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

Download IRMA Documentation IRMA Documentation, Release 1.1.1 IRMA is an asynchronous & customizable analysis

Post on 26-Sep-2020

2 views

Category:

Documents

0 download

Embed Size (px)

TRANSCRIPT

  • IRMA Documentation Release 1.1.1

    Quarkslab

    April 15, 2015

  • Contents

    1 Table of Contents 3 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.4 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

    2 Resources 47

    3 Screenshots 49 3.1 Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.2 Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

    i

  • ii

  • 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

  • IRMA Documentation, Release 1.1.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 the recommended 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 you have 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 incident you 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 you install 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 we are 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

  • IRMA Documentation, Release 1.1.1

    1.1.3 Infrastructure Overview

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

    4 Chapter 1. Table of Contents

  • IRMA Documentation, Release 1.1.1

    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 you are using.

    The Frontend and the Brain must be installed on a GNU/Linux system 1. We recommend to use a Debian Stable distribution 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 for the platform are known to work or to have equivalents on these systems.

    1.1. Introduction 5

  • IRMA Documentation, Release 1.1.1

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

    We can not give you any specific numbers. On one hand we managed to run the whole IRMA platform on a single machine by hosting it with multiple systems inside virtual machines: this setup gives fairly high throughput as long as it has reasonable IO (ideally, SSDs), and a good amount of memory (our setup was an i7 cpu with 16 GB ram on regular drives (at least 200 GB required), on the other hand, a lighter version of the system with the three parts together 3 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 IRMA platform 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 automated installation is known to work only from GNU/Linux platforms as it uses Ansible which does not support Windows systems 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 or maintain 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 is difficult 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

    6 Chapter 1. Table of Contents

    http://www.ansible.com http://www.ansible.com https://galaxy.ansible.com/

  • IRMA Documentation, Release 1.1.1

    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 of RAM 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 use one 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 the default_ssh_keys: section. You will need to add your public keys for SSH password-less connection to the 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 and playbooks/group_vars/probe respectively. Make sure to adapt xxx_deployment_configs variables accordingly 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 Inventory documentation for the expected syntax.

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

    $ ansible-playbook -i ./hosts/example playbooks/playbook.yml -u -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

  • IRMA Documentation, Release 1.1.1

    To run one or more specific actions and avoid running all the playbook, you can use tags. For example, if you want to re-provision Nginx, run the same command, but append --tags=nginx. You can combine multiple tags separated with 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 defaul