Recon Essentials

The free, self-hosted edition — what it does, how to install it, and where its limits are.

Recon Essentials is the discovery and inventory part of Vulmon Recon, packaged to run on your own machine with Docker. You add the domains and IP ranges you own. It then keeps discovering what is exposed — subdomains, IP addresses, open ports, websites, technologies, certificates — and shows changes as they happen.

Everything it finds stays in a PostgreSQL database on your machine. It never uploads your assets.

What is included, and what is not

This matters before you install, because the free edition is deliberately narrower than the hosted product and nothing in it is locked behind an upgrade prompt — the missing parts are not in the image at all.

Included. The six inventory lists (domains, IP addresses, websites, technologies, ports, certificates), each searchable, filterable and exportable to CSV. Scope review, so you decide which domains and IP addresses are yours and get monitored. Scan configuration with policies, an activity log, and the engine settings. Certificate and TLS findings. Reports you generate when you want them. Notes, tags and owners. Search across everything found. In-app notifications. Accounts with roles, and two-factor authentication.

Not included. Vulnerability findings — there is no CVE matching, no severity scoring and no issue tracking, so this edition tells you what is exposed rather than which software on it has a known vulnerability. Also absent: cloud account connectors, integrations (Jira, Slack, Teams, ServiceNow, GitHub, GitLab, Zapier), the public API and API keys, single sign-on, scheduled or emailed reports, and outbound email of any kind.

That last one has a visible consequence: invitations and password resets are links you copy and send yourself.

Capacity

UnregisteredRegistered (free)
Discovered assets (domains + IP addresses)UnlimitedUnlimited
In-scope assets (domains + IP addresses)1550
Seeds45150

Registering is optional, takes an email address and an activation code, and happens in the app under Settings → License. Once registered, the daily license renewal also reports how many domains and IP addresses are in scope, out of scope and pending, and how many seeds there are — numbers only, never names. See Network activity and the privacy policy.

Recon Essentials is not open source. Its use is governed by the Terms of Service. They allow you to add and scan only assets you own or are authorized to assess.

Install, and start it later

Run the command in a terminal, in the folder where the installation should go. It creates a recon-essentials folder there.

Linux and macOS (on Windows, Git Bash and WSL work too):

curl -fsSL https://raw.githubusercontent.com/kontratek/recon-essentials/main/recon-essentials.sh | bash

Windows, in PowerShell, with Docker Desktop running Linux containers (its default):

irm https://raw.githubusercontent.com/kontratek/recon-essentials/main/recon-essentials.ps1 | iex

The command checks Docker and Compose v2 and generates the database password. Then it asks one question: who will use Recon Essentials. Press Enter if only this computer will (local access); the port then listens on 127.0.0.1 only. If other computers on the network will open it too (remote access), it asks for this computer's IP address or host name. Invitation and password-reset links use that address, so a fixed one works best. It takes port 8080, or the next free one when 8080 is in use. Then it downloads the images, starts everything and opens the browser at the page where you create the first administrator. It writes nothing outside the recon-essentials folder. In a system or temporary folder, it installs into your home folder instead.

After that, start Recon Essentials from its folder: .\recon-essentials.cmd on Windows (or double-click it), ./recon-essentials.sh on Linux and macOS. It never deletes data, and it downloads only an image that is missing. When a new release is out, it asks whether to upgrade. When the installed release is no longer supported, it upgrades before it starts.

The README shows how to read the script before running it, and how to install without a terminal or into another folder.

Requirements: Docker Engine 24+ with Docker Compose v2 (a Linux server, or Docker Desktop on macOS or Windows), 2 CPU cores and 4 GB RAM, 10 GB disk to start with, and one inbound port for the web interface.

First steps

  1. Add seeds — Scan configuration → Seeds: your domains, IP addresses or ranges. Add only assets you own or are authorized to assess. Discovery then starts on its own.
  2. Review scope — Asset review lists what was found. Confirm what is yours; only in-scope assets are monitored continuously and count towards the limit.
  3. Check what the engine can measure — Scan configuration → Scanning. Some scans need privileges the container may not have, and the page says so plainly rather than reporting an empty result as a clean one.
  4. Invite colleagues — Settings → Users. The invitation is a link you copy and send.

When it does not open

Recon Essentials runs in Docker, in the background. Closing the terminal does not stop it, and it starts again on its own whenever Docker starts. On Windows and macOS, let Docker Desktop start when you sign in.

When it does not open, start it with the script in its folder. It starts Docker Desktop when it is closed, and offers to restart it when it does not answer. It starts Recon Essentials when it was stopped, and downloads the same release again when an image or a container was deleted. The data stays in Docker volumes through all of this. The table in the README lists each case.

In the installation folder, ./recon-essentials.sh stop stops it (Windows: .\recon-essentials.cmd stop).

The command refuses to make a second installation over the data of an existing one, and names the folder of the existing installation when Docker still knows it.

To change who can open it, or the address, run ./recon-essentials.sh address (Windows: .\recon-essentials.cmd address) in the installation folder. On Linux, Docker publishes the port past ufw, so the answer to "who will use it" is what limits who can reach it. On Windows, allow Docker Desktop Backend for private networks in the firewall so other computers can open it.

Upgrading and backing up

Starting it offers the upgrade when a new release is out. To upgrade at another time, run this in the installation folder. It moves to the current release and restarts; data is kept.

./recon-essentials.sh upgrade           # Linux and macOS
.\recon-essentials.cmd upgrade          # Windows

Recon Essentials runs as two images, the web and the engine, and every release is one tested pair of them. .env names the release in a single line, RECON_VERSION, and both images take that number, so they cannot come from different releases. docker compose pull alone fetches the same release again. The upgrade command first downloads the new images, and changes nothing if that fails. Then it moves RECON_VERSION to the new release, replaces docker-compose.yml if the release changed it (your previous copy is kept beside it) and restarts. To move to a specific release instead: RECON_VERSION=x.y.z ./recon-essentials.sh upgrade on Linux and macOS, .\recon-essentials.cmd upgrade -Version x.y.z on Windows.

If the engine that runs is not the build this release was tested with, the dashboard says so; run the upgrade to put both images on the same release again.

The migrator upgrades the database schema before the new version starts. Downgrades are not supported.

The data is not in the installation folder: it lives in Docker volumes — pgdata (the database), media (favicons and screenshots) and webdata (generated secrets and uploaded profile images) — which survive restarts and upgrades. The folder holds .env, and with it the database password; keep it. A backup is two files, the database dump and the generated secrets file: two-factor secrets are encrypted with a key from that file, so a database restored without it locks every two-factor user out. From the installation folder — the same commands in bash and in PowerShell:

docker compose exec -T db pg_dump -U recon -Fc -f /tmp/recon.dump recon
docker compose cp db:/tmp/recon.dump recon.dump
docker compose exec -T db rm /tmp/recon.dump
docker compose cp web:/data/secrets.env recon.secrets.env

The dump is written inside the database container and copied out, never sent through the shell: Windows PowerShell re-encodes binary output that passes through >, and the dump would be damaged without any warning. The restore steps are in the README of the distribution repository.

Locked out?

An administrator can issue a one-time password reset link from Settings → Users. If the only administrator is locked out, the image carries a command for it:

docker compose exec web cli user reset-password admin@example.com

It prints a reset link valid for 60 minutes.