====== DB Server ======

Follow the [[http://docs.mongodb.org/manual/installation/|documentation from MongoDB project]], depending on your distribution. It is recommended to install packages from the MongoDB project rather than the (possibly old) packages from your distribution.

If you want to use the "flow" module, you also need to install [[http://neo4j.com/|Neo4j]].

====== IVRE ======

===== Dependencies =====

If you plan to run scans from a machine, install [[http://nmap.org/|Nmap]] and optionally [[https://zmap.io/|ZMap]] and [[https://github.com/robertdavidgraham/masscan|Masscan]]. If you want to integrate screenshots, install [[https://github.com/tesseract-ocr/tesseract|Tesseract]] and [[http://phantomjs.org/|PhantomJS]].

If you plan to analyze PCAP file on a machine, install [[http://www.bro.org/|Bro]] (version 2.3 minimum) and [[http://lcamtuf.coredump.cx/p0f/|p0f]] (version 2, will not work with version 3).

To install IVRE, you'll need [[http://www.python.org/|Python]] 2, version 2.6 minimum (prefer 2.7), with the following modules:

  * [[http://www.pycrypto.org/|Crypto]]
  * [[http://api.mongodb.org/python/|pymongo]] version 2.7.2 minimum.
  * [[http://py2neo.org/v3/|py2neo]]
  * [[http://www.pythonware.com/products/pil/|PIL]] optional, to trim screenshots.

===== Installation =====

The installation of [[doc:readme|IVRE]] itself can be done by:

  * using the ''%%setup.py%%'' (classical ''%%./setup.py build; sudo ./setup.py install%%'') script.
  * using [[https://pypi.python.org/pypi/pip|pip]]: on a Debian-based system for example, install the packages ''%%python-pip%%'' and ''%%python-dev%%'' (needed to build dependencies) and run ''%%pip install ivre%%'' (this will download and install for you IVRE and its Python dependencies from [[https://pypi.python.org|PyPI]], the Python Package Index).
  * building an RPM package (you can use the provided ''%%buildrpm%%'' script, or use the ''%%setup.py%%'' script with your own options) and then installing it.
  * using [[doc:docker|Docker]] (in this case you do not need to follow the following instructions, as the Docker containers are already configured).

===== Configuration =====

Default configuration values are hard-coded in ''%%ivre/config.py%%''. You should not change this file, unless you are modifying IVRE and you want to change the default configuration. You do not need to do this if you want to install IVRE with a non-default configuration, you just need to distribute a proper configuration file.

You can override default values in three files:

  * two system-wide:
    * ''%%/etc/ivre.conf%%''
    * ''%%/usr/local/etc/ivre.conf%%'' (read after, so higher priority)
  * one user-specific:
    * ''%%~/.ivre.conf%%'' (the last to be read, so highest priority)

The file should contain lines of type ''%%key = value%%''. Empty lines and comments (starting with the ''%%#%%'' character) are ignored. The following values can be changed:

  * ''%%DB%%'': the URL to use; default is ''%%mongodb:///%%'', meaning use default database (''%%ivre%%'') on the default host (''%%localhost%%''). Here is a more complete example: ''%%mongodb://user:password@host/db?colname_aaa=bbb&colname_ccc=ddd%%''
  * ''%%DB_NMAP%%'', ''%%DB_PASSIVE%%'' and ''%%DB_DATA%%'': specific URLs to use; default is to use the URL from ''%%DB%%'' setting.
  * ''%%GEOIP_PATH%%'': default is ''%%[INSTALL PREFIX]/share/ivre/geoip/%%''.

For the full and up-to-date list of settings that can be changed, see the ''%%ivre/config.py%%'' file.

It might be a good idea to have a read-only account everywhere except for some specific users or hosts that need write access to the database (the users that insert scan results with ''%%ivre scan2db%%'', the users or the hosts that run ''%%ivre p0f2db%%'' and/or ''%%ivre passiverecon2db%%''). It is best to avoid using a configuration with write access to the database when you only need a read access. This can be achieved with users or hosts dedicated to insertion tasks.

===== DB creation =====

Once IVRE has been properly configured, it's time to initialize its databases.

For that, the command-line tools (namely ''%%ivre ipdata%%'', ''%%ivre ipinfo%%'', ''%%ivre scancli%%'' and ''%%ivre runscansagentdb%%'', respectively for information about IP addresses, passive information, active information and running scans through agents) have a ''%%--init%%'' option.

So you can run, with a user or from a host where the configuration has a write access to the database (add ''%%< /dev/null%%'' to skip the confirmation):

<code>
$ ivre scancli --init
This will remove any scan result in your database. Process ? [y/N] y
$ ivre ipinfo --init
This will remove any passive information in your database. Process ? [y/N] y
$ ivre ipdata --init
This will remove any country/AS information in your database. Process ? [y/N] y
# ivre runscansagentdb --init
This will remove any agent and/or scan in your database and files. Process ? [y/N] y
</code>
==== Getting IP data ====

<code>
# ivre ipdata --download
$ ivre ipdata --import-all --no-update-passive-db
</code>
==== Web Server ====

Once IVRE has been installed, to also install the web interface, you have to copy or symlink IVRE files to your web server directories, or configure your web server to use IVRE files directly.

The files the web server should serve statically are located in ''%%[PREFIX]/share/ivre/web/static%%'', the folder the web server should serve as CGI is located in ''%%[PREFIX]/share/ivre/web/cgi-bin%%'', and the (optional) folders to use as Dokuwiki content are located in ''%%[PREFIX]/share/ivre/dokuwiki/doc%%'' and ''%%[PREFIX]/share/ivre/dokuwiki/media%%''. Make sure your Dokuwiki has been configured with server-side URL rewriting; this means using proper rewrite in your Web server configuration (with ''%%mod_rewrite%%'' when using Apache; you can use the provided ''%%Dockerfile%%''s as examples on how to configure Apache or Nginx) and adding ''%%$conf['userewrite'] = 1%%'' in your Dokuwiki config file.

You may want to change some values, by creating or modifying ''%%/etc/ivre.conf%%''.

On a typical Debian/Ubuntu installation with Apache and Dokuwiki installed with the distribution packages, these files should be copied or (sym)linked at these locations:

  * ''%%[PREFIX]/share/ivre/web/static/*%%'' -> ''%%/var/www%%'' or ''%%/var/www/html%%''
  * ''%%[PREFIX]/share/ivre/web/cgi-bin/*%%'' -> ''%%/usr/lib/cgi-bin/%%''
  * ''%%[PREFIX]/share/ivre/dokuwiki/doc%%'' -> ''%%/var/lib/dokuwiki/data/pages/%%''
  * ''%%[PREFIX]/share/ivre/dokuwiki/media/logo.png%%'' -> ''%%/var/lib/dokuwiki/data/media/%%''
  * ''%%[PREFIX]/share/ivre/dokuwiki/media/doc%%'' -> ''%%/var/lib/dokuwiki/data/media/%%''

==== Getting screenshots ====

Nmap does not take application screenshots by default. To do so, you have to install the NSE screenshot scripts that come with IVRE. You will also need to install PhantomJS, ImageMagick and FFMPEG. Also, ''%%vnc-screenshot.nse%%'' requires Nmap version >= 7.25BETA2. If both Nmap and IVRE have been installed in ''%%/usr%%'':

<code>
# cp /usr/share/ivre/nmap_scripts/*.nse /usr/share/nmap/scripts/
# patch /usr/share/nmap/scripts/rtsp-url-brute.nse \
> /usr/share/ivre/nmap_scripts/patches/rtsp-url-brute.patch
# nmap --script-updatedb
</code>
And now, you can play:

<code>
# nmap -sV --script screenshot [targets]
</code>
====== Agent ======

If you do not plan to run active scans with remote agents (where IVRE will not be installed), you can skip this section.

The agent does not require IVRE to be installed. It is a script that needs to be adapted to each situation.

The agent is only needed when you cannot install IVRE on the machine used to scan or when you want to use many machines to run one scan.

It requires a POSIX environment, and the commands ''%%screen%%'', ''%%rsync%%'' and ''%%nmap%%'' (of course). See the [[doc:agent|AGENT]] file for more information about that.


----

This file is part of IVRE. Copyright 2011 - 2016 [[mailto:pierre.lalet@cea.fr|Pierre LALET]]

