How to Use Recon-ng for OSINT: Workspaces, Modules, API Keys and Reports

Key takeaways

• Recon-ng organises reconnaissance into workspaces, a database of results, and modules that each query one data source.
• Most modules are passive: they ask third-party services what is already known, rather than touching the target. That still needs a defined scope on an engagement.
• Many useful modules need an API key. The free tiers of those services have limits.
• Collected data is personal and company information. Store it securely, keep to scope and delete it when the engagement ends.

What is Recon-ng for?

Reconnaissance is the first phase of a security assessment: learning what an organisation exposes before anyone tests it. Recon-ng, which is maintained as an open-source project at github.com/lanmaster53/recon-ng, automates the gathering of public information such as subdomains, IP addresses, contacts and leaked data, and keeps everything in one place.

It suits two jobs: building an inventory of an organisation's internet-facing assets for an authorised test, and learning how OSINT works. For a broader introduction, see what Recon-ng is and how ethical hackers use it.

Scope and legality first

Use a domain you own or one you have written permission to assess. Passive lookups are lower risk than active scanning, but they can still go outside the agreed scope, and the data collected may include personal details. In this guide, yourdomain.example stands for your own lab domain. Replace it with a domain you control, and do not point these steps at a real third-party organisation without permission, as the IT Act, 2000 applies to unauthorised access, and many programmes also forbid certain data collection.

Install and start

On Kali Linux it is a package:

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

On other systems, clone the project from GitHub and follow its README, which lists the Python requirements. You will see a prompt like [recon-ng][default] >. Type help to list commands. The command set differs a little between versions, so rely on help and the project wiki if a command here is not accepted.

What are the core concepts?

• Workspace: a separate project with its own database, so one engagement's data never mixes with another's.
• Database tables: domains, hosts, contacts, credentials, netblocks and more. Modules read from some tables and write to others.
• Modules: small plug-ins grouped by what they take in and give out, such as recon/domains-hosts/, which turns a domain into hosts.
• Marketplace: modules are installed on demand with the marketplace command.
• Keys: API keys are stored once and shared by all modules that need them.

Step-by-step workflow

1. How do you create a workspace?

[recon-ng][default] > workspaces create lab_project
[recon-ng][lab_project] > workspaces list

2. Seed the database with your scope

[recon-ng][lab_project] > db insert domains
domain (TEXT): yourdomain.example
notes (TEXT):

3. Find and install modules

[recon-ng][lab_project] > marketplace refresh
[recon-ng][lab_project] > marketplace search hackertarget
[recon-ng][lab_project] > marketplace install recon/domains-hosts/hackertarget
[recon-ng][lab_project] > modules search

4. Load, configure and run a module

[recon-ng][lab_project] > modules load recon/domains-hosts/hackertarget
[recon-ng][lab_project][hackertarget] > info
[recon-ng][lab_project][hackertarget] > options set SOURCE yourdomain.example
[recon-ng][lab_project][hackertarget] > run

Always run info first. It shows what the module needs, what it writes and whether a key is required. Without a SOURCE option, many modules default to every row in the relevant table.

5. Add API keys

Many data sources need a key. Create a free account with the service, then add the key.

[recon-ng][lab_project] > keys add shodan_api YOUR_KEY_HERE
[recon-ng][lab_project] > keys list

The key name must match what the module expects, which info shows. Treat keys as secrets: they are stored in the ~/.recon-ng/ directory on your machine, so do not share that folder or commit it to a repository.

6. Review what you found

[recon-ng][lab_project] > show domains
[recon-ng][lab_project] > show hosts
[recon-ng][lab_project] > show contacts
[recon-ng][lab_project] > dashboard

Chain modules. For instance, the hosts you find can feed a resolver module that adds IP addresses, and those can feed lookup modules that add location or network owner data. Each step enriches the database.

7. Export and keep records

[recon-ng][lab_project] > spool start session.log
[recon-ng][lab_project] > modules load reporting/csv
[recon-ng][lab_project][csv] > options set TABLE hosts
[recon-ng][lab_project][csv] > options set FILENAME /home/kali/hosts.csv
[recon-ng][lab_project][csv] > run

Other reporting modules write HTML, JSON and XML. The spool start line at the top logs the session to a file, and spool stop ends it.

Useful command summary

Common problems

• Module not found: install it first from the marketplace, and run marketplace refresh if the list looks old.
• Module needs a key: run info and add the named key.
• No results: check the SOURCE spelling, rate limits on free API tiers, and whether the data source has anything on the domain.
• Data looks wrong: third-party data goes stale. Verify important findings with a second source or directly, within scope.
• Some marketplace modules fail: modules depend on external services that change or disappear. Try another module that gives the same kind of data.

From recon to defence

The point of reconnaissance is a better defence. Typical findings are forgotten subdomains, staging servers on the public internet, exposed email patterns and old contacts. An organisation can fix those by removing unused DNS records, restricting staging systems and reviewing what public registries show. Report them with that advice. Recon-ng is also used in bug bounty, and the best tools used in bug bounty hunting post puts it in context. Programme rules decide what you may collect.

Next steps

Practise on your own domain, then continue with advanced reconnaissance with Recon-ng. If you want structured training, the CEH v13 AI course includes reconnaissance within an authorised-testing framework.

Related reading

• How can I automate recon and detect subdomain takeovers using tools like Amass, Subfinder, and Nuclei?
• Metasploit Database Configuration | Setting Up database.yml for Persistent PostgreSQL Connection in Kali Linux