irma documentation · irma documentation, release 1.1.1 irma is an asynchronous & customizable...

IRMA DocumentationRelease 1.1.1

Quarkslab

April 15, 2015

Contents

1 Table of Contents 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411.4 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

2 Resources 47

3 Screenshots 493.1 Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493.2 Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

i

IRMA Documentation, Release 1.1.1

IRMA is an asynchronous & customizable analysis system for suspicious files.

This guide will explain how to set up IRMA, use it and customize it at will.

Contents 1


2 Contents

CHAPTER 1

Table of Contents

1.1 Introduction

This is an introductory chapter to IRMA. It recalls IRMA’s overall architecture, hardware required to run it and therecommended order for installing the IRMA’s components.

Note: This chapter is common for all components of IRMA platform. You can skip directly to the next chapter if youhave already read this introductory chapter.

1.1.1 Purpose

IRMA intends to be an open-source platform designed to help identifying and analyzing malicious files.

However, today’s defense is not only about learning about a file, but it is also getting a fine overview of the incidentyou dealt with: where / when a malicious file has been seen, who submitted a hash, where a hash has been noticed,which anti-virus detects it, ...

An important value with IRMA comes from you keep control over where goes and who gets your data. Once youinstall IRMA on your network, your data stays on your network.

Each submitted files is analyzed in various ways. For now, we focus our efforts on multiple anti-virus engines, but weare working on other “probes” (feel free to submit your own).

1.1.2 File Analysis Process

1. An analysis begins when a user uploads files to the Frontend.

2. Frontend checks for existing files and results in mongodb. If needed, it stores the new files and calls asyn-chronously scan jobs on Brain.

3. Brain worker sends as much subtasks to Probe(s) as needed.

4. Probe workers process their jobs and send back results to Brain.

5. Brain sends results to Frontend.

3


1.1.3 Infrastructure Overview

A drawing is better than a lot of explanations (sometimes ;)

4 Chapter 1. Table of Contents


1.1.4 Hardware requirements

IRMA platform is divided in three major components: the Frontend, the Brain and one or multiple Probes.

These three components can be installed on a unique host or on multiple hosts, according to the kind of probes youare using.

The Frontend and the Brain must be installed on a GNU/Linux system 1. We recommend to use a Debian Stabledistribution which is supported and known to work.

According to the kind of probes and their dependencies, each analyzers can be installed on a separate hosts or share

1 Theorically, it should be possible, with some efforts, to make IRMA work on Microsoft Windows systems as most of the components used forthe platform are known to work or to have equivalents on these systems.

1.1. Introduction 5


the same host as far as they do not interfere with each other 2. So forth, only Debian Stable and Microsoft Windows 7hosts have been tested.

We can not give you any specific numbers. On one hand we managed to run the whole IRMA platform on a singlemachine by hosting it with multiple systems inside virtual machines: this setup gives fairly high throughput as longas it has reasonable IO (ideally, SSDs), and a good amount of memory (our setup was an i7 cpu with 16 GB ram onregular drives (at least 200 GB required), on the other hand, a lighter version of the system with the three parts together3 was successfully installed on a single virtual machine (1 GB of Ram and 4 virtual processors).

For a large company, in theory, given a single high-memory machine, with 16+ cores, and SSDs, you could run IRMAplatform and bear the workload load with reasonable response time.

1.2 Installation

We provide some scripts to automate the installation of IRMA for different uses cases. So forth, the automatedinstallation is known to work only from GNU/Linux platforms as it uses Ansible which does not support Windowssystems at the time of writing.

1.2.1 Automated Install

IRMA platform can be easily installed with a set of ansible roles and playbooks. It will help you to build, install ormaintain different setups.

Requirements

• Ansible 1.8 or higher;

Ansible scripts

Get IRMA ansible scripts on github:

$ git clone https://github.com/quarkslab/irma-ansible

Install the dependencies via Ansible Galaxy repository:

$ ansible-galaxy install -r ansible-requirements.yml # eventually, add ’--force’ to overwrite installed roles

Predefined Environments

There are 3 different IRMA setups available:

Testing Environment

This environment is used to install the whole IRMA platform in a single virtual machine, merely for testing purposes.

2 For instance, we managed to host several GNU/Linux anti-viruses on an unique probe by preventing it to launch daemons at startup. This isdifficult for Microsoft systems on which it is not recommended to install multiple anti-viruses on a single host.

3 with a limited set of probes


http://www.ansible.com

http://www.ansible.com

https://galaxy.ansible.com/


Requirements

• Vagrant 1.5 or higher has to be installed.

• As the installation work only for Virtualbox, you will need to install it.

Setup Run the following command in the directory containing the Vagrantfile:

$ vagrant up

Vagrant will launch a VM and install IRMA on it. It can take a while (from 15 to 30 min) depending on the amount ofRAM you have on your computer, the hard disk drive I/O speed and your Internet connection speed.

Once the installation has completed, IRMA’s frontend interface will be available at http://172.16.1.30.

Production environment

This environment is used to install IRMA on production-ready Debian servers.

Requirements

• One or multiple 64-bit Debian 7 servers.

Preparing servers Create an account that is going to be used to provision IRMA on the server via Ansible, or useone which has already been created. To speed up provisioning, you can:

• Authorize your SSH key for password-less authentication (optional):

# On your local machine$ ssh-copy-id user@hostname # -i if you want to select your identity file

• If you do not want to have to type your password for sudo command, consider adding your user to sudoers,using visudo command (optional):

user ALL=(ALL) NOPASSWD: ALL

Configure for your installation Modify settings in playbooks/group_vars/all especially thedefault_ssh_keys: section. You will need to add your public keys for SSH password-less connection tothe default irma server user.

Configuration file used by the brain, the frontend and the probes applications are generated with default val-ues that are specified in playbooks/group_vars/brain, playbooks/group_vars/frontend andplaybooks/group_vars/probe respectively. Make sure to adapt xxx_deployment_configs variablesaccordingly to your installation. It is recommended to change all the default passwords defined in group_vars/*configuration files (password variables for most of them).

Finally, you will need to customize the hosts/example file and adapt it to describe your own server infrastruc-ture. There is three sections, one for each server role (frontend, brain, probe). Please refer to Ansible Inventorydocumentation for the expected syntax.

Run the Ansible Playbook To run the main playbook with the hosts/example file you have defined, use thefollowing command. Ansible will ask you the sudo password (-K option).

$ ansible-playbook -i ./hosts/example playbooks/playbook.yml -u <your_sudo_username> -K

1.2. Installation 7

http://www.vagrantup.com/

https://www.virtualbox.org/

http://172.16.1.30

https://www.debian.org

http://docs.ansible.com/intro_inventory.html#inventory

http://docs.ansible.com/intro_inventory.html#inventory


To run one or more specific actions and avoid running all the playbook, you can use tags. For example, if you want tore-provision Nginx, run the same command, but append --tags=nginx. You can combine multiple tags separatedwith commas.

Deploy a new version of IRMA Assuming that you have already provisioned and deployed a version of IRMA,which you want to upgrade, you will need to run the deployment script:

$ ansible-playbook -i ./hosts/example ./playbooks/deployment.yml -u irma

Make sure to replace irma with the default user if you have changed it in the group_vars/all file.

Access your IRMA installation Once the provisioning and the deployment have finished, you should be able toperform scans and get their results via the frontend hostname you specified.

Development environment

This environment has been designed to help you to modify IRMA’s components and redeploy and test them. In thissetup, everything is installed in a single virtual machine with sources rsync-ed between the host and the guest.

Requirements

• Vagrant 1.5 or higher has to be installed

• As the installation work only for Virtualbox, you will need to install it

• Rsync to synchronize directories from host to VMs

• Read the Ansible introduction

Create the right environment Clone IRMA repositories:

$ git clone --recursive https://github.com/quarkslab/irma-frontend$ git clone --recursive https://github.com/quarkslab/irma-brain$ git clone --recursive https://github.com/quarkslab/irma-probe

If you are interested in using Vagrant, be sure to have the following directory layout:

# all in the same directory|+--- irma-frontend+--- irma-probe+--- irma-brain[...]+--- irma-ansible

Note: This directory layout can be modified, see share_* variables from environments/dev.yml andenvironments/allinone_dev.yml files.

Run Vagrant and create your VMs To initialize and provision the Virtualbox VM, run vagrant up--no-provision from the irma-ansible directory. The template will be downloaded automatically and con-figured using environments/dev.yml file.


http://www.vagrantup.com/

https://www.virtualbox.org/

https://rsync.samba.org/

http://docs.ansible.com/intro.html

http://vagrantup.com


$ VM_ENV=your_environment_name vagrant up --no-provision

Note: Optionally, if you want to use your own environment, create it in environments directory and run:

$ VM_ENV=your_environment_name vagrant up --no-provision

Configure your .ini filesNote: You can bypass this step, as this provisioning is sync with default username and password used in (fron-tend|brain|probe) config files.

As your config/*.ini file are transferred from host to VMs, you will need to modify them individually inthe irma-frontend, irma-probe and irma-brain repositories to match the user and password defined inplaybooks/group_vars/*.

Provision your VMs Due to Ansible limitations using parallel execution, you’ll need to launch the provision Vagrantcommand only for one VM:

$ vagrant provision frontend.irma

The provisioning and deployment will apply to all of your VMs.

Modify your host and open IRMA frontend Then, for proper use, update your /etc/hosts file and add:

172.16.1.30 www.frontend.irma

Then, with your web browser, IRMA allinone is available at www.frontend.irma.

Sync files between host and guest Once rsync is installed inside your virtual machine and your environment iscorrectly set. You could easily sync your code with:

$ vagrant rsync # or vagrant rsync-auto to automatically initiates an rsync# transfer when changes are detected

Then, reload the modified application.

Using Debian repos

If you planned to use only Debian official repository, you’ll need to change in playbooks/group_vars/all:

default_use_debian_repo: yes # no is the default value

1.2.2 Manual Installation

In some specific cases where automatic install is not possible, you should go with manual installation.

Each major component of the IRMA platform comes with their own python-based application. As the Brain is thenerve center of the whole platform, it is recommended to install it first before installing other components. One canthen install either the Frontend or the Probes he wants.

Please refer to specific documentation for the manual installation process for each component.

1.2. Installation 9

http://www.frontend.irma


Brain

The Brain is a python-based application that only dispatches analysis requests from different frontends 4 to the avail-able Probes. Analyses are scheduled by the Brain on Probes through Celery, an open source task framework forPython.

Architecture

Let us recall first the inner architecture of the Brain. It uses multiple technologies with a specific purpose each:

• a Celery worker that handles scan requests from Frontends and results returned by the Probes.

• a Redis and a RabbitMQ that are used by Celery respectively as a backend and as a broker for task queues andjob queues used to schedule tasks for Probes (for scan jobs) and the Frontend (for scan results).

• a FTP server with TLS enabled where files to be scanned are uploaded by Frontends and downloaded byProbes,

Installing and Configuring RabbitMQ

The following explains how to install and to setup RabbitMQ for your setup.

Install RabbitMQ RabbitMQ server can be installed with this command on Debian:

$ sudo apt-get install rabbitmq-server

Configuring RabbitMQ RabbitMQ serves all components of IRMA platform. Each component has their ownvirtual host (i.e., message queue where to get data), a username and a password.

To configure RabbitMQ for IRMA platform, you have to create users, vhosts and add permissions for each user tocorresponding vhost. To easily create virtual hosts and users, we provide scripts in extras/ directory:

$ sh ./extras/scripts/rabbitmq/rmq_adduser.shUsage: sudo rmq_adduser.sh <user> <password> <vhost>

For instance, to create 3 users with the following parameters, one can do:

User-name

Password VirtualHost

Command

brain brain-rmq-password

mqbrain sudo ./extras/scripts/rabbitmq/rmq_adduser.shbrain brain-rmq-password mqbrain

probe probe-rmq-password

mqprobe sudo ./extras/scripts/rabbitmq/rmq_adduser.shprobe probe-rmq-password mqprobe

fron-tend

frontend-rmq-password

mqfron-tend

sudo ./extras/scripts/rabbitmq/rmq_adduser.shfrontend frontend-rmq-password mqfrontend

The script simply execute the following three commands:

$ sudo rabbitmqctl add_user <username> <password>$ sudo rabbitmqctl add_vhost <vhostname>$ sudo rabbitmqctl set_permissions -p <vhostname> <username> ".*" ".*" ".*"

4 This feature is not ready yet, we are currently working on its implementation.



Warning: ImportantMake sure to note down the username, the password and the virtual host you just defined. You will be asked toretype them on each application configuration file (brain, frontend and probe)

Note: Disclaimer

Please ensure that only trusted sources can communicate with your RabbitMQ server, by setting up firewall rules forinstance, as your RabbitMQ may be exposed to Internet.

Verifying RabbitMQ configuration We can verify that the RabbitMQ server has taken into account our modifica-tions with some commands:

Checking for vhosts$ sudo rabbitmqctl list_vhostsListing vhosts ...mqbrain/mqfrontendmqprobemqadmin...done.

If the defined virtual host are not listed by the above command, please execute once more the script.

Checking for users$ sudo rabbitmqctl list_usersListing users ...probe []brain []guest [administrator]frontend []...done.

If the defined users are not listed by the above command, please execute once more the script.

Changing password If you do not remember the password you just typed, you can change it with rabbitmqctlcommand:

$ sudo rabbitmqctl change_password brain brain-rmq-passwordChanging password for user "brain" ......done.

Restarting the service You may want to restart the service. Thus, the following command can be done:

$ sudo invoke-rc.d rabbitmq-server restart

Installing and configuring Pure-ftpd

A FTP server with TLS is used to store file uploaded by Frontends and meant to be analyzed by Probes. We describein the following how to set up pure-ftpd.

1.2. Installation 11


Installing pure-ftpd$ sudo apt-get install pure-ftpd

Creating FTP specific users and groups$ sudo groupadd ftpgroup$ sudo useradd -g ftpgroup -d /dev/null -s /etc ftpuser

Configure pure-ftpd We provide some template scripts to configure pure-ftpd in the extras/pure-ftpddirectory. These templates should be copied as is in the pure-ftpd configuration folder.

$ sudo cp extras/pure-ftpd/conf/* /etc/pure-ftpd/conf/$ sudo ln -s /etc/pure-ftpd/conf/PureDB /etc/pure-ftpd/auth/50puredb

Generate Certificate So far, we have not set up support for TLS yet. To enable TLS, one must generate a self signedcertificate:

$ sudo mkdir -p /etc/ssl/private/$ cd /etc/ssl/private/$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:4096 -subj "/CN=$(hostname --fqdn)/" -keyout pure-ftpd.pem -out pure-ftpd.pem$ sudo chmod 600 pure-ftpd.pem

Create FTP accounts The creation of virtual users (or FTP accounts) could be done through the provided script inextras/scripts/pure-ftpd/ftpd-adduser.sh:

$ sh extras/scripts/pure-ftpd/ftpd-adduser.shUsage: sudo ftpd-adduser.sh <user> <virtualuser> <chroot home>

The frontends need an account with /home/ftpuser/<frontend-name> as home directory and a single ac-count is shared between probes. The later needs to access to all frontends, thus the associated home directory issimply /home/ftpuser/. For instance, a frontend named frontend-irma, execute the following to create thedirectories:

$ sudo mkdir -pv /home/ftpuser/frontend-irmamkdir: created directory ‘/home/ftpuser’mkdir: created directory ‘/home/ftpuser/frontend-irma’$ sudo chown -R ftpuser:ftpgroup /home/ftpuser

These commands create the accounts for this frontend first and secondly for probes:

$ sudo extras/scripts/pure-ftpd/ftpd-adduser.sh frontend-irma ftpuser /home/ftpuser/frontend-irma[ enter twice a password to be used for frontend, for example frontend-ftp-password]$ sudo extras/scripts/pure-ftpd/ftpd-adduser.sh probe ftpuser /home/ftpuser/[ enter twice a password to be used for frontend, for example probe-ftp-password]

Checking your configuration Listing your users should output something like this:

$ sudo pure-pw listfrontend-irma /home/ftpuser/frontend-irma/./probe /home/ftpuser/./



Restart the service You may want to restart the service:

$ sudo invoke-rc.d pure-ftpd restart

Installation

The Brain must be installed on a GNU/Linux distribution. With some efforts, it should be possible to run it on aMicrosoft Windows system, but this has not been tested yet.

Installation from source This section describes how to get the source code of the application for the Brain and toinstall it.

Downloading the source code from github.com The source code is hosted on github.com. One can fetch an up-to-date version with the following commands. Let us note that there is a common submodule named irma-commonthat could be fetched automatically with the --recursive option:

$ git clone --recursive https://github.com/quarkslab/irma-brain

Building the source distribution We provide a Makefile that helps to build the python source distribution. Bydefault, the source distribution will be available in the dist/ directory. The created archive will be used to install theapplication.

$ make source$ ls dist/irma-brain-app-1.0.4.tar.gz

Note: Required tools to build the source distribution

Few tools are needed to build the python source distribution and to install the application:

• make

• python-pip

• python-setuptools

Installing the source distribution To be able to install the python source distribution, we assume that you havealready installed the following software on your system. The pre-requisites are recalled here.

Pre-requisites We assume that you have a command line interface on your system with the following tools installed:

• python 2.7.x (see Python for Windows for prebuild MSI installer)

• python-pip (see Install pip for the recommended way to install pip package manager)

Furthermore, we assume that you have created an user irma that will be used to run the python application.

Note: On GNU/Linux, one can create the user (and the group) irma with:

$ sudo adduser --system --no-create-home --group irma


https://www.python.org/downloads/windows/

https://pip.pypa.io/en/latest/installing.html


Installation on GNU/Linux On GNU/Linux system, we will assume that the code for the Brain will be installed in/opt/irma/irma-brain directory, which is the configured default installation directory.

$ pip install --install-option="--install-base=/opt/irma/irma-brain" irma-brain-app-1.1.0.tar.gz[...]

Since the way we packaged the python application does not so support automatic installation of dependencies, weneed to install them manually:

$ pip install -r /opt/irma/irma-brain/requirements.txt[...]

If everything has gone well, you should have installed the python application on your system. The next step is to installthe other components it relies on and finally to configure it for your platform.

Configuration

The configuration file is located at config/brain.ini in the installation directory.

From the sources At the root of the installation directory, the script setup.py asks you questions to configure theapplication for your needs. To fit your setup, you must provide the parameters configured previously on the RabbitMQserver and the Pure-FTPd server.

For GNU/Linux systems:

$ python setup.py configure --applicationrunning configure

Welcome to IRMA brain application configuration script.

The following script will help you to create a new configuration forIRMA frontend application.

Please answer to the following questions so this script can generate the filesneeded by the application. To abort the configuration, press CTRL+D.

> Do you want to enable syslog logging? (experimental) (y/N)> What is the hostname of your RabbitMQ server? [127.0.0.1]> What is the vhost defined for the brain on your RabbitMQ server? [mqbrain]> What is the username for this vhost on your RabbitMQ server? [brain]> What is the password for this vhost on your RabbitMQ server? brain-rmq-password> What is the vhost defined for the probes on your RabbitMQ server? [mqprobe]> What is the username for this vhost on your RabbitMQ server? [probe]> What is the password for this vhost on your RabbitMQ server? probe-rmq-password> What is the vhost defined for the frontend on your RabbitMQ server? [mqfrontend]> What is the username for this vhost on your RabbitMQ server? [frontend]> What is the password for this vhost on your RabbitMQ server? frontend-rmq-password> What is the hostname of your FTPs server? [127.0.0.1]> What is the username defined for the probes on your FTP server? probe> What is the password defined for the probes on your FTP server? probe-ftp-password

When finished, one can note that the config/brain.ini file has been modified with values we typed.

Note: We recall in the following the meaning of each field in config/brain.ini:

Section Key Type Default Description

log syslog integer 0 enable rsyslog (experimental)Continued on next page



Table 1.1 – continued from previous pageSection Key Type Default Description

prefix string irma-brain: prefix to append to rsyslog entries

broker_brain

host string hostname for the RabbitMQ serverport integer 5672 port for the RabbitMQ servervhost string virtual host configured for brainusername string username used for brain on the RabbitMQ serverpassword string password used for brain on the RabbitMQ serverqueue string queue to poll new tasks on the RabbitMQ server

broker_probe

host string hostname for the RabbitMQ serverport integer 5672 port for the RabbitMQ servervhost string virtual host configured for probesusername string username used for probes on the RabbitMQ serverpassword string password used for probes on the RabbitMQ serverqueue string queue to poll new tasks on the RabbitMQ server

broker_frontend

host string hostname for the RabbitMQ serverport integer 5672 port for the RabbitMQ servervhost string virtual host configured for frontendusername string username used for frontend on the RabbitMQ serverpassword string password used for frontend on the RabbitMQ serverqueue string queue to poll new tasks on the RabbitMQ server

sqldb

dbms string sqlite dbapi enginedialect string sqlalchemy dialectusername string database usernamepassword string database passwordhost string database hostdbname string /var/irma/ db/brain.db database nametables_prefix string database tables prefix

ftp_brain

host string hostname for the FTP serverport integer 21 port for the FTP serverusername string username used by probe on the FTP serverpassword string password used by the probe on the FTP server

Generate a SQLite database for scan tracking You could easily generate the user database by running the follow-ing command. The path of the database is taken from the configuration file and the folder where the database is goingto be stored must be created beforehand.

$ python -m scripts.create_userusage: create_user <username> <rmqvhost> <ftpuser> [quota]

with <username> a string<rmqvhost> the rmqvhost used for the frontend<ftpuser> the ftpuser used by the frontend[quota] the number of file scan quota 0 for disabled (default: 0)

example: create_user test1 mqfrontend frontend

To create an entry in the database for the frontend named frontend-irma and which uses the frontend-rmqvirtual host on the RabbitMQ server, simply run the following commands:

$ python -m scripts.create_user frontend-irma frontend-rmq frontend-irma 0

The quota sets to 0 simply disable the quota system and you will be able to launch as many analyzes as you want.

Note: There is a limitation due to SQLite. The folder where the database is stored, plus the database file must be



writable by the user running the worker:

$ sudo chown irma:irma db/brain.db$ sudo chmod a+w /opt/irma/irma-brain

Installation Checks

Celery Workers Before going further, you should check that the python application manages to communicate withthe RabbitMQ server and the Redis server through Celery. To ensure that, from the installation directory, execute theCelery worker:

On GNU/Linux:

$ celery worker --app=brain.tasks:scan_app --workdir=/opt/irma/irma-brain

-------------- celery@irma-brain v3.1.13 (Cipater)---- **** -------- * *** * -- Linux-3.2.0-4-amd64-x86_64-with-debian-7.5-- * - **** ---- ** ---------- [config]- ** ---------- .> app: scantasks:0x1f4c2d0- ** ---------- .> transport: amqp://brain:**@127.0.0.1:5672/mqbrain- ** ---------- .> results: amqp://brain:[email protected]:5672/mqbrain- *** --- * --- .> concurrency: 4 (prefork)-- ******* ------- ***** ----- [queues]-------------- .> brain exchange=celery(direct) key=brain

[2014-08-21 14:54:49,633: WARNING/MainProcess] celery@brain ready.

$ celery worker --app=brain.tasks:results_app --workdir=/opt/irma/irma-brain

-------------- celery@irma-brain v3.1.13 (Cipater)---- **** -------- * *** * -- Linux-3.2.0-4-amd64-x86_64-with-debian-7.5-- * - **** ---- ** ---------- [config]- ** ---------- .> app: restasks:0x19fe0d0- ** ---------- .> transport: amqp://probe:**@127.0.0.1:5672/mqprobe- ** ---------- .> results: disabled- *** --- * --- .> concurrency: 4 (prefork)-- ******* ------- ***** ----- [queues]-------------- .> results exchange=celery(direct) key=results

[2014-08-21 14:55:59,079: WARNING/MainProcess] celery@irma-brain ready.

If your Celery worker does not output something similar to the above output, you should check twice the parametersin the application configuration file you are using.

FTP-SSL accounts Additionnally, if you have configured IRMA to use FTP-ssl, you can check whether the config-ured account is valid. On Debian, this can be done with the ftp-ssl package:



$ sudo apt-get install ftp-ssl[...]$ ftp-ssl localhostConnected to localhost.220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------220-You are user number 1 of 50 allowed.220-Local time is now 18:55. Server port: 21.220-This is a private system - No anonymous login220-IPv6 connections are also welcome on this server.220 You will be disconnected after 15 minutes of inactivity.Name (brain:root): probe-ftp500 This security scheme is not implemented234 AUTH TLS OK.[SSL Cipher DHE-RSA-AES256-GCM-SHA384]200 PBSZ=0200 Data protection level set to "private"331 User probe OK. Password requiredPassword: probe-ftp-password230 OK. Current directory is /Remote system type is UNIX.Using binary mode to transfer files.ftp>

$ ftp-ssl localhostConnected to localhost.220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------220-You are user number 1 of 50 allowed.220-Local time is now 18:55. Server port: 21.220-This is a private system - No anonymous login220-IPv6 connections are also welcome on this server.220 You will be disconnected after 15 minutes of inactivity.Name (brain:root): frontend-ftp500 This security scheme is not implemented234 AUTH TLS OK.[SSL Cipher DHE-RSA-AES256-GCM-SHA384]200 PBSZ=0200 Data protection level set to "private"331 User probe OK. Password requiredPassword: frontend-ftp-password230 OK. Current directory is /Remote system type is UNIX.Using binary mode to transfer files.ftp>

Running Brain at startup

We have ensured that the freshly installed Brain is ready to be integrated to your IRMA platform. Now, we can goa step further and make the celery worker to run automatically when the system starts up so you will not need tomanually relaunch it every time.

We provide several template scripts in the extras/ repository located at the root of the installation directory. Wedescribe in the following how to setup daemons on a GNU/Linux system.

Daemon on GNU/Linux At the moment, we only support daemonizing with init.d scripts. The following de-scribes the procedure to make a service run Celery workers on Debian distribution.



Installing the services First, copy the scripts in extras/init.d/ and extras/default respectively in/etc/init.d and /etc/defaults.

$ sudo cp extras/init.d/celeryd.brain /etc/init.d/celeryd.brain$ sudo cp extras/init.d/celeryd.results /etc/init.d/celeryd.results$ sudo cp extras/default/celeryd.brain /etc/default/celeryd.brain$ sudo cp extras/default/celeryd.results /etc/default/celeryd.results

Configuring the services Update the service parameters in /etc/default/celeryd.brain and/etc/default/celeryd.brain to match your setup. In most cases, you should pay attention to the follow-ing fields:

Fields Default DescriptionCELERYD_NODES Name given to the workerCELERYD_CHDIR /opt/irma/irma-brain/ Installation directory for the workerCELERYD_USER irma Username used to execute the Celery workerCELERYD_GROUP irma Group used to execute the Celery worker

Registering the services Finally, fix the permission for the /etc/init.d/celeryd.brain and the/etc/init.d/celeryd.results scripts and register the two services:

$ sudo chmod u+x /etc/init.d/celeryd.brain$ sudo chmod u+x /etc/init.d/celeryd.results$ update-rc.d celeryd.brain defaults$ update-rc.d celeryd.results defaults

You can check that the celery daemon is running properly by launching it and by consulting the system logs:

$ sudo invoke-rc.d celeryd.brain start$ sudo invoke-rc.d celeryd.results start$ sudo cat /var/log/celery/*.log[...][2014-04-30 13:35:03,949: WARNING/MainProcess] worker1@irma-brain ready.[...]

Frontend

The Frontend handles scan submission to the Brain, stores the results of the scanned files. These results can bedisplayed through a web graphical user interface or via the command line interface.

Architecture

Let us recall first the inner architecture of the Frontend. It uses multiple technologies with each a specific purpose:

• A client through which an user submits a file and get the analysis results. There are two clients bundled in therepository: a web user interface and a command-line client.

• A python-based restful API, served by a nginx web server and a uWSGI application server. It gets the results ofa file scan by querying a database.

• A worker that will handle scan submission to the Brain and store the results of analyzes scheduled by the Brain.The worker relies on Celery, a python-based distributed task queue.

• An hybrid database server (SQL/mongodb) is used to store results of analyzes made on each file submitted eitherby the web graphical interface or the CLI client.



Installation

Currently, a quick install through vagrant and ansible scripts is supported. It is the recommended way to proceed butif you want to go more into the details, here is the manual install guide.

The Frontend must be installed on a GNU/Linux system. With some efforts, it should be possible to run it on aMicrosoft Windows system, but this has not been tested yet.

This section describes how to get the source code of the application and to install it.

Downloading the source code from github The source code is hosted on github.com. One can fetch an up-to-dateversion with the following commands. Let us note that there is a common submodule named irma-common thatcould be fetched automatically with the --recursive option:

$ git clone --recursive https://github.com/quarkslab/irma-frontend

Building the web client The first step that should be performed when installing the frontend from the code sourceis to build the web client which is composed of static HTML files mixed with javascript web framework (in particular,AngularJS).

One must install first some tools that are necessary to build the whole web client. At the time of writing, Node.js isavailable in the default Debian Wheezy repositories (if not, add wheezy-backports repository):

$ echo "deb http://ftp.fr.debian.org/debian/ wheezy-backports main contrib non-free" | sudo tee /etc/apt/source.list.d/wheezy-backports.list[...]$ sudo apt-get install nodejs[...]$ curl https://www.npmjs.org/install.sh | sudo sh[...]

Once the tools installed, you can build the static files for the web user interface with the following commands, executedfrom the installation directory:

$ cd irma-frontend/web$ npm install$ node_modules/.bin/bower install$ node_modules/.bin/gulp dist

A new directory or an updated directory web/dist should appear now with HTML and javascript files that havebeen minified and “obfuscated” by gulp. For more details on the web interface, please refer to the dedicated chapter.


$ make source$ ls dist/irma-frontend-app-1.1.0.tar.gz



• make

• python-pip




Installing the source distribution To be able to install the python source distribution, we assume that you havealready installed the following software on your system. The prerequisites are recalled here.

Prerequisites We assume that you have a command line interface on your system with the following tools installed:

• python 2.7.x





Installation on GNU/Linux On GNU/Linux system, we will assume that the code for the Frontend will be installedin /opt/irma/irma-frontend directory.

$ pip install --install-option="--install-base=/opt/irma/irma-frontend" irma-frontend-app-1.1.0.tar.gz[...]

Since the way we packaged the python application does not support automatic installation of dependencies, we needto install them manually:

$ pip install -r /opt/irma/irma-frontend/requirements.txt[...]

If everything has gone well, you should have installed the python application on your system. The next step is toconfigure it for your platform and to install the other components it relies on.

Configuration

The configuration file is located at config/frontend.ini in the installation directory.

At the root of the installation directory, the script setup.py asks you questions to configure the application for yourneeds. To fit your setup, you must provide the parameters configured on the Brain.


$ python setup.py configure --applicationrunning configure

Welcome to IRMA frontend application configuration script.

The following script will help you to create a new configuration forIRMA frontend application.


> Do you want to enable syslog logging? (experimental) (y/N)> What is the hostname of your mongodb server? [127.0.0.1]> What is the port used by your mongodb server? [27017]> What is the sample storage path? [/var/irma/samples/]




> What is the hostname of your RabbitMQ server? [brain.irma]> What is the vhost defined for the brain on your RabbitMQ server? mqbrain> What is the username for this vhost on your RabbitMQ server? brain-rmq-password> What is the password for this vhost on your RabbitMQ server? brain> What is the vhost defined for the frontend on your RabbitMQ server? mqfrontend> What is the username for this vhost on your RabbitMQ server? frontend> What is the password for this vhost on your RabbitMQ server? frontend-rmq-password> What is the hostname of your FTPs server? [brain.irma]> What is the username defined for the frontend on your FTP server? frontend> What is the password defined for the frontend on your FTP server? frontend-ftp-password

When finished, one can note that the config/frontend.ini file has been modified with values we typed.

Note: We recall in the following the meaning of each field in config/frontend.ini:


log syslog integer 0 enable rsyslog (exper-imental)

prefix string irma-frontend: prefix to append torsyslog entries

mongodb

host string hostname of the mon-godb server

port integer 27017 port on which themongodb server lis-tens

dbname string irma name of the databasefor IRMA

collections_ prefixstring irma prefix for mongodb

collections

sqldb

dbms string sqlite dbapi enginedialect string sqlalchemy dialectusername string database usernamepassword string database passwordhost string database hostdbname string /var/irma/db/ fron-

tend.dbdatabase name

tables_prefix string database tables prefixsamples_storage path string /var/irma/ samples Samples storage pathcelery_brain timeout integer 10 (sec) time before consider-

ing that the brain hastimed-out

celery_frontend timeout integer 10 (sec) time before consider-ing that the frontendhas timed-out

broker_brain

host string hostname for the Rab-bitMQ server

port integer 5672 port for the RabbitMQserver

vhost string virtual host config-ured for brain

username string username used forbrain on the Rab-bitMQ server

Continued on next page



Table 1.2 – continued from previous pageSection Key Type Default Description

password string password used forbrain on the Rab-bitMQ server

queue string queue to poll newtasks on the Rab-bitMQ server

broker_frontend

host string hostname for the Rab-bitMQ server

port integer 5672 port for the RabbitMQserver

vhost string virtual host config-ured for this frontend

username string username used for thisfrontend on the Rab-bitMQ server

password string password used for thisfrontend on the Rab-bitMQ server

queue string queue to poll newtasks on the Rab-bitMQ server

ftp_brain

host string hostname for the FTPserver

port integer 21 port for the FTP serverusername string username used by this

frontend on the FTPserver

password string password used by thisfrontend on the FTPserver

cron_frontend

clean_db_file_max_age

integer 2 remove file after Xdays

clean_db_cron _hour integer 0 cron hour settingsclean_db_cron_minute

integer 0 cron minute settings

clean_db_scan_day_of_week

integer * cron day of week set-tings

Running Frontend worker at startup

We have ensured that the freshly installed Frontend worker is ready to be integrated to your IRMA platform. Now,we can go a step further and make it run automatically when the system starts up so you will not need to relaunch itmanually every time.

We provide several template scripts in the extras/ repository located at the root of the installation directory. Wedescribe in the following how to setup daemons on GNU/Linux systems, specifically Debian systems.

Daemon on GNU/Linux At the moment, we only support daemonizing with init.d scripts. The following de-scribes the procedure to run make a service run Celery workers on Debian distribution.



Installing the service First, copy the scripts in extras/init.d/ and extras/default respectively in/etc/init.d and /etc/defaults.

$ sudo cp extras/init.d/celeryd.probe /etc/init.d/celeryd.frontend$ sudo cp extras/default/celeryd.probe /etc/default/celeryd.frontend

Configuring the service Update the service parameters in extras/default/celeryd.frontend to matchyour setup. In most cases, you should pay attention to the following fields:

Fields Default DescriptionCELERYD_NODES frontend Name given to the probeCELERYD_CHDIR /opt/irma/irma-frontend/ Installation directory for the frontendCELERYD_USER irma Username used to execute the Celery workerCELERYD_GROUP irma Group used to execute the Celery worker

Registering the service Finally, fix the permission for the /etc/init.d/celeryd.frontend script and reg-ister the service:

$ sudo chmod u+x /etc/init.d/celeryd.frontend$ update-rc.d celeryd.frontend defaults


$ sudo invoke-rc.d celeryd.probe start$ sudo cat /var/log/celery/*.log[...][2014-04-30 13:35:03,949: WARNING/MainProcess] worker1@frontend ready.[...][2014-04-30 13:35:04,205: WARNING/MainProcess] worker2@frontend ready.[...][2014-04-30 13:35:03,949: WARNING/MainProcess] worker3@frontend ready.

Installing MongoDB server

The Frontend relies on a MongoDB to store the results of all files scanned. On Debian, one can install a mongodbserver in few commands:

$ sudo apt-get install mongodb-server[...]

Please refer to the documentation of your preferred distribution to install a mongodb server on it.

Note: Make it listen only on loopback

Edit /etc/mongodb.conf to listen only on loopback interface. You should have the following configuration:

bind_ip 127.0.0.1port = 27017

Installing SQL server

The Frontend relies on a SQL database to keep track of all scans info. On Debian, one can install a SQL server in fewcommands:



in development environment, prefer sqlite server:

$ sudo apt-get install sqlite3[...]

in production environment, prefer postgres server:

$ sudo apt-get install postgresql[...]

For PostgreSQL, extra steps for configuring the database and a user is required. Then adapt the frontend configurationfile to allow frontend to connect to the SQL database. The tables are automatically created on celery daemon / uwsgistartup.

Installing and configuring uWSGI

The restful API is served by an uWSGI application server. This section will explain how to install an uWSGI serverand configure it for the Frontend.

Installation On Debian, installing uWSGI to serve a python application is pretty straightforward:

$ sudo apt-get install uwsgi uwsgi-plugin-python[...]

Please refer to the documentation of your preferred distribution to install an uWSGI server on it.

Configuration We provide several template scripts in the extras/ repository located at the root of the installationdirectory. Templates for uWSGI are located in extras/uwsgi/. Copy the file to uWSGI app-available folder.

$ sudo cp extras/uwsgi/frontend-api.xml /etc/uwsgi/apps-available/$ sudo vi /etc/uwsgi/apps-available/frontend-api.xml[...]

The template is configured for a default installation of the frontend in /opt/irma/irma-frontend. You mayneed to edit it for you setup. In particular, please ensure that the <chdir> tag points to your installation directory.

<uwsgi><plugin>python</plugin><chdir>/opt/irma/irma-frontend</chdir><app mountpoint="/_api">

<script>./frontend/web/api.py</script></app><master/>

</uwsgi>

Activate the application By default, all application in apps-available are not activated. One can enable theapplication frontend-api.xml by creating a soft-link into the apps-enabled folder:

$ sudo ln -s /etc/uwsgi/apps-available/frontend-api.xml /etc/uwsgi/apps-enabled/frontend-api.xml

Relaunch the service The final step is to relaunch the service:

$ sudo invoke-rc.d uwsgi restart



Installing and configuring nginx

In the Frontend, we use a nginx web server to serve the uWSGI application and the static web site that query the APIin order to get results of scanned files and to present them to the user.

Installation On Debian, installing nginx is done with few commands:

$ sudo apt-get install nginx[...]

Please refer to the documentation of your preferred distribution to install an uWSGI server on it.

Configuration We provide several template scripts in the extras/ repository located at the root of the installationdirectory. Templates for nginx are located in extras/nginx/. Copy the file to sites-available in nginxconfiguration folder:

$ sudo cp extras/nginx/frontend /etc/nginx/sites-available/

The template is configured for a default installation of the frontend in /opt/irma/irma-frontend/. You mayneed to edit it for you setup. In particular, please ensure that the root directive points to the folder web/dist (for aproduction ready version of the web site) or web/app (for a development version of the web site) in your installationdirectory.

Activate the web site By default, all websites in apps-available are not activated. One can enable the websitedescribed in frontend configuration file by creating a soft-link into the sites-enabled folder:

$ sudo ln -s /etc/nginx/sites-available/frontend /etc/nginx/sites-enabled/frontend

Note: The case of HTTPs

A template to set up a HTTPs server with nginx is also provided in the extras/nginx folder. Here is the way tosetup it:

$ sudo cp extras/nginx/frontend-https /etc/nginx/sites-available/$ sudo ln -s /etc/nginx/sites-available/frontend-https /etc/nginx/sites-enabled/frontend-https$ sudo mkdir /etc/nginx/certificates/$ cd /etc/nginx/certificates/

Generate the required Diffie Hellman Ephemeral Parameters:

$ sudo openssl dhparam -out dhparam.pem 4096

Finally, generate a self signed certificate:

$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:4096 -subj "/CN=$(hostname --fqdn)/" -keyout frontend.key -out frontend.crt

Relaunch the service The final step is to relaunch the service:

$ sudo invoke-rc.d nginx restart



Installation Checks


On GNU/Linux:

$ celery worker --app=frontend.tasks:frontend_app

-------------- celery@frontend v3.1.13 (Cipater)---- **** -------- * *** * -- Linux-3.2.0-4-amd64-x86_64-with-debian-7.6-- * - **** ---- ** ---------- [config]- ** ---------- .> app: frontend.tasks:0x1e18750- ** ---------- .> transport: amqp://probe:**@brain:5672/mqfrontend- ** ---------- .> results: disabled- *** --- * --- .> concurrency: 1 (prefork)-- ******* ------- ***** ----- [queues]-------------- .> brain exchange=celery(direct) key=brain

[2014-08-20 15:28:58,745: WARNING/MainProcess] celery@frontend ready.

If your Celery worker does not output something similar to the above output, you should check twice the parametersin the application configuration file you are using. Let us note that the Celery worker gives us useful information onthe analyzer that are enabled.


$ sudo apt-get install ftp-ssl[...]$ ftp-ssl <hostname of the brain>Connected to brain.220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------220-You are user number 1 of 50 allowed.220-Local time is now 18:55. Server port: 21.220-This is a private system - No anonymous login220-IPv6 connections are also welcome on this server.220 You will be disconnected after 15 minutes of inactivity.Name (brain:root): frontend-ftp500 This security scheme is not implemented234 AUTH TLS OK.[SSL Cipher DHE-RSA-AES256-GCM-SHA384]200 PBSZ=0200 Data protection level set to "private"331 User probe OK. Password requiredPassword: frontend-ftp-password230 OK. Current directory is /Remote system type is UNIX.Using binary mode to transfer files.ftp>

Restful API One can verify that the restful API is up and running by querying a specific route on the web server orby checking the system logs:



$ curl http://localhost/_api/probe/list{"msg": "success", "code": 0, "probe_list": ["ClamAV", "ComodoCAVL", "EsetNod32", "FProt", "Kaspersky", "McAfeeVSCL", "NSRL", "StaticAnalyzer", "VirusTotal"]}$ sudo cat /var/log/uwsgi/app/frontend-api.logWed Aug 20 17:51:33 2014 - *** Starting uWSGI 1.2.3-debian (64bit) on [Wed Aug 20 17:51:33 2014] ***Wed Aug 20 17:51:33 2014 - compiled with version: 4.7.2 on 06 July 2013 12:20:09Wed Aug 20 17:51:33 2014 - detected number of CPU cores: 4Wed Aug 20 17:51:33 2014 - current working directory: /Wed Aug 20 17:51:33 2014 - writing pidfile to /run/uwsgi/app/frontend-api/pidWed Aug 20 17:51:33 2014 - detected binary path: /usr/bin/uwsgi-coreWed Aug 20 17:51:33 2014 - setgid() to 33Wed Aug 20 17:51:33 2014 - setuid() to 33Wed Aug 20 17:51:33 2014 - your memory page size is 4096 bytesWed Aug 20 17:51:33 2014 - detected max file descriptor number: 1024Wed Aug 20 17:51:33 2014 - lock engine: pthread robust mutexesWed Aug 20 17:51:33 2014 - uwsgi socket 0 bound to UNIX address /run/uwsgi/app/frontend-api/socket fd 3Wed Aug 20 17:51:33 2014 - Python version: 2.7.3 (default, Mar 13 2014, 11:26:58) [GCC 4.7.2]Wed Aug 20 17:51:33 2014 - *** Python threads support is disabled. You can enable it with --enable-threads ***Wed Aug 20 17:51:33 2014 - Python main interpreter initialized at 0x264e120Wed Aug 20 17:51:33 2014 - your server socket listen backlog is limited to 100 connectionsWed Aug 20 17:51:33 2014 - *** Operational MODE: preforking ***Wed Aug 20 17:51:33 2014 - mounting ./frontend/web/api.py on /_apiWed Aug 20 17:51:33 2014 - WSGI app 0 (mountpoint=’/_api’) ready in 0 seconds on interpreter 0x264e120 pid: 7860 (default app)Wed Aug 20 17:51:33 2014 - *** uWSGI is running in multiple interpreter mode ***Wed Aug 20 17:51:33 2014 - spawned uWSGI master process (pid: 7860)Wed Aug 20 17:51:33 2014 - spawned uWSGI worker 1 (pid: 7892, cores: 1)Wed Aug 20 17:51:33 2014 - spawned uWSGI worker 2 (pid: 7893, cores: 1)

Web Interface

Installation

Here are the few steps needed to get the interface up and running

1. Make sure you have node installed

Node is needed to fetch the dependencies (npm for the server side, bower for the client side), and to launch the taskrunner (gulp). You can get it from many ways, choose the one that suits you better on their website: nodeJs.

2. Install the development tools

Those two work better when installed globally, you may need root privileges to install them this way

$ npm install -g bower gulp

3. Fetch the dependencies

The rest of the dependencies can then be fetched with this command:

$ npm install

If everything went fine, bower and the webdriver-manager should launch their respective updates right afternpm install is done. If not, here they are:

$ bower install$ webdriver-manager update

Usage


http://nodejs.org/


Tests There are 3 steps that can check code integrity:

Linting

$ gulp lint

Unit tests

$ gulp unit

End to end tests

These tests need to access the interface through a web server, so you will have to launch one. There is a standaloneserver embeded in the project, just launch it in another shell with:

# in another shell$ npm start

The end to end tests can then be checked with another gulp task:

$ gulp e2e

You can launch those 3 in sequence with the full task. You will need the standalone server running for the E2E tests.

$ gulp full

Build To get a bundled and production ready version of the interface, use the dist task, which will build a distdirectory.

$ gulp dist

Probe

The Probes are python-based application that host a single or multiple analyzers. Each analyzer listens on a specificwork queue and waits for an analysis to be scheduled by the Brain through Celery, an open source task framework forPython.

Supported Analyzers

We have mainly focused our efforts on multiple anti-virus engines but we are working on other kind of “probes”. Weenumerate the analyzers that are bundled with IRMA probe application. Feel free to submit your own probes.

Antiviruses So far, we have instrumented the following antiviruses from their CLI:



ProbeName

Anti-Virus Name Description Platform CLI/GUI

ClamAV ClamAV Instruments ClamAV Daemon GNU/Linux CLIComod-oCAVL

Comodo Antivirus forLinux

Instruments Comodo FreeAntivirus for Linux

GNU/Linux CLI

EsetNod32 Eset Nod32 BusinessEdition

Instruments Eset Nod32 BusinessEdition

GNU/Linux CLI

FProt F-Prot Instruments F-Prot Antivirus GNU/Linux CLIMcAfeeVSCLMcAfee VirusScan

Command LineInstruments McAfee GNU/Linux - Microsoft

WindowsCLI

Sophos Sophos Instruments Sophos Microsoft Windows CLIKaspersky Kaspersky Internet

SecurityInstruments Kaspersky InternetSecurity

Microsoft Windows CLI

Symantec Symantec EndpointProtection

Instruments Symantec EndpointProtection

Microsoft Windows CLI

GData G Data Antivirus Instruments G Data Antivirus Microsoft Windows CLI

External analysis platforms So far, we query the following external analysis platforms:

Probe Name Analysis Platform DescriptionVirusTotal VirusTotal Report is searched using the sha256 of the file which is not sent

File database So far, we query the following file databases:

ProbeName

Database Description

NSRL National Software ReferenceLibrary

collection of digital signatures of known, traceable softwareapplications

Binary analyzers So far, we implemented the following binary analyzers:

Probe Name Analyzer DescriptionStaticAnalyzer PE File Analyzer PE File analyzer adapted from Cuckoo Sandbox

Others Additionnally, the following modules are available:

Probe Name DescriptionYara Checks if a file match yara rules

Installation

Probes can be installed either on GNU/Linux and on Microsoft Windows systems. The installation procedure maydiffers between the two systems.

Installation from source According to the system that host the analyzers, the procedure to install the python-basedapplication for Probes may differ. This section describes how to get the source code of the application and to install iton your preferred system.



Downloading the source code from github.com The source code is hosted on github.com. One can fetch an up-to-date version with the following commands. Let us note that there is a common submodule named irma-commonthat could be fetched automatically with the --recursive option:

$ git clone --recursive https://github.com/quarkslab/irma-probe


$ make source$ ls dist/irma-probe-app-1.1.0.tar.gz



• make

• python-pip


Once the source distribution is built, one can install it either on a Microsoft Windows or a GNU/Linux system.

Installing the source distribution To be able to install the python source distribution, we assume that you havealready installed the following software on your system. The prerequisites are recalled here.

Prerequisites We assume that you have a command line interface on your system 5 with the following tools installed:

• python 2.7.x (see Python for Windows for prebuild MSI installer)





Installation on Microsoft Windows On windows system, we will assume that the code for the Probe will beinstalled at the root of the C:\ drive, namely in C:\irma\irma-probe.

Due to differences between Python for Windows and Python for Linux, the installation with pip can only be done withthe following command:

$ C:\Python27\Scripts\pip.exe install irma-probe-app-1.1.0.tar.gz --root="C:\irma\irma-probe"

However, this command puts the code source in C:\irma\irma-probe\Python27 instead ofC:\irma\irma-probe. To fix this, either install irma-probe-app with pip and move the content ofC:\irma\irma-probe\Python27 to C:\irma\irma-probe\ or simply copy the code source you have justchecked out from github.com in C:\irma\irma-probe. Both methods should work.

5 On Microsoft Windows, a Linux-like lightweight command line interface can be installed by installing MSYS.


https://www.python.org/downloads/windows/


http://www.mingw.org/wiki/MSYS


Since the way we packaged the python application does not support automatic installation of dependencies, we needto install them manually:

$ C:\Python27\Scripts\pip.exe install -r C:\irma\irma-probe\requirements.txt[...]

Installation on GNU/Linux On GNU/Linux system, we will assume that the code for the Probe will be installed in/opt/irma/irma-probe directory.

$ pip install irma-probe-app-1.1.0.tar.gz --install-option="--install-base=/opt/irma/irma-probe"[...]

Since the way we packaged the python application does not so support automatic installation of dependencies, weneed to install them manually:

$ pip install -r /opt/irma/irma-probe/requirements.txt[...]

If everything has gone well, the python application is now installed on your system. The next step is to configure it foryour platform and to enable the analyzers you need.

Configuration

The configuration file is config/probe.ini located in the installation directory.

From the sources At the root of the installation directory, the script setup.py asks you questions to configure theapplication to your needs. To fit your setup, you must provide the parameters configured on the Brain.

For Microsoft Windows systems:

$ C:\Python27\python.exe setup.py configure --applicationrunning configure

Welcome to IRMA probe application configuration script.

The following script will help you to create a new configuration forIRMA probe application.


> Do you want to enable syslog logging? (experimental) (y/N) N> Which name would you like to give to your probe? [irma-probe]> What is the hostname of your RabbitMQ server? [brain.irma] brain.irma> What is the vhost defined for probes on your RabbitMQ server? mqbrain> What is the username for this vhost on your RabbitMQ server? brain-rmq> What is the password for this vhost on your RabbitMQ server? brain-rmq-password> What is the hostname of your FTPs server? [brain.irma] brain.irma> What is the username defined for probes on your FTP server? probe-ftp> What is the password defined for probes on your FTP server? probe-ftp-password


$ python setup.py configure --application[...]



When finished, one can note that the config/probe.ini file has been modified with values we typed.

Note: We recall in the following the meaning of each field in config/probe.ini:


log syslog integer 0 enable rsyslog (experimental)prefix string irma-probe: prefix to append to rsyslog entries

probe name string name to give to the probe

broker probe

host string hostname for the RabbitMQ serverport integer 5672 port for the RabbitMQ servervhost string virtual host configured for probesusername string username used for probes on the RabbitMQ serverpassword string password used for probes on the RabbitMQ serverqueue string queue to poll new tasks on the RabbitMQ server

ftp brain

host string hostname for the FTP serverport integer 21 port for the FTP serverusername string username used by probe on the FTP serverpassword string password used by the probe on the FTP server

Enabling Analyzers

The python application auto-discovers available analyzers. As long as the requirements are fulfilled for an analyzer,it is automatically discovered and enabled. By default, no analyzers are available. The following enumerates therequirements to enable each analyzer bundled with the application.

ClamAV - GNU/Linux To enable ClamAV on Debian Stable distribution, one should install several packages:

$ sudo apt-get install clamav-daemon[...]$ sudo freshclam[...]$ sudo service clamav-daemon restart[...]

ComodoCAVL - GNU/Linux Comodo Antivirus for Linux can be downloaded from the Comodo’s downloadpage. The following instruction enable to install the Debian package. By default, the binaries are installed in/opt/COMODO/ directory. As ComodoCAVL is not packaged for the current Debian Stable distribution, we mustinstall it manually:

$ sudo apt-get install binutils$ ar x cav-linux_1.1.268025-1_iXXX.deb$ sudo tar xvf ~/data.tar.gz -C /[...]

Updates for the database can be performed with the following command:

$ XAUTHORITY="$HOME/.Xauthority" sudo /opt/COMODO/menu/comodo-updater[...]

Note: Dependencies to update the database

To be able to update the database using the updater provided with Comodo Antivirus for Linux, some dependeciesneeded for the graphical interface may be missing from the distribution. On Debian Stable system, one can installthem with:


http://www.comodo.com/home/internet-security/antivirus-for-linux.php

http://www.comodo.com/home/internet-security/antivirus-for-linux.php


$ sudo apt-get install libqt4-sql libqt4-network libqtgui4

EsetNod32 - GNU/Linux One can request a trial version of Eset Nod32 Business Edition for Linux on the Esetdownload page. Once downloaded, the anti-virus can be installed with the following commands on Debian. Justfollow the typical installation on the GUI:

$ sudo chmod u+x eset_nod32av_64bit_en.linux$ sudo apt-get install libgtk2.0-0 libc6-i386$ sudo ./eset_nod32av_64bit_en.linux[...]

Binaries should be installed in /opt/eset/esets directory. Updates are performed from the GUI:

$ XAUTHORITY="$HOME/.Xauthority" sudo /opt/eset/esets/bin/esets_gui

Note: Disabling the antivirus daemon

To avoid the anti-virus to protect your system at startup, we deliberately disabled the script used to launch the anti-virusearly at boot:

$ sudo service esets stop$ sudo mv /etc/init.d/esets /etc/init.d/esets.disable

F-Prot - GNU/Linux A copy of F-PROT anti-virus for Linux workstations is available on the F-PROT downloadpage.

The binaries should be installed in /usr/local/f-prot to make the python application detect it automatically.

$ sudo tar xvf fp-Linux.x86.32-ws.tar.gz -C /usr/local/

To launch an update, a configuration step is mandatory:

$ sudo cp /usr/local/f-prot/f-prot.conf.default /etc/f-prot.conf

An update is launched with:

$ sudo ./fpupdateERROR: ld.so: object ’libesets_pac.so’ from /etc/ld.so.preload cannot be preloaded: ignored.[...]

Note: Error

If you see an error message like:

DownloadingWarning: Network - Connection failed (18), trying again...Downloading updateError: Update - Bad mergefile

Just relaunch the script.

Note: Dependencies to update the database

To be able to update the database using the updater provided with Comodo install them with:

$ sudo apt-get install libc6-i386


http://www.eset.com/int/download/home/detail/family/71/

http://www.eset.com/int/download/home/detail/family/71/

http://www.f-prot.com/download/home_user/download_fplinux.html

http://www.f-prot.com/download/home_user/download_fplinux.html


McAfeeVSCL - GNU/Linux or Microsoft Windows A free evaluation of McAfee VirusScan Command Line canbe downloaded from the editor download page.

The binaries should be installed in /usr/local/uvscan/ on GNU/Linux system and must be installed inC:\VSCL on Windows Systems. Let us note that updates must be performed manually. Anti-virus databases andengines can be downloaded here.

After downloading McAfee Virus Scan archive, create /usr/local/uvscan and extract the archive in it:

$ sudo mkdir /usr/local/uvscan$ sudo tar xvf vscl-XXX.tar.gz -C /usr/local/uvscan # replace using your values$ sudo chmod +x /usr/local/uvscan/uvscan

Extract also, using unzip program, the database:

$ sudo unzip avvepo7536dat.zip -d /usr/local/uvscan$ cd /usr/local/uvscan$ sudo unzip avvdat-XXXX.zip

Sophos - Microsoft Windows A free evaluation of Sophos Endpoint Antivirus can be downloaded from the editordownload page. It should be detected automatically if the anti-virus is installed in its default installation directory.

Kaspersky - Microsoft Windows A free evaluation of Kaspersky Internet Security can be requested on the editordownload page. It should be detected automatically if the anti-virus is installed in its default installation directory.

Symantec - Microsoft Windows The procedure to install a trial version of Symantec Endpoint Protection is partic-ularly tedious. We will not document its installation.

G Data - Microsoft Windows A trial version of G Data is available on the editor download page<https://www.gdata.de/kundenservice/downloads.html>. It should be detected automatically if the anti-virus is in-stalled in its default installation directory.

VirusTotal - GNU/Linux or Microsoft Windows The VirusTotal analyzer can be installed easily by downloadingthe python packages it depends on and by modifying its configuration file. From the installation directory, one canexecute:

On GNU/Linux:

$ pip install -r modules/external/virustotal/requirements.txt[...]$ python setup.py configure --VirusTotalrunning configure

Welcome to IRMA VirusTotal module configuration script.

The following script will help you to create a new configuration forVirusTotal module on IRMA probe application.


> Do you want to use VirusTotal private API? (y/N) N> What is the apikey you would you like to use for VirusTotal? <api key here>

On Microsoft Windows:


http://www.mcafee.com/apps/downloads/free-evaluations/

http://www.mcafee.com/apps/downloads/security-updates/security-updates.aspx

http://www.sophos.com/en-us/products/endpoint-antivirus/free-trial.aspx

http://www.sophos.com/en-us/products/endpoint-antivirus/free-trial.aspx

http://usa.kaspersky.com/downloads/free-home-trials/Internet-security

http://usa.kaspersky.com/downloads/free-home-trials/Internet-security


$ C:\Python27\Scripts\pip.exe install -r modules/external/virustotal/requirements.txt[...]$ C:\Python27\python.exe setup.py configure --VirusTotal[...]

Note: Meaning of the fields in the configuration file

Section Option Type Default Description

VirusTotalapikey string api_key used to query VirusTotal API

private boolean use private api (need a private api key)

NSRL - GNU/Linux The National Software Reference Library can be downloaded on the NIST’s web page. Theprovided files are stored in the RDS (Reference Data Set) format. To use this analyzer, one must build first the database.We use LevelDB as fast key-value storage library.

To build the dabatase, one must install first the dependencies:

$ pip install -r modules/database/nsrl/requirements.txt

A (not optimized and very slow) helper script is provided to build the database:

$ mkdir /home/irma/leveldb$ python -m modules.database.nsrl.nsrl create -t os NSRLOS.txt /home/irma/leveldb/os_db$ python -m modules.database.nsrl.nsrl create -t manufacturer NSRLMfg.txt /home/irma/leveldb/mfg_db$ python -m modules.database.nsrl.nsrl create -t product NSRLProd.txt /home/irma/leveldb/prod_db$ python -m modules.database.nsrl.nsrl create -t file NSRLFile.txt /home/irma/leveldb/file_db

Finally, one must indicate to the analyzer where to find the files for the database:

$ python setup.py configure --NSRLrunning configure

Welcome to IRMA NSRL module configuration script.

The following script will help you to create a new configuration forNSRL module on IRMA probe application.


> Where is located NSRL OS database? /home/irma/leveldb/os_db> Where is located NSRL MFG database? /home/irma/leveldb/mfg_db> Where is located NSRL PRODUCT database? /home/irma/leveldb/prod_db> Where is located NSRL FILE database? /home/irma/leveldb/file_db

The last command ask questions to the user for the configuration file located atmodules/database/nsrl/config.ini.

Note: Error

If you see an error message like:

fatal error: Python.h: No such file or directory

Then you’ll need to install python-dev package (for Debian like systems).


http://www.nsrl.nist.gov/


Note: leveldb.LevelDBError: IO error: /home/irma/leveldb/file_db/LOCK: Permission denied

If you encounter this problem, you likely have a problem with unix permissions. Please ensure that the folder is ownedby the user running the probes. On supervisord-based installation (default for vagrant/ansible scripts), the folderowner should be set to nobody. For init.d-based installation, it should be irma instead.

Note: Meaning of the fields in the configuration file

Section OptionType Default Description

NSRL

nsrl_os_db string location of the OS databasensrl_mfg_db string location of the Manufacturer databasensrl_file_db string location of the File databasensrl_prod_db string location of the Product database

StaticAnalyzer - GNU/Linux or Microsoft Windows The PE File analyzer adapted from Cuckoo Sandbox canbe installed easily. One need to install the python packages it depends on. From the installation directory, one canexecute:

On GNU/Linux:

$ pip install -r modules/metadata/pe_analyzer/requirements.txt[...]

On Microsoft Windows, you need cygwin to successfully install the requirements (see python-magic documentationfor installation details):

$ C:\Python27\Scripts\pip.exe install -r modules/metadata/pe_analyzer/requirements.txt[...]

Yara - GNU/Linux or Microsoft Windows Please refer to modules/metadata/yara/README.md file forthe documentation.

Guide on Debian (credits to Carbonn)

1. Installing dependencies

$ sudo apt-get install libtool automake bison

2. Installing Yara python modules

$ git clone https://github.com/plusvic/yara.git$ autoreconf -i --force$ ./configure$ make$ sudo make install$ python setup.py build$ sudo python setup.py install$ sudo ldconfig

3. Configuring for IRMA

$ mkdir /opt/irma/yara_rules/$ cat /opt/irma/yara_rules/yara_rules.yar << EOF# Insert rule below inside the file


https://github.com/ahupp/python-magic#dependencies


rule silent_banker : banker{

meta:description = "This is just an example"thread_level = 3in_the_wild = true

strings:$a = {6A 40 68 00 30 00 00 6A 14 8D 91}$b = {8D 4D B0 2B C1 83 C0 27 99 6A 4E 59 F7 F9}$c = "UVODFRYSIHLNWPEJXQZAKCBGMT"

condition:$a or $b or $c

}EOF

Installation Checks


On GNU/Linux:

$ celery worker --app=probe.tasks:app --workdir=/opt/irma/irma-probeWARNING:root: *** [plugin] Plugin failed to load: Kaspersky miss dependencies: win32 (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: Sophos miss dependencies: win32 (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: Symantec miss dependencies: win32 (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: NSRL miss dependencies: leveldict (ModuleDependency). See requirements.txt for needed dependenciesWARNING:root: *** [plugin] Plugin failed to load: VirusTotal miss dependencies: virus_total_apis (ModuleDependency). See requirements.txt for needed dependenciesWARNING:root: *** [plugin] Plugin failed to load: StaticAnalyzer miss dependencies: pefile (ModuleDependency). See requirements.txt for needed dependencies

-------------- celery@irma-probe v3.1.13 (Cipater)---- **** -------- * *** * -- Linux-3.2.0-4-amd64-x86_64-with-debian-7.6-- * - **** ---- ** ---------- [config]- ** ---------- .> app: probe.tasks:0x1e18750- ** ---------- .> transport: amqp://probe:**@brain:5672/mqprobe- ** ---------- .> results: redis://brain:6379/1- *** --- * --- .> concurrency: 1 (prefork)-- ******* ------- ***** ----- [queues]-------------- .> ClamAV exchange=celery(direct) key=ClamAV

.> ComodoCAVL exchange=celery(direct) key=ComodoCAVL

.> EsetNod32 exchange=celery(direct) key=EsetNod32

.> FProt exchange=celery(direct) key=FProt

.> McAfeeVSCL exchange=celery(direct) key=McAfeeVSCL

[2014-08-19 18:25:06,469: WARNING/MainProcess] celery@irma-probe ready.

The equivalent command on Microsoft Windows is:

$ C:\Python27\Scripts\celery.exe worker --app=probe.tasks:app --workdir=C:\irma\irma-probe[...]



If your Celery worker does not output something similar to the above output, you should check twice the parametersin the application configuration file you are using. Let us note that the Celery worker gives us useful information onthe analyzer that are enabled. As each analyzer connects to a dedicated queue, we can deduce, in this example, thatthe analyzers ClamAV, ComodoCAVL, EsetNod32, FProt and McAfeeVSCL are enabled and ready to serve.


$ sudo apt-get install ftp-ssl[...]$ ftp-ssl <hostname of the brain>Connected to brain.220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------220-You are user number 1 of 50 allowed.220-Local time is now 18:55. Server port: 21.220-This is a private system - No anonymous login220-IPv6 connections are also welcome on this server.220 You will be disconnected after 15 minutes of inactivity.Name (brain:root): probe-ftp500 This security scheme is not implemented234 AUTH TLS OK.[SSL Cipher DHE-RSA-AES256-GCM-SHA384]200 PBSZ=0200 Data protection level set to "private"331 User probe OK. Password requiredPassword: probe-ftp-password230 OK. Current directory is /Remote system type is UNIX.Using binary mode to transfer files.ftp>

Running Probes at startup

We have ensured that the freshly installed Probe is ready to be integrated to your IRMA platform. Now, we can goa step further and make the python application run automatically when the system starts up so you will not need torelaunch manually the workers every time.

We provide several template scripts in the extras/ repository located at the root of the installation directory. Wedescribe in the following how to setup daemons on Microsoft Windows and GNU/Linux systems which roles is to runthe Celery worker at startup.

Daemon on GNU/Linux At the moment, we only support daemonizing with init.d scripts. The following de-scribe the procedure to run make a service run Celery workers on Debian distribution.

Installing the service First, copy the scripts in extras/init.d/ and extras/default respectively in/etc/init.d and /etc/default.

$ sudo cp extras/init.d/celeryd.probe /etc/init.d/celeryd.probe$ sudo cp extras/default/celeryd.probe /etc/default/celeryd.probe

Configuring the service Update the service parameters in extras/default/celeryd.probe to match yoursetup. In most cases, you should pay attention to the following fields:



Fields Default DescriptionCELERYD_NODES probe Name given to the probeCELERYD_CHDIR /opt/irma/irma-probe/ Installation directory for the probeCELERYD_USER irma Username used to execute the Celery workerCELERYD_GROUP irma Group used to execute the Celery worker

Registering the service Finally, fix the permission for the /etc/init.d/celeryd.probe script and registerthe service:

$ sudo chmod u+x /etc/init.d/celeryd.probe$ sudo update-rc.d celeryd.probe defaults


$ sudo invoke-rc.d celeryd.probe start$ sudo cat /var/log/celery/*.log[...][2014-04-30 13:35:03,949: WARNING/MainProcess] worker1@irma-probe ready.[...][2014-04-30 13:35:04,205: WARNING/MainProcess] worker2@irma-probe ready.[...][2014-04-30 13:35:03,949: WARNING/MainProcess] worker3@irma-probe ready.

Daemon on Microsoft Windows On Microsoft Windows, many solution exists to make the Celery worker run atstartup. The recommended way to perform that would be to register a Windows service.

Pre-requisites For that purpose, you will need first to download and install the lastest build of pywin32 .

Configuring the service Then, you will have to adapt the file located in extras/winsrv/service.ini toyour installation. In particular, you should pay attention to the various paths indicated in the configuration file.

The default service.ini looks like the following. Let us recall that we have installed the application inC:\irma\irma-probe:

[services]run=celerydclean=c:\irma\irma-probe\celery.log

[celeryd]command=c:\Python27\python.exeparameters=-m celery worker --app=probe.tasks --workdir=c:\irma\irma-probe -f c:\irma\irma-probe\celery.log -l info

[log]filename=c:\irma\irma-probe\service.loglevel=INFO

The services section contains:

• The list of background commands to run (celeryd) in the run directive.

• The list of files to delete when refreshed or stopped in the clean directive.

The celeryd section contains the commands to run for the celeryd service that is going to be run:

• command specifies the command to run

• parameters specifies the arguments passed to the command.


http://sourceforge.net/projects/pywin32/files/pywin32/


This is equivalent to launching the following command from the CLI:

$ c:\Python27\python.exe -m celery worker --app=probe.tasks --workdir=c:\irma\irma-probe -f c:\irma\irma-probe\celery.log -l info

The log section defines a log file and logging level for the service process itself.

Installing the service You need to have administrator privileges to install the service in the Windows Registry sothat it is started each time the system boots:

$ C:\Python27\python.exe extras/winsrv/service.py --startup=auto install

The --startup=auto makes the service to start automatically when the system boots. You can check that theservice has been effectively installed by consulting the list of Microsoft Windows Services.

Starting and stopping the service Before starting the service, one should debug it to see if the service workscorrectly. This can be done by launching the binary pythonservice.exe in charge of launching the service. Letus note that the worker keeps on working even if an error due to libmagic (see output below) is raised. This erroris not critical as long as we do not enable StaticAnalyzer probe. Please check the documentation if you want tosolve this issue and to enable the StaticAnalyzer probe on Microsoft Windows systems.

$ C:\Python27\Lib\site-packages\win32\pythonservice.exe -debug irma-serviceDebugging service irma-service - press Ctrl+C to stop.Info 0x400000FF - InitializationInfo 0x400000FF - c:\irma\irma-probe\extras\winsrv\service.iniInfo 0x400000FF - startingInfo 0x400000FF - Spawned c:\Python27\python.exe -m celery worker --app=probe.tasks --workdir=c:\irma\irma-probe -f c:\irma\irma-probe\celery.log -l infoInfo 0x400000FF - Started. Waiting for stopNo handlers could be found for logger "multiprocessing"starting command: c:\Python27\python.exe -m celery worker --app=probe.tasks --workdir=c:\irma\irma-probe -f c:\irma\irma-probe\celery.log -l infoWARNING:root: *** [plugin] Plugin failed to load: ClamAV miss dependencies: linux (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: ComodoCAVL miss dependencies: linux (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: EsetNod32 miss dependencies: linux (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: FProt miss dependencies: linux (PlatformDependency).WARNING:root: *** [plugin] Plugin failed to load: KasperskyPlugin: verify() failed because Kaspersky executable was not found.WARNING:root: *** [plugin] Plugin failed to load: McAfeeVSCLPlugin: verify() failed because McAfeeVSCL executable was not found.WARNING:root: *** [plugin] Plugin failed to load: SophosPlugin: verify() failed because Sophos executable was not found.WARNING:root: *** [plugin] Plugin failed to load: Unable to find Symantec executableWARNING:root: *** [plugin] Plugin failed to load: NSRL miss dependencies: leveldict (ModuleDependency). See requirements.txt for needed dependenciesERROR:root:failed to find libmagic. Check your installationTraceback (most recent call last):

File "c:\irma\irma-probe\lib\plugins\manager.py", line 58, in discovermodule = module_meta.load_module(pkg_name)

File "c:\Python27\lib\pkgutil.py", line 246, in load_modulemod = imp.load_module(fullname, self.file, self.filename, self.etc)

File "c:\irma\irma-probe\modules\metadata\pe_analyzer\pe.py", line 20, in <module>from lib.common.mimetypes import Magic

File "c:\irma\irma-probe\lib\common\mimetypes.py", line 20, in <module>import magic

File "c:\Python27\lib\site-packages\magic.py", line 161, in <module>raise ImportError(’failed to find libmagic. Check your installation’)

ImportError: failed to find libmagic. Check your installationWARNING:root: *** [plugin] Plugin failed to load: StaticAnalyzer miss dependencies: modules.metadata.pe_analyzer.pe (ModuleDependency).

-------------- celery@irma-probe v3.1.13 (Cipater)---- **** -------- * *** * -- Windows-7-6.1.7601-SP1-- * - **** ---



- ** ---------- [config]- ** ---------- .> app: probe.tasks:0x2f08ff0- ** ---------- .> transport: amqp://probe:**@brain:5672/mqprobe- ** ---------- .> results: amqp://probe:**@brain:5672/mqprobe- *** --- * --- .> concurrency: 1 (prefork)-- ******* ------- ***** ----- [queues]-------------- .> VirusTotal exchange=celery(direct) key=VirusTotal

[tasks]. probe.tasks.probe_scan

The service can be manually started and stopped with the following commands:

$ C:\Python27\python.exe extras/winsrv/service.py start$ C:\Python27\python.exe extras/winsrv/service.py stop

Removing the service It can be removed with the following commands:

$ C:\Python27\python extras/winsrv/service.py remove

1.3 References

1.3.1 Disclaimer

IRMA is distributed as it is, in the hope that it will be useful, but without any warranty neither the implied mer-chantability or fitness for a particular purpose.

Whatever you do with this tool is uniquely your own responsibility.

1.3.2 License

IRMA source code is licensed under Apache License, version 2.0.

The full license text can be found below (Apache License, version 2.0).

1.3.3 Apache License, version 2.0

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

“License” shall mean the terms and conditions for use, reproduction, and distribution as defined bySections 1 through 9 of this document.

“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is grant-ing the License.

1.3. References 41

http://www.apache.org/licenses/


“Legal Entity” shall mean the union of the acting entity and all other entities that control, are con-trolled by, or are under common control with that entity. For the purposes of this definition, “control”means (i) the power, direct or indirect, to cause the direction or management of such entity, whetherby contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares,or (iii) beneficial ownership of such entity.

“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by thisLicense.

“Source” form shall mean the preferred form for making modifications, including but not limited tosoftware source code, documentation source, and configuration files.

“Object” form shall mean any form resulting from mechanical transformation or translation of aSource form, including but not limited to compiled object code, generated documentation, and con-versions to other media types.

“Work” shall mean the work of authorship, whether in Source or Object form, made available underthe License, as indicated by a copyright notice that is included in or attached to the work (an exampleis provided in the Appendix below).

“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (orderived from) the Work and for which the editorial revisions, annotations, elaborations, or othermodifications represent, as a whole, an original work of authorship. For the purposes of this License,Derivative Works shall not include works that remain separable from, or merely link (or bind byname) to the interfaces of, the Work and Derivative Works thereof.

“Contribution” shall mean any work of authorship, including the original version of the Work andany modifications or additions to that Work or Derivative Works thereof, that is intentionally submit-ted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entityauthorized to submit on behalf of the copyright owner. For the purposes of this definition, “sub-mitted” means any form of electronic, verbal, or written communication sent to the Licensor or itsrepresentatives, including but not limited to communication on electronic mailing lists, source codecontrol systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for thepurpose of discussing and improving the Work, but excluding communication that is conspicuouslymarked or otherwise designated in writing by the copyright owner as “Not a Contribution.”

“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contri-bution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributorhereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocablecopyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform,sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributorhereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable(except as stated in this section) patent license to make, have made, use, offer to sell, sell, import,and otherwise transfer the Work, where such license applies only to those patent claims licensableby such Contributor that are necessarily infringed by their Contribution(s) alone or by combinationof their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institutepatent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) allegingthat the Work or a Contribution incorporated within the Work constitutes direct or contributorypatent infringement, then any patent licenses granted to You under this License for that Work shallterminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof inany medium, with or without modifications, and in Source or Object form, provided that You meetthe following conditions:



(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices stating that You changed the files;and

(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright,patent, trademark, and attribution notices from the Source form of the Work, excluding thosenotices that do not pertain to any part of the Derivative Works; and

(d) If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Worksthat You distribute must include a readable copy of the attribution notices contained withinsuch NOTICE file, excluding those notices that do not pertain to any part of the DerivativeWorks, in at least one of the following places: within a NOTICE text file distributed as partof the Derivative Works; within the Source form or documentation, if provided along with theDerivative Works; or, within a display generated by the Derivative Works, if and wherever suchthird-party notices normally appear. The contents of the NOTICE file are for informationalpurposes only and do not modify the License. You may add Your own attribution notices withinDerivative Works that You distribute, alongside or as an addendum to the NOTICE text fromthe Work, provided that such additional attribution notices cannot be construed as modifyingthe License.

You may add Your own copyright statement to Your modifications and may provide additional ordifferent license terms and conditions for use, reproduction, or distribution of Your modifications,or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution ofthe Work otherwise complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionallysubmitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions ofthis License, without any additional terms or conditions. Notwithstanding the above, nothing hereinshall supersede or modify the terms of any separate license agreement you may have executed withLicensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, servicemarks, or product names of the Licensor, except as required for reasonable and customary use indescribing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor pro-vides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUTWARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, withoutlimitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABIL-ITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determiningthe appropriateness of using or redistributing the Work and assume any risks associated with Yourexercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence),contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligentacts) or agreed to in writing, shall any Contributor be liable to You for damages, including anydirect, indirect, special, incidental, or consequential damages of any character arising as a result ofthis License or out of the use or inability to use the Work (including but not limited to damages forloss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercialdamages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Worksthereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity,or other liability obligations and/or rights consistent with this License. However, in accepting suchobligations, You may act only on Your own behalf and on Your sole responsibility, not on behalfof any other Contributor, and only if You agree to indemnify, defend, and hold each Contributorharmless for any liability incurred by, or claims asserted against, such Contributor by reason of your

1.3. References 43


accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

1.3.4 Authors

IRMA is a project co-funded by the following actors:

• CEA DAM

• DCNS

• GOVCERT.LU (governmental CERT of Luxembourg)

• Airbus Group

• QuarksLab

• Orange Group IS&T

The PRIMARY AUTHORS are (and/or have been):

• Alexandre Quint - Lead Developer, QuarksLab

• Fernand Lone-Sang - QuarksLab

• Bruno Dorsemaine - Orange Group IS&T

• David Carle - QuarksLab

• Guillaume Dedrie - QuarksLab

And here is an inevitably incomplete list of MUCH-APPRECIATED CONTRIBUTORS – people who have submittedpatches, reported bugs, helped answer newbie questions, and generally made IRMA that much better:

• Jean-Paul Weber

• y0ug

1.4 Frequently Asked Questions

1.4.1 Install a python package with pip

$ pip install <package-name>

1.4.2 Update a python package with pip

$ pip install --upgrade <package-name>

1.4.3 Install a specific version of a python package with pip

$ pip install <package-name>==<version>



1.4.4 Install all requirements with pip

$ pip install -r requirements.txt

1.4.5 Install a custom python package with custom install path (e.g., IRMA pack-ages)

$ pip install <package-name.tar.gz> --install-option=’--install-base=<custom path>’

1.4.6 Add a service at boot

$ sudo update-rc.d <service-name> defaults

1.4.7 Start/Stop/Restart a service

$ sudo invoke-rc.d <service-name> start|stop|restart

1.4.8 Enable SSL using OpenSSL in ansible scripts

If you want to activate SSL on the frontend server, you’ll need:

• modify frontend_openssl variables in group_vars/frontend:

frontend_openssl: True # Default is falsefrontend_openssl_dh_param: # put the DH file locationsfrontend_openssl_certificates: [] # an array of files {source, destination}

# to copy to the server

• Uncomment (and customize) the nginx_sites variable in the group_vars/frontend, a commented example is avail-able.

Then, provision or re-provision your infrastructure. Ansible will only change file related to OpenSSL and Nginxconfigurations.

1.4.9 Speed up your Vagrant VMs

Install this softwares:

• vagrant-cachier (more info on vagrant-cachier)

$ vagrant plugin install vagrant-cachier

• vagrant-vbguest (more info on vagrant-vbguest)

$ vagrant plugin install vagrant-vbguest

1.4. Frequently Asked Questions 45

https://github.com/fgrehm/vagrant-cachier

https://github.com/dotless-de/vagrant-vbguest

CHAPTER 2

Resources

• Project website

• IRC (irc.freenode.net, #qb_irma)

• Twitter (@qb_irma)

47

http://irma.quarkslab.com

https://twitter.com/qb_irma


48 Chapter 2. Resources

CHAPTER 3

Screenshots

3.1 Command Line Interface

A sample script can be found in frontend repository. Add your own frontend address before testing it.

3.2 Web Interface

Some screenshots of the irma user interface shipped with frontend package.

49


50 Chapter 3. Screenshots


3.2. Web Interface 51

irma documentation · irma documentation, release 1.1.1 irma is an asynchronous & customizable...

Documents