IVRE - A PYTHON NETWORK RECON FRAMEWORK, BASED ON NMAP, BRO & P0F

IVRE (Instrument de veille sur les réseaux extérieurs) or DRUNK (Dynamic Recon of UNKnown networks) is a network recon framework, including two modules for passive recon (one p0f-based and one Bro-based) and one module for active recon (mostly Nmap-based, with a bit of ZMap).

The advertising slogans are:

• (in French): IVRE, il scanne Internet.
• (in English): Know the networks, get DRUNK!

The names IVRE and DRUNK have been chosen as a tribute to "Le Taullier".

External programs / dependencies

IVRE relies on:

• Python 2, version 2.6 minimum
  
  • the Crypto module
  • the pymongo module, version 2.7.2 minimum.
• Nmap & ZMap
• Bro & p0f
• MongoDB, version 2.6 minimum
• a web server (successfully tested with Apache and Nginx, should work with anything capable of serving static files and run a Python-based CGI), although a test web server is now distributed with IVRE (httpd-ivre)
• a web browser (successfully tested with recent versions of Firefox and Chromium)
• Maxmind GeoIP free databases
• optionally Tesseract, if you plan to add screenshots to your Nmap scan results
• optionally Docker & Vagrant (version 1.6 minimum)

IVRE comes with (refer to the LICENSE-EXTERNAL file for the licenses):

• AngularJS
• Twitter Bootstrap
• jQuery
• D3.js
• flag-icon-css

Passive recon

The following steps will show some examples of passive network recon with IVRE. If you only want active (for example, Nmap-based) recon, you can skip this part.

Using Bro

You need to run bro (2.3 minimum) with the option -b and the location of the passiverecon.bro file. If you want to run it on the eth0 interface, for example, run:

# mkdir logs
# bro -b /usr/local/share/ivre/passiverecon/passiverecon.bro -i eth0

If you want to run it on the capture file (capture needs to a PCAP file), run:

$ mkdir logs
$ bro -b /usr/local/share/ivre/passiverecon/passiverecon.bro -r capture

This will produce log files in the logs directory. You need to run a passivereconworker to process these files. You can try:

$ passivereconworker --directory=logs

This program will not stop by itself. You can (p)kill it, it will stop gently (as soon as it has finished to process the current file).

Using p0f

To start filling your database with information from the eth0 interface, you just need to run (passiverecon is just a sensor name here):

# p0f2db -s passiverecon iface:eth0

And from the same capture file:

$ p0f2db -s passiverecon capture

Using the results

You have two options for now:

• the ipinfo command line tool
• the db.passive object of the ivre.db Python module

For example, to show everything stored about an IP address or a network:

$ ipinfo 1.2.3.4
$ ipinfo 1.2.3.0/24

See the output of ipinfo --help.
To use the Python module, run for example:

$ python
>>> from ivre.db import db
>>> db.passive.get(db.passive.flt_empty)[0]

For more, run help(db.passive) from the Python shell.

Active recon

Scanning

The easiest way is to install IVRE on the "scanning" machine and run:

# runscans --routable --limit 1000 --output=XMLFork

This will run a standard scan against 1000 random hosts on the Internet by running 30 nmap processes in parallel. See the output of runscans --help if you want to do something else.
When it's over, to import the results in the database, run:

$ nmap2db -c ROUTABLE-CAMPAIGN-001 -s MySource -r scans/ROUTABLE/up

Here, ROUTABLE-CAMPAIGN-001 is a category (just an arbitrary name that you will use later to filter scan results) and MySource is a friendly name for your scanning machine (same here, an arbitrary name usable to filter scan results; by default, when you insert a scan result, if you already have a scan result for the same host address with the same source, the previous result is moved to an "archive" collection (fewer indexes) and the new result is inserted in the database).
There is an alternative to installing IVRE on the scanning machine that allows to use several agents from one master. See the AGENT file, the program runscans-agent for the master and the agent/ directory in the source tree.

Using the results

You have three options:

• the scancli command line tool
• the db.nmap object of the ivre.db Python module
• the web interface

CLI: scancli

To get all the hosts with the port 22 open:

$ scancli --port 22

See the output of scancli --help.

Python module

To use the Python module, run for example:

$ python
>>> from ivre.db import db
>>> db.nmap.get(db.nmap.flt_empty)[0]

For more, run help(db.nmap) from the Python shell.

Web interface

The interface is meant to be easy to use, it has its own documentation.

Download IVRE