====== 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 [[README.md|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 [[DOCKER.md|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 [[AGENT.md|AGENT]] file for more\\
information about that.


----

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

