Recon-ng: Modular OSINT Framework — Part 1 (Setup & Workspaces)

Recon-ng is one of the most complete — and most educational — OSINT tools for penetration testers. It provides a Metasploit-style CLI with dozens of modules for subdomain enumeration, email harvesting, breach checks, social-profile discovery, and much more. In this first part we look at what it is, how to install it, and how the workspaces and marketplace architecture work.

Legal & ethical scope: All Recon-ng modules must be used only inside engagements with written authorization, or against your own domains and lab environments. Many modules call third-party APIs (Shodan, Have I Been Pwned, BinaryEdge) — respect their terms of service.

What Recon-ng is

Recon-ng (maintained by Tim Tomes / lanmaster53) is an open-source web reconnaissance framework written in Python. Its design intentionally mirrors Metasploit: an interactive shell where you load modules, set options, and execute queries.

• Modular architecture: Dozens of modules organized into categories (Recon, Reporting, Discovery, Import, Exploitation).
• Workspaces: Each engagement gets its own workspace backed by a dedicated SQLite database — nothing crosses over.
• Marketplace: Centralized installer for modules — you install only what you need.
• Database-driven: All findings (domains, IPs, emails, contacts) are stored in a structured schema and cross-referenced between modules.

Where it fits in the methodology

Recon-ng operates in the Passive & External Reconnaissance phase, mapping to MITRE ATT&CK TA0043 — Reconnaissance. It is ideal when you want:

• Structured storage of findings in a database, not text files.
• Reuse of data between modules (for example, discovered domains automatically feed the email modules).
• Reproducibility — any other team member can open the workspace and continue.

Installation

Kali / Parrot Linux

Pre-installed. Launch with:

recon-ng

Debian / Ubuntu

sudo apt update
sudo apt install -y recon-ng
recon-ng

From source (always latest)

git clone https://github.com/lanmaster53/recon-ng.git
cd recon-ng
pip3 install -r REQUIREMENTS
./recon-ng

First launch — what you will see

$ recon-ng
    _/_/_/    _/_/_/_/    _/_/_/    _/_/_/    _/      _/
   _/    _/  _/        _/        _/      _/  _/_/    _/
  _/_/_/    _/_/_/    _/        _/      _/  _/  _/  _/
 _/    _/  _/        _/        _/      _/  _/    _/_/
_/    _/  _/_/_/_/    _/_/_/    _/_/_/    _/      _/  -ng

                            /[]\
                          _/____\_
                         |        |
                         |________|
                          recon-ng

[recon-ng v5.x.x, Tim Tomes (@lanmaster53)]
[*] Version check disabled.
[*] No modules enabled/installed.
[recon-ng][default] > 

Core shell commands

help	List all commands.
marketplace search	Search modules in the marketplace.
marketplace install <module>	Install a module.
marketplace remove <module>	Remove a module.
modules load <module>	Load a module.
info	Information about the current module.
options set <name> <value>	Set a parameter.
run	Execute the current module.
workspaces create <name>	New workspace.
workspaces load <name>	Load a workspace.
db query <sql>	Direct SQL on the workspace database.
keys list	List API keys.
keys add <name> <value>	Add an API key.

Workspaces — a separate database per engagement

[recon-ng][default] > workspaces create lab_example
[recon-ng][lab_example] > workspaces list
+----------------+----------------+
| Workspace      | Modified       |
+----------------+----------------+
| default        | 2025-01-01     |
| lab_example    | 2025-01-15     |
+----------------+----------------+

Each workspace is stored at ~/.recon-ng/workspaces/<name>/ and contains a SQLite database with tables such as domains, hosts, contacts, credentials, and vulnerabilities.

Marketplace — the heart of Recon-ng

Since version 5, modules are not pre-installed. You must install them from the marketplace:

# See what is available:
[recon-ng][lab_example] > marketplace search

# Filter by keyword:
[recon-ng][lab_example] > marketplace search hackertarget

# Install a module:
[recon-ng][lab_example] > marketplace install recon/domains-hosts/hackertarget

# Bulk install everything that does not need API keys:
[recon-ng][lab_example] > marketplace install all

Examples of popular modules:

• recon/domains-hosts/hackertarget — subdomain enum via the HackerTarget API.
• recon/domains-hosts/certificate_transparency — subdomains from CT logs.
• recon/domains-contacts/whois_pocs — WHOIS contacts.
• recon/companies-multi/whois_miner — domains from WHOIS records.
• recon/hosts-hosts/resolve — DNS resolution.
• recon/hosts-ports/shodan_ip — Shodan service info (requires API key).
• recon/contacts-credentials/hibp_breach — Have I Been Pwned breach check.
• reporting/html — HTML report for the pentest deliverable.

First real run (lab placeholder)

# Create a workspace
recon-ng -w lab_example

# Install + load module
[recon-ng][lab_example] > marketplace install recon/domains-hosts/hackertarget
[recon-ng][lab_example] > modules load recon/domains-hosts/hackertarget
[recon-ng][lab_example][hackertarget] > info

# Configure target domain (placeholder)
[recon-ng][lab_example][hackertarget] > options set SOURCE example.com

# Execute
[recon-ng][lab_example][hackertarget] > run

# Inspect the discovered hosts in the database
[recon-ng][lab_example][hackertarget] > back
[recon-ng][lab_example] > db query SELECT * FROM hosts;

API keys — required for premium modules

# See which keys are supported:
[recon-ng][lab_example] > keys list

# Add keys (free tier in many sources):
[recon-ng][lab_example] > keys add shodan_api YOUR_SHODAN_KEY
[recon-ng][lab_example] > keys add hibp_api YOUR_HIBP_KEY
[recon-ng][lab_example] > keys add bing_api YOUR_BING_KEY

Keep your keys out of git and never publish them in public repositories.

Common mistakes

• Installing every module at once: marketplace install all can install modules that require API keys you do not own. Prefer targeted installation.
• Default workspace: Running multiple engagements in the same default workspace mixes the data. Always create a new workspace per engagement.
• Confusing Recon-ng v4 vs v5: Many older guides use v4 syntax (for example, use module instead of modules load). Always check your version.
• No rate limiting: APIs with low free tiers can throttle you quickly. Read the limits for each source.

Defensive / Blue team perspective

• Run Recon-ng against your own domains regularly — it surfaces shadow IT and forgotten assets.
• Monitor Certificate Transparency logs for new certificates issued for your domains — useful to detect rogue or phishing infrastructure.
• DNS hardening: disable AXFR, use DNSSEC, keep public hostnames to a minimum.
• Threat Intelligence loop: Findings from breach modules → user notification → password reset.

Best practices

• Create a new workspace per engagement.
• Start with passive modules before any active query.
• Export to an HTML report with reporting/html for the deliverable.
• Cross-validate with Amass and theHarvester for completeness.
• Back up ~/.recon-ng/workspaces/ when the engagement closes.

Summary

Recon-ng is a mature, modular framework for external reconnaissance and OSINT that stands out for its structured storage of findings and reuse of data across modules. In this Part 1 we installed the tool, understood workspaces and the marketplace, and executed our first module. In Part 2 we will look at complete recon workflows and integration with reporting modules.

Next steps

• Amass — subdomain enumeration
• theHarvester — email harvesting
• Maltego — OSINT link analysis
• All Information Gathering articles
• External references: Recon-ng on GitHub, MITRE TA0043.

For a complete OSINT and external reconnaissance curriculum, explore the courses at Audax Cybersecurity Academy.