recon-ng: OSINT framework for automated reconnaissance

recon-ng is a full-featured, modular web reconnaissance framework written in Python, designed with a workflow deliberately similar to Metasploit. Rather than being a single-purpose script, Recon-ng provides a persistent interactive console, a workspace-based project structure, a database backend, and dozens of independent modules for tasks such as subdomain enumeration, contact harvesting, credential-breach lookups, geolocation, and reporting. Its modularity and built-in data management make it ideal for organizing large, multi-source OSINT investigations rather than running one-off commands.

Installation

Recon-ng is pre-installed on Kali Linux.

# Kali/Debian
sudo apt update && sudo apt install recon-ng -y

# From source (any Linux distro with Python 3)
git clone https://github.com/lanmaster53/recon-ng.git
cd recon-ng
pip3 install -r REQUIREMENTS --break-system-packages
./recon-ng

Verify installation:

recon-ng --version

Syntax

Recon-ng is primarily an interactive console; it can also be scripted via a resource file or -r:

recon-ng [OPTIONS]

Inside the console, the general command pattern is:

[recon-ng][workspace] > COMMAND [ARGUMENTS]

Command-Line Options

Launch-time flags:

Flag	Description
-w, --workspace NAME	Load or create a specific workspace on startup
-r, --resource FILE	Execute a resource file (a script of console commands) on startup
--no-version	Disable the version check on startup
--stealth	Disable version check and marketplace calls for a fully offline/stealth start
-m, --module MODULE	Load a specific module immediately at startup
-C, --command COMMAND	Run a single command and exit
--accessible	Enable accessibility mode for screen readers

Console commands (used inside the interactive shell):

Command	Description
workspaces create NAME	Create a new workspace/project
marketplace search KEYWORD	Search for available modules in the marketplace
marketplace install MODULE	Install a module from the marketplace
modules load MODULE	Load a specific reconnaissance module
modules search KEYWORD	Search locally installed modules
info	Show details/options for the currently loaded module
options set OPTION VALUE	Set a module option (e.g., SOURCE)
run	Execute the currently loaded module
show TABLE	Display data from the database (hosts, contacts, domains, credentials)
db query SQL	Run a raw SQL query against the workspace database
add domains DOMAIN	Manually seed the database with a domain
keys add SOURCE KEY	Store an API key for a module/source
keys list	Show all configured API keys
back	Unload the current module
exit	Quit Recon-ng

Basic Usage

recon-ng

Expected output:

    _/_/_/    _/_/_/_/    _/_/_/    _/_/_/    _/      _/            _/      _/    _/_/_/
   _/    _/  _/        _/          _/    _/  _/_/    _/            _/_/    _/  _/
  _/_/_/    _/_/_/    _/          _/    _/  _/  _/  _/  _/_/_/_/  _/  _/  _/  _/  _/_/
 _/    _/  _/        _/          _/    _/  _/    _/_/            _/    _/_/  _/    _/
_/    _/  _/_/_/_/    _/_/_/    _/_/_/    _/      _/            _/      _/    _/_/_/

                                         /\
                                        /  \
      /\                              /    \                              /\
     /  \      /\    ______    /\    /      \    /\    ______    /\      /  \

[recon-ng][default] >

Practical Examples

Example 1 — Creating and switching to a new workspace

[recon-ng][default] > workspaces create acme-pentest
[recon-ng][acme-pentest] >

Example 2 — Adding a seed domain to the workspace database

[recon-ng][acme-pentest] > db insert domains
domain (TEXT): acme.com
[*] 1 rows affected.

Example 3 — Searching the module marketplace

[recon-ng][acme-pentest] > marketplace search hackertarget
[*] recon/domains-hosts/hackertarget

Example 4 — Installing and loading a module

[recon-ng][acme-pentest] > marketplace install recon/domains-hosts/hackertarget
[*] Module installed: recon/domains-hosts/hackertarget

[recon-ng][acme-pentest] > modules load recon/domains-hosts/hackertarget
[recon-ng][acme-pentest][hackertarget] >

Example 5 — Viewing module options

[recon-ng][acme-pentest][hackertarget] > info

Name: HackerTarget Lookup
Author: Tim Tomes
Description: Uses the hackertarget.com API to harvest subdomains.

Options
=======
  Name    Current Value  Required  Description
  ----    -------------  --------  -----------
  SOURCE  default        yes       source of input (see 'show info')

Example 6 — Running a module against the workspace’s seed domain

[recon-ng][acme-pentest][hackertarget] > run

[*] URL: https://api.hackertarget.com/hostsearch/?q=acme.com
[*] www.acme.com => 93.184.216.34
[*] mail.acme.com => 93.184.216.35
[*] 2 total (2 new) hosts found.

Example 7 — Viewing all discovered hosts

[recon-ng][acme-pentest][hackertarget] > show hosts

+----+-----------------+---------------+
| id | host            | ip_address    |
+----+-----------------+---------------+
| 1  | www.acme.com    | 93.184.216.34 |
| 2  | mail.acme.com   | 93.184.216.35 |
+----+-----------------+---------------+

Example 8 — Loading and running a contact-harvesting module

[recon-ng][acme-pentest] > modules load recon/domains-contacts/whois_pocs
[recon-ng][acme-pentest][whois_pocs] > run

[*] Discovered contact: John Admin (admin@acme.com)
[*] 1 total (1 new) contacts found.

Example 9 — Generating an HTML report

[recon-ng][acme-pentest] > marketplace install reporting/html
[recon-ng][acme-pentest] > modules load reporting/html
[recon-ng][acme-pentest][html] > options set CREATOR "Pentester"
[recon-ng][acme-pentest][html] > run
[*] Report generated: /root/.recon-ng/workspaces/acme-pentest/results.html

Example 10 — Running Recon-ng non-interactively via a resource file

cat commands.rc
# workspaces create acme
# db insert domains
# acme.com
# modules load recon/domains-hosts/hackertarget
# run
# exit

recon-ng -r commands.rc

[*] Executing resource file: commands.rc
[*] 2 total (2 new) hosts found.

Common Use Cases

• Centralized, database-backed management of large OSINT engagements spanning domains, hosts, contacts, and credentials.
• Chaining multiple modules together where one module’s output (e.g., discovered domains) automatically feeds the next module’s input (e.g., contact harvesting).
• Generating polished HTML/CSV/JSON client reports directly from gathered reconnaissance data.
• Running fully scripted, non-interactive recon workflows via resource files for repeatable engagements.
• Checking discovered email addresses against breach databases using credential-related modules.

Automation with Bash

Wrap a full Recon-ng workflow into a single bash-triggered resource file:

#!/bin/bash
# recon_ng_auto.sh
DOMAIN=$1
WORKSPACE=$(echo "$DOMAIN" | tr '.' '_')

cat > /tmp/recon_commands.rc <<EOF
workspaces create $WORKSPACE
db insert domains
$DOMAIN
modules load recon/domains-hosts/hackertarget
run
modules load recon/domains-contacts/whois_pocs
run
show hosts
show contacts
exit
EOF

recon-ng -r /tmp/recon_commands.rc

Export workspace results to CSV using the built-in reporting module in an automated script:

#!/bin/bash
DOMAIN=$1
WORKSPACE=$(echo "$DOMAIN" | tr '.' '_')

cat > /tmp/recon_export.rc <<EOF
workspaces load $WORKSPACE
marketplace install reporting/csv
modules load reporting/csv
run
exit
EOF

recon-ng -r /tmp/recon_export.rc

Tips and Best Practices

• Always create a dedicated workspace per client/engagement (workspaces create) — never mix data from multiple clients in the default workspace.
• Use keys add to configure API keys once per install (e.g., Shodan, Hunter.io, Bing) so every module that needs them works without repeated prompts.
• Use marketplace search liberally — Recon-ng’s module ecosystem has grown significantly since v5, and many useful modules are not installed by default.
• Build resource files (.rc) for repeatable, standardized recon workflows across engagements — this also makes results auditable and reproducible.
• Use show schema to understand the database structure before writing custom db query SQL commands.

Troubleshooting

Problem	Cause	Fix
Module fails with [!] Module failed: missing API key	Required API key not configured	Run keys add SOURCE_NAME your_api_key before re-running the module
marketplace install fails / no internet	Recon-ng cannot reach the module marketplace	Check connectivity, or use --stealth for fully offline module use with pre-installed modules only
Workspace data missing after reopening Recon-ng	Loaded the wrong workspace, or used default accidentally	Use workspaces list and workspaces load NAME to confirm the correct workspace is active
Old/deprecated module syntax errors (v4 vs v5 differences)	Following outdated tutorials for Recon-ng v4	Refer to the current v5+ documentation; module paths and commands changed significantly between major versions

References

• Official GitHub repository: https://github.com/lanmaster53/recon-ng
• Recon-ng wiki/documentation: https://github.com/lanmaster53/recon-ng/wiki
• Kali Linux tool page: https://www.kali.org/tools/recon-ng/