Clone wiki

Recon-ng / Usage Guide


Migration Notes

  • [2015-05-14] Starting with Recon-ng v4.6.0, framework dependencies are no longer included and must be installed prior to use. Please see Recon-ng Update (v4.6.0) for more information.
  • [2014-06-04] All migrations for Recon-ng v4.0.0 occur automatically. However, migrated workspaces may not be backwards compatible. Please see Recon-ng Update (v4.0.0) for more information.
  • [2014-01-16] As of version 3.3.0, Recon-ng persists module options between sessions. If upgrading to >= 3.3.0, it is recommended that all old configuration files be purged (rm ~/.recon-ng/workspaces/*/config.dat). Failure to remove old configuration files will result in a failure to load saved option values.

Getting Started

Installation - Kali Linux

  • Install Recon-ng
    • apt-get update && apt-get install recon-ng

Installation - Source

  • Clone the Recon-ng repository.
    • git clone
  • Change into the Recon-ng directory.
    • cd recon-ng
  • Install dependencies.
    • pip install -r REQUIREMENTS
  • Launch Recon-ng.
    • ./recon-ng
  • Use the "-h" switch for information on runtime options.
    • ./recon-ng -h

Helpful Resources


  • All 3rd party libraries/packages should be installed prior to use. The framework checks for the presence of dependencies at runtime and disables the modules affected by missing dependencies.

Usage Notes

Below are a few helpful nuggets for getting started with the Recon-ng framework. While not all features are covered, the following notes will help make sense of a few of the frameworks more helpful and complex features.

  • Users will likely create and share custom modules that are not merged into the master branch of the framework. In order to allow for the use of these modules without interfering with installed package, the framework allows for the use of a custom module tree placed in the user's "home" directory. In order to leverage this feature, a directory named "modules" must be created underneath the ".recon-ng" directory, i.e. "~/.recon-ng/modules/". Custom modules that are added to the "~/.recon-ng/modules/" directory are loaded into the framework at runtime. Where the modules are placed underneath the "~/.recon-ng/modules/" directory doesn't affect functionality, but things will look much nicer in the framework if the proper module directory tree is replicated and the modules are placed in the proper category.
  • Modules are organized to facilitate the flow of a penetration test, and there are separate module branches within the module tree for each methodology step. Reconnaissance, Discovery, Exploitation and Reporting are steps 1, 3, 4 and 5 of the Web Application Penetration Testing Methodology. Therefore, each of these steps has their own branch in the module tree. It is important to understand the difference between Reconnaissance and Discovery. Reconnaissance is the use of open sources to gain information about a target, commonly referred to as "passive reconnaissance". Discovery, commonly referred to as "active reconnaissance", occurs when packets are explicitly sent to the target network in an attempt to "discover" vulnerabilities. While Recon-ng is a reconnaissance framework, elements from the other steps of the methodology will be included as a convenient place to leverage the power of Python.
  • After loading a module, the context of the framework changes, and a new set of commands and options are available. These commands and options are unique to the module. Use the "help" and "show" commands to gain familiarity with the framework and available commands and options at the root (global) and module contexts.
  • The "info" and "source" subcommands of "show" (available only in the module context) are particularly helpful ways to discover the capabilities of the framework. The "show info" command will return detailed information about the loaded module, and the "show source" command will display its source code. Spend some time exploring modules with the "show info" and "show source" commands to get a sense for how information flows through the framework.
  • The "query" command assists in managing and understanding the data stored in the database. Users are expected to know and understand Structured Query Language (SQL) in order to interact with the database via the "query" command. The "show schema" command provides a graphical representation of the database schema to assist in building SQL queries. The "show schema" command creates the graphical representation dynamically, so as the schema of the database changes, so will the result of the command.
  • Pay attention to the global options, as they have changed over time and have a large impact on the performance of the framework. Many of the online tutorials regarding Recon-ng are outdated and misrepresent the purpose of Global options as they stand now. Global options are the options that are available at the root (global) context of the framework and have a global effect on how the framework operates. Global options such as "VERBOSITY" and "PROXY" drastically change how the modules present feedback and make web requests. Explore and understand the global options before diving into the modules.
  • The modular nature of the framework requires frequently switching between modules and setting options unique to each one. It can become taxing having to repeatedly set module options as information flows through the framework. Therefore, option values for all contexts within the framework are stored locally and loaded dynamically each time the context is loaded. This provides persistence to the configuration of the framework between sessions.
  • Workspaces help users to conduct multiple simultaneous engagements without having to repeatedly configure global options or databases. All of the information for each workspace is stored in its own directory underneath the "~/.recon-ng/workspaces/" folder. Each workspace consists of its own instance of the Recon-ng database, a configuration file for the storage of configuration options, reports from reporting modules, and any loot that is gathered from other modules. To create a new workspace, use the "workspaces" command, workspaces add <name>. Loading an existing workspace is just as easy, workspaces select <name>. To view a list of available workspaces, see the "workspaces list" command or the "show workspaces" alias. To delete a workspace, use the "workspaces delete" command, workspaces delete <name>. Workspaces can also be created or loaded at runtime by invoking the "-w <workspace>" argument when executing Recon-ng, ./recon-ng -w bhis.
  • The "search" command provides the capability to search the names of all loaded modules and present the matches to the user. The "search" command can be very helpful in determining what to do next with the information that has been harvested, or identifying what is required to get the desired information. The "recon" branch of the module tree follows the following path structure: recon/<input table>-<output table>/<module>. This provides simplicity in determining what module is available for the action the user wants to take next. To see all of the modules which accept a domain as input, search for the input table name "domains" followed by a dash: search domains-. To see all of the modules which result in harvested hosts, search for the output table name "hosts" with a preceding dash: search -hosts.
  • The entire framework is equipped with command completion. Whether exploring standard commands, or passing parameters to commands, tap the "tab" key several times to be presented with all of the available options for that command or parameter.
  • Even with command completion, module loading can be cumbersome because of the directory structure of the module tree. To make module loading easier, the framework is equipped with a smart loading feature. This feature allows modules to be loaded by referring to a keyword unique to the desired module's name. For instance, use namechk will load the "recon/contacts-contacts/namechk" module without requiring the full path since it is the only module containing the string "namechk". Attempting to smart load with a string that exists in more than one module name will result in a list of all possible modules for the given keyword. For example, there are many modules whose names contain the string "pwned". Therefore, the command use pwned would not load a module, but return a list of possible modules for the user to reference by full module name.
  • Every piece of information stored in the Recon-ng database is a potential input "seed" from which new information can be harvested. The "add" command allows users to add initial records to the database which will become input for modules. Modules take the seed data, transform it into other data types, and store the data in the database as potential input for other modules. Each module has a "SOURCE" option which determines the seed data. The "SOURCE" option provides flexibility in what the user can provide to modules as input. The "SOURCE" option allows users to select "default", which is seed data from the database as determined by the module developer, a single entry as a string, the path to a file, or a custom SQL query. The framework will detect the source and provide it as input to the module. Changing the "SOURCE" option of a module does not affect how the module handles the resulting information.
  • While the "shell" command and "!" alias give users the ability to run system commands on the local machine from within the framework, neither of these commands is necessary to achieve this functionality. Any input that the framework does not understand as a framework command is executed as a system command. Therefore, the only time that "shell" or "!" is necessary is when the desired command shares the same name as a framework command.
  • A recorded session of all activity is essential for many penetration testers, but built-in OS tools like "tee" and "script" break needed functionality, like tab completion, and muck with output formatting. To solve this dilemma, the framework is equipped with the ability to spool all activity to a file for safe keeping. The "spool" command gives users the ability to start and stop spooling, or check the current spooling status. The destination file for the spooled data is set as a parameter of the "spool start" command, spool start <filename>. Use help spool for more information on the "spool" command.
  • Backing up data at important points during the reconnaissance process helps to prevent the loss or corruption of data due to unexpected resource behavior. The "snapshots" command gives users the ability to backup and restore snapshots of the database. Use help snapshots for more information on the "snapshots" command.

Acquiring API Keys

  • Bing API Key (bing_api) - Sign up for the free 90-day trial subscription to the Bing Search API here. Sign in to Microsoft Cognitive Services and go to the "My Account" tab. Click "Subscribe to new free trials" and get a key for "Bing Search - Free". The API key will be available under the "Bing Search" heading on the "My Account" page.
  • BuiltWith API Key (builtwith_api) - Sign up for a free account here. Sign in to the application. The API key will be available in the upper right hand portion of the screen.
  • Censys API Key (censysio_id) - TBD
  • Censys API Secret (censysio_secret) - TBD
  • Flickr API Key (flickr_api) - Create a Flickr account here. Apply for an API key here and select "APPLY FOR A NON-COMMERCIAL KEY". Enter the name of your application. Enter a description of what you are building. Check the "I acknowledge that Flickr members own all rights to their content, and that it’s my responsibility to make sure that my project does not contravene those rights." disclaimer. Read the Flickr API Terms of Use. Check the "I agree to comply with the Flickr API Terms of Use." box. There will be a 32 character "Key" and a 16 character "Secret". Recon-ng uses the "Key" only.
  • FullContact API Key (fullcontact_api) - TBD
  • Google API Key (google_api) - Create an API Project here. The API key will be available in the Credentials section of the API Manager console. Be sure to enable the relevant APIs.
    • YouTube Data API
    • Custom Search API
  • Google Custom Search Engine (CSE) ID (google_cse) - Create a CSE here. The CSE ID will be available in the CSE management console. Read here for guidance on configuring the CSE to search the entire web. Otherwise, the CSE will be restricted to only searching domains specified within the CSE management console. This will drastically effect the results of any module which leverages the CSE.
  • Github API Key (github_api) - TBD
  • API Key (hashes_api) - TBD
  • IPInfoDB API Key (ipinfodb_api) - Create a free account here. Log in to the application here. The API key will be available on the "Account" tab.
  • Jigsaw API Key (jigsaw_api) - Create an account and sign up for the $1,500/year plan here. A corporate email address is preferred. Submit a request for an API token here using the same email address that was used to create the paid account. The Jigsaw API team will look up the account to validate that it is a paid membership and issue an API token. NOTE: This is not a confirmed process, so proceed with care. If nothing else, call Salesforce and ask how to get an API key.
  • PwnedList API Key (pwnedlist_api) - Contact PwnedList directly regarding API access.
  • PwnedList Initialization Vector (pwnedlist_iv) - Contact PwnedList directly regarding API access.
  • PwnedList Secret (pwnedlist_secret) - Contact PwnedList directly regarding API access.
  • Shodan API Key (shodan_api) - Create an account or sign in to Shodan using one of the many options available here. The API key will be available on the right side of the screen. An upgraded account is required to access advanced search features.
  • Twitter Consumer Key (twitter_api) - Create an application here. The Consumer key will be available on the application management page.
  • Twitter Consumer Secret (twitter_secret) - The Consumer secret will be available on the application management page for the application created above.

Scripting the Framework

  • The entire framework is scriptable through the use of a resource file. A resource file is a plain text file containing a list of commands for the framework. By referencing the resource file when executing Recon-ng, ./recon-ng -r <filename>, the framework will read in the list of commands from the file and feed them to the command interpreter, in sequence. The resource file does not have to end by exiting the framework. The framework will automatically detect the end of the resource file and hand stdin back over to the terminal session for user input. The script is complete when the framework prompt looks like this: recon-ng > EOF.
  • To make it easy to create resource files, the framework is equipped with the ability to record commands. The "record" command gives users the ability to start and stop command recording, or check the current recording status. The destination file for the recorded commands is set as a parameter of the "record start" command, record start <filename>. Use help record for more information on the "record" command.
  • If external shell scripting is preferred, the framework includes a tool called ./ which makes all of the functionality of the Recon-ng framework accessible from the command line. Use ./ -h for information on runtime options.


The Recon-ng project consists of a one-man development team in terms of sustaining the framework. When things break, as they often do when dealing with evolving web technologies, users don't got to the module developer, they go to the Recon-ng Issue Tracker or directly to me. As the framework grows, module issues become more and more frequent. I needed a way to "trim the fat" in the framework and determine the best approach to maintaining broken modules. Therefore, I decided to add an analytics element (eab6307) which would allow me to track the most commonly used modules. That way, when a user comes to me and says, "There is a problem with module X." I can look at my analytics and determine whether or not it is worth the effort to fix myself, ask them to fix, or remove from the framework all together.

Initially, I had a few folks notice and complain, citing issues with custom modules being reported and not having the ability to disable the system completely. Both of these items have been addressed (717c7c6). Overall, it is a system that helps me more efficiently maintain the framework. The only thing attributable to the user is their IP address. To me, this is a non-issue. People use the Internet every day to visit web pages and logically attribute themselves to shady places. There is no such thing as "leaking" an external IP address. It is a part of layer 3 communication and the way the Internet works. If you don't want your IP leaked, don't use the Internet, or use an anonymizing service. There is no targeting or harvested information included in the analytics. I encourage users to watch the traffic and validate for themselves.

The first time Recon-ng runs, it creates a file in the user's home ~/.recon-ng directory called .cid. It is a randomly generated UUID that is non-specific to the system. That UUID is sent with each analytics request to differentiate users, allowing me to track how many different users are using the module. There is a big difference between one person using a module 3,000 times in a day, and 3,000 users using a module once a day. I need to know this in order to make good maintenance decisions. Analytics requests are sent each time a module is loaded using the load or use command. The analytics request includes the UUID, the module name, and the version of Recon-ng. No analytics requests are made when loading custom modules (modules that reside in the users home ~/.recon-ng/modules/ directory), and the entire system can be disabled by running Recon-ng with the --no-analytics flag. See the ./recon-ng -h help menu for more information.

Additional Help

Recon-ng has an official IRC channel (#recon-ng) located on the Freenode network. For additional help, information, and general discussion about the framework, connect to Freenode and join the channel using the /join #recon-ng command.