IVRE: a self-hosted network recon framework built on Nmap, Masscan and Zeek

The gap IVRE fills between a scanner and a search engine

Running Nmap or Masscan produces files. Running Zeek produces logs. Neither gives you a place to ask "which of my hosts exposed port 8443 last quarter and what certificate did they present". Commercial services do answer that, but the data lives on someone else's infrastructure, and the coverage they offer is the whole internet rather than your own address space.

IVRE is the middle layer. The README describes it as a network recon framework with tools for passive and active recon, and the list of inputs is the clearest statement of intent: Zeek, Argus, Nfdump, p0f and airodump-ng on the passive side; Nmap, Masscan, ZGrab2, ZDNS, Nuclei, httpx, dnsx, tlsx and Dismap on the active side. The project's own framing is that you build your own self-hosted alternative to Shodan, ZoomEye, Censys and GreyNoise, run your own Passive DNS service, or assemble a tailor-made EASM tool.

The audience is therefore narrow and specific: security engineers with existing scan or capture infrastructure, and research groups that need to keep the raw observations. A team with no scanners already deployed gets nothing from IVRE on day one.

How the database, the CLI and the web interface fit together

The architecture visible in the repository is a Python package (ivre/) that normalises heterogeneous tool output into a single document model, a storage backend, and two front ends. The backends named in the README badges and CI workflows are MongoDB, Elasticsearch and PostgreSQL. MongoDB is the dependency pinned directly in pyproject.toml as pymongo>=4.10, which suggests it is the default path; the PostgreSQL and Elasticsearch support is exercised by separate GitHub Actions workflows rather than by the base dependency list.

The data flow is one-directional. A scanner or capture tool writes its native format, IVRE's ingestion commands parse it, and the parsed records land in the store. Queries then go through the ivre Python modules, the CLI tools, or the web interface. The repository also ships a web-ui/ directory alongside web/, and setup.py contains a helper that tolerates a missing web/static/ui/ tree, which indicates the interface bundle is generated by pkg/buildwebui rather than committed.

One detail worth noting for anyone embedding IVRE in a larger system: pyproject.toml pulls in a static ReDoS analyser used by ivre.web.utils.validate_regex_complexity to reject user-supplied regexes. That is a deliberate choice to treat the web query interface as an attack surface, and it costs a dependency most recon tools do not carry.

Installing IVRE and running a first Nmap import

The README does not give a step-by-step install. It points to the documentation at doc.ivre.rocks, to the doc/ directory in the repository, and notes that on a running IVRE web server the doc/* files are rendered under /doc/. The package is on PyPI as ivre, and the repository ships a docker/ directory and a pkg/ directory, so container and distribution packaging exist, but the README does not spell out the commands for either.

What the packaging does tell you is the floor: requires-python is >=3.12, <4, and the classifiers list Python 3.12, 3.13 and 3.14. A system Python older than 3.12 will not install it.

The README does give one concrete install-and-run pair, for the MCP server, which is the newest entry point in the project:

pip install 'ivre[mcp]'
ivre mcp-server

The first line installs IVRE with the optional MCP extra; the second starts a Model Context Protocol server that, per the README, exposes the database to LLM agents. Client configuration for Claude Code, Claude Desktop, Cursor, OpenCode, VS Code, Windsurf and JetBrains is documented in doc/usage/mcp-server.rst, and doc/dev/mcp-plugins.rst covers adding your own tools. Note that this path assumes a populated database; the MCP server is a query surface, not a scanner.

For the ingestion side, the README gives no command, so treat the doc/ directory as the source of truth rather than guessing flags. On an installed system, the README states that most CLI tools accept --help and most Python sub-modules expose help(ivre.module), which is the fastest way to discover the real command names on your build.

Where IVRE stops being the right tool

The heaviest constraint is operational. IVRE is a framework, not an appliance. It expects a database server, a Python 3.12+ environment, and scanners you supply and maintain separately. The README's contributing section asks for scan results and capture files as examples and offers to help people produce them, which is a fair signal that getting representative data into the tool is a real step, not a formality.

The second constraint is scope. IVRE does not scan anything by itself. Every active tool in the list, from Nmap to Nuclei, is external. If your problem is "I need a scan run right now", IVRE adds a database to your path before it adds any capability.

The third is that the documentation is uneven by design. The README delegates almost everything to Read The Docs and to --help output. That is workable for someone already fluent in Nmap and Zeek, and frustrating for someone who wants a single page that says which backend to pick. The README does not document rollback, migration between MongoDB and PostgreSQL, or what happens to existing records when the schema changes, so plan to test that yourself before a production cutover.

Finally, the licence is a boundary, not a footnote. GPL-3.0-or-later covers the framework. If your EASM product embeds IVRE and you distribute it, the copyleft terms apply; running it internally as a service does not trigger distribution. That distinction matters more here than in most tools, because the README explicitly frames IVRE as a foundation for building your own product.

IVRE versus running Zeek and Nmap with your own scripts

The obvious alternative is not another recon framework. It is the pile of Nmap XML, Zeek logs and one-off Python scripts that most teams already have. That approach has real advantages: no database to operate, no schema to migrate, and total freedom over what you keep.

What it lacks is a query model. IVRE's value is that a Zeek observation and an Nmap result describing the same host land in the same store with a common document shape, so a single query can cross the passive and active views. Rebuilding that means writing and maintaining a normalisation layer yourself, which is exactly the part of IVRE that is hardest to replace and least visible from the README.

The honest comparison is cost of ownership. A script pile costs you engineering time every time a tool changes its output format. IVRE costs you a database, a Python runtime and an upgrade path, and in exchange the format churn is the maintainers' problem. For a team scanning a handful of subnets occasionally, the scripts win. For a team with continuous passive capture plus periodic active scans, the scripts stop scaling at the point where someone wants to correlate the two.

Maintenance, releases and what GPL-3.0 means in practice

The last push to the repository was on 2026-09-10, and the repository is not archived. The most recent tagged release listed is v0.9.21 from 2024-09-25, so the gap between tags is wide while the commit activity is current. Anyone pinning a version should expect to track master or a distribution package rather than wait for a tag, and should read the release notes for v0.9.21 as the last formal statement of change.

The version is dynamic, produced by setuptools-scm from Git metadata. That has a practical consequence: a source checkout without tags or history will not produce a meaningful version string, and packaging from a tarball depends on the tag being present. Distribution packagers should check this before filing a bug about a version like 0.0.0.

Upgrade cost is dominated by the backend, not by IVRE. A MongoDB major-version bump, a PostgreSQL extension change or an Elasticsearch mapping change is the expensive part, and the README does not describe a supported migration path between any of the three. The pytest suite under tests/ and the three backend-specific CI workflows are the evidence that all three are exercised, but exercising a backend in CI is not the same as guaranteeing an in-place upgrade.

On licensing: GPL-3.0-or-later, stated in both the README and pyproject.toml, with the full text at doc/license.rst. The README quotes the standard warranty disclaimer. If you plan to redistribute IVRE inside a product, read the licence text yourself; this is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt IVRE if you already run Nmap, Masscan or Zeek and need a queryable, self-hosted store for the results, and if you are willing to operate MongoDB, PostgreSQL or Elasticsearch plus the Python 3.12 toolchain it requires. Do not adopt it if you want a hosted scanner with no infrastructure to run, or if you only need a one-off Nmap XML file read once. Before committing, confirm which backend the doc/ installation page recommends for your case, check that your Python is 3.12 or newer, and read doc/license.rst against your own distribution plans, since GPL-3.0-or-later governs the whole framework.

Frequently asked questions

Official sources

1. ivre/ivre on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases