Recon-ng OSINT Framework Tutorial for Beginners

Recon-ng is one of the most powerful open-source OSINT frameworks available to penetration testers and security researchers. Built in Python and modeled after the Metasploit Framework’s interface, it provides a modular environment for conducting web-based open-source reconnaissance. In this tutorial, you will learn how to set up Recon-ng, organize investigations with workspaces, load and configure modules, add API keys, and build a comprehensive target profile — all without ever touching the target directly.

What Is Recon-ng?

Recon-ng is a full-featured reconnaissance framework that automates the process of gathering intelligence from open sources. It ships with dozens of modules that query services like HaveIBeenPwned, Shodan, VirusTotal, GitHub, LinkedIn, and many more. Because all activity happens through third-party APIs and public data, it constitutes passive reconnaissance — no packets are sent to your target.

Recon-ng comes pre-installed on Kali Linux and Parrot OS. On other Debian-based systems, install it with:

sudo apt install recon-ng

Or install from source:

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

Understanding the Interface

Launch Recon-ng:

recon-ng

You are dropped into an interactive console that feels immediately familiar if you have used Metasploit. The prompt shows your current workspace:

[recon-ng][default] >

Key commands to know:

Command	Description
help	Show all available commands
workspaces list	List all workspaces
workspaces create <name>	Create a new workspace
workspaces load <name>	Switch to a workspace
modules search <term>	Search available modules
modules load <path>	Load a module
marketplace search <term>	Search the module marketplace
marketplace install <path>	Install a module
db schema	View the database tables
show hosts	List hosts discovered so far

Working with Workspaces

Workspaces are isolated databases that keep each investigation separate. Always create a dedicated workspace for each target.

workspaces create example_corp
workspaces load example_corp

Your prompt changes to reflect the active workspace:

[recon-ng][example_corp] >

All data gathered — domains, hosts, contacts, credentials, ports — is stored in this workspace’s SQLite database. You can export results at any time:

db export csv /home/user/reports/example_corp.csv

Adding Seed Data

Before running modules, seed the workspace with your starting data. The most common seed is a root domain:

db insert domains
domain (TEXT): example.com
notes (TEXT): primary target domain

You can also insert company names, network ranges, and email addresses as seeds:

db insert companies
db insert netblocks
db insert contacts

Discovering and Installing Modules

The module marketplace lets you browse and install community-contributed modules. Search for relevant ones:

marketplace search domains
marketplace search whois
marketplace search github

Install a module you want:

marketplace install recon/domains-hosts/hackertarget
marketplace install recon/domains-contacts/whois_pocs
marketplace install recon/hosts-ports/shodan_ip

List all currently installed modules:

modules search

Using Modules: Step-by-Step

Load a module with the modules load command, then configure its options with options set:

modules load recon/domains-hosts/hackertarget

Check required options:

options list

Set the source (this pulls from your workspace’s domains table automatically if set to default):

options set SOURCE example.com
run

After execution, discovered hosts are added to the hosts table:

show hosts

Finding Email Addresses

The whois_pocs module pulls contact emails from WHOIS records:

modules load recon/domains-contacts/whois_pocs
options set SOURCE example.com
run
show contacts

Enumerating Subdomains

Chain multiple modules to build a rich host list:

modules load recon/domains-hosts/brute_hosts
options set SOURCE example.com
run

modules load recon/domains-hosts/certificate_transparency
options set SOURCE example.com
run

Checking for Credential Leaks

modules load recon/contacts-credentials/hibp_breach
run
show credentials

Configuring API Keys

Most powerful modules require API keys from third-party services. Without them, modules either fail or return limited results. Store keys in Recon-ng once and they are available across all workspaces:

keys add shodan_api <your_api_key>
keys add github_api <your_github_token>
keys add virustotal_api <your_api_key>
keys add hunter_api <your_hunter_io_key>
keys list

Recommended free API keys to obtain:

Service	URL	What It Unlocks
Shodan	shodan.io	IP/port/banner data
Hunter.io	hunter.io	Email discovery
VirusTotal	virustotal.com	Domain/IP reputation
GitHub	github.com	Code/secret leaks
HaveIBeenPwned	haveibeenpwned.com	Credential breach data
SecurityTrails	securitytrails.com	DNS history

Once keys are added, reload the relevant modules and run them again — you’ll receive substantially more results.

Building a Full Target Profile

A realistic OSINT workflow strings together multiple module types in sequence:

domains → hosts → IPs → ports/services → contacts → credentials

Here is a practical sequence:

# 1. Seed the domain
db insert domains
# (enter: example.com)

# 2. Find subdomains
modules load recon/domains-hosts/certificate_transparency
run

modules load recon/domains-hosts/hackertarget
run

# 3. Resolve IPs
modules load recon/hosts-hosts/resolve
run

# 4. Grab Shodan data for each IP
modules load recon/hosts-ports/shodan_ip
run

# 5. Pull contacts
modules load recon/domains-contacts/whois_pocs
run

# 6. Check for breaches
modules load recon/contacts-credentials/hibp_breach
run

# 7. Review everything
show hosts
show ports
show contacts
show credentials

Generating Reports

Recon-ng includes reporting modules to produce HTML, CSV, and JSON output:

modules load reporting/html
options set FILENAME /home/user/reports/example_corp.html
options set CREATOR "Your Name"
options set CUSTOMER "Example Corp"
run

Open the generated HTML file in a browser for a clean, shareable report.

Practical Tips

• Always use workspaces — never run multiple investigations in the default workspace or data will mix.
• Chain modules — each module’s output becomes the next module’s input automatically via the database.
• Check show dashboard — gives a quick count of all collected data types.
• Use pdb cautiously — the built-in Python debugger can help troubleshoot broken modules.
• Rate limit awareness — some APIs have strict call limits. Space out module runs when working with free tiers.

Legal and Ethical Considerations

Recon-ng queries public data sources and third-party APIs — it does not send traffic to the target. However, you must still obtain written authorization before conducting any reconnaissance on systems or organizations you do not own. OSINT gathered without permission can still violate computer fraud laws in many jurisdictions depending on how the data is used. Always operate within the scope of an authorized engagement.

Summary

Recon-ng transforms manual OSINT research into a structured, repeatable, and automated workflow. By mastering workspaces, modules, and API key integration, you can build detailed target profiles — subdomains, email addresses, open ports, leaked credentials — in a fraction of the time manual searching would take. It is an essential tool for any penetration tester’s reconnaissance phase and a natural complement to tools like Maltego, theHarvester, and Shodan.