Principles — IVRE documentation

# Principles

IVRE is a network cartography (or network recon) framework.

## Purposes

IVRE has five purposes (we use this word to refer to the different types of data IVRE handles), which can be stored by one or more backend databases:

- `data`: associates IP ranges to Autonomous Systems (AS numbers and names), and geographical information (country, region, city), based on data from Maxmind GeoIP. It can be queried using:

  > - Python API: the `db.data` object from the `ivre.db` module.

  > - Command line: the `ivre ipdata` tool.

  > - Web (JSON) API: the `/cgi/ipdata/<address>` URL.

- `nmap` (sometimes also referred to as `scans`): contains Nmap, Masscan, Dismap, Zgrab2, ZDNS, Nuclei, httpx, tlsx and dnsx scan results, as well as `ivre auditdom` results. Each record represents one host seen during one network scan. It can be queried using:

  > - Python API: the `db.nmap` object from the `ivre.db` module.

  > - Command line: the `ivre scancli` tool.

  > - Web (JSON) API: the `/cgi/scans` and `/cgi/scans/*` URLs.

- `passive`: contains host intelligence captured from the network using a Zeek dedicated module called `passiverecon`, p0f and airodump-ng logs. Each record represents one piece of information (e.g., the HTTP `Server:` header value `Apache` has been seen 10 times on port 80 of host 1.2.3.4). It can be queried using:

  > - Python API: the `db.passive` object from the `ivre.db` module.

  > - Command line: the `ivre ipinfo` and `ivre iphost` tools. The latter is dedicated to passive DNS queries.

  > - Web (JSON) APIs: the `/cgi/passive` and `/cgi/passivedns` URLs. The latter is dedicated to passive DNS and is compatible with the Common Output Format implemented for example in CIRCL’s PyPDNS.

- `view`: contains a consolidated view of hosts based on data from `nmap` and `passive`. The structure of the records is similar to `nmap`, but each record represents a host, seen during one or more network scans and/or seen from network captures. It can be queried using:

  > - Python API: the `db.view` object from the `ivre.db` module.

  > - Command line: the `ivre view` tool.

  > - Web (JSON) API: the `/cgi/view` and `/cgi/view/*` URLs.

  > - Web UI: the `/` or `/index.html` Web page.

- `flow`: contains aggregated network flows, as seen by Zeek, Argus or Netflows (using Nfdump). It can be queried using:

  > - Python API: the `db.flow` object from the `ivre.db` module.

  > - Command line: the `ivre flowcli` tool.

  > - Web (JSON) API: the `/flows` URL.

  > - Web UI: the `/flow.html` Web page.

The following (non-exhaustive) figure shows how the data gets from your favorite open-source tools to IVRE’s databases.

## Storing data

## Accessing data

The following (also non-exhaustive) figures show how the data gets from IVRE’s databases back into your hands.