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 thedefaultworkspace. - Use
keys addto configure API keys once per install (e.g., Shodan, Hunter.io, Bing) so every module that needs them works without repeated prompts. - Use
marketplace searchliberally — 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 schemato understand the database structure before writing customdb querySQL 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/