There are an accompanying set of blog posts detailing the development process and underpinnings of the pipeline. Feel free to check them out if you're so inclined, but they're in no way required reading to use the tool.
Check out recon-pipeline's readthedocs entry for some more in depth information than what this README provides.
- Installation
- Defining Scope
- Example Scan
- Viewing Results
- Chaining Results w/ Commands
- Choosing a Scheduler
- Found a Bug?
- Special Thanks
Automatic installation tested on kali 2019.4 and Ubuntu 18.04/20.04
There are two primary phases for installation:
- prior to the python dependencies being installed
- everything else
First, the manual steps to get dependencies installed in a virtual environment are as follows, starting with pipenv
sudo apt update
sudo apt install pipenvsudo apt update
sudo apt install python3-pip
pip install --user pipenv
echo "PATH=${PATH}:~/.local/bin" >> ~/.bashrc
bashgit clone https://github.com/epi052/recon-pipeline.git
cd recon-pipeline
pipenv install
pipenv shellAfter installing the python dependencies, the recon-pipeline shell provides its own install command (seen below). A simple install all will handle all additional installation steps.
Ubuntu Note (and newer kali versions): You may consider running
sudo -vprior to running./recon-pipeline.py.sudo -vwill refresh your creds, and the underlying subprocess calls during installation won't prompt you for your password. It'll work either way though.
Individual tools may be installed by running install TOOLNAME where TOOLNAME is one of the known tools that make
up the pipeline.
The installer maintains a (naive) list of installed tools at ~/.local/recon-pipeline/tools/.tool-dict.pkl. The installer in no way attempts to be a package manager. It knows how to execute the steps necessary to install its tools. Beyond that, it's like Jon Snow, it knows nothing.
New as of v0.9.0: In the event you're scanning a single ip address or host, simply use --target. It accepts a single target and works in conjunction with --exempt-list if specified.
scan HTBScan --target 10.10.10.183 --top-ports 1000
In order to scan more than one host at a time, the pipeline needs a file that describes the target's scope to be provided as an argument to the --target-file option. The target file can consist of domains, ip addresses, and ip ranges, one per line.
tesla.com
tesla.cn
teslamotors.com
...
Some bug bounty scopes have expressly verboten subdomains and/or top-level domains, for that there is the --exempt-list option. The exempt list follows the same rules as the target file.
shop.eu.teslamotors.com
energysupport.tesla.com
feedback.tesla.com
...
Here are the steps the video below takes to scan tesla.com.
Create a targetfile
# use virtual environment
pipenv shell
# create targetfile; a targetfile is required for all scans
mkdir /root/bugcrowd/tesla
cd /root/bugcrowd/tesla
echo tesla.com > tesla-targetfile
# create a blacklist (if necessary based on target's scope)
echo energysupport.tesla.com > tesla-blacklist
echo feedback.tesla.com >> tesla-blacklist
echo employeefeedback.tesla.com >> tesla-blacklist
echo ir.tesla.com >> tesla-blacklist
# drop into the interactive shell
/root/PycharmProjects/recon-pipeline/pipeline/recon-pipeline.py
recon-pipeline>Create a new database to store scan results
recon-pipeline> database attach
1. create new database
Your choice? 1
new database name? (recommend something unique for this target)
-> tesla-scan
[*] created database @ /home/epi/.local/recon-pipeline/databases/tesla-scan
[+] attached to sqlite database @ /home/epi/.local/recon-pipeline/databases/tesla-scan
[db-1] recon-pipeline>Scan the target
[db-1] recon-pipeline> scan FullScan --exempt-list tesla-blacklist --target-file tesla-targetfile --interface eno1 --top-ports 2000 --rate 1200
[-] FullScan queued
[-] TKOSubsScan queued
[-] GatherWebTargets queued
[-] ParseAmassOutput queued
[-] AmassScan queued
[-] ParseMasscanOutput queued
[-] MasscanScan queued
[-] WebanalyzeScan queued
[-] SearchsploitScan queued
[-] ThreadedNmapScan queued
[-] SubjackScan queued
[-] WaybackurlsScan queued
[-] AquatoneScan queued
[-] GobusterScan queued
[db-1] recon-pipeline>The same steps can be seen in realtime in the linked video below.
When running additional scans against the same target, you have a few options. You can either
- use a new directory
- reuse the same directory
If you use a new directory, the scan will start from the beginning.
If you choose to reuse the same directory, recon-pipeline will resume the scan from its last successful point. For instance, say your last scan failed while running nmap. This means that the pipeline executed all upstream tasks (amass and masscan) successfully. When you use the same results directory for another scan, the amass and masscan scans will be skipped, because they've already run successfully.
Note: There is a gotcha that can occur when you scan a target but get no results. For some scans, the pipeline may still mark the Task as complete (masscan does this). In masscan's case, it's because it outputs a file to results-dir/masscan-results/ whether it gets results or not. Luigi interprets the file's presence to mean the scan is complete.
In order to reduce confusion, as of version 0.9.3, the pipeline will prompt you when reusing results directory.
[db-2] recon-pipeline> scan FullScan --results-dir testing-results --top-ports 1000 --rate 500 --target tesla.com
[*] Your results-dir (testing-results) already exists. Subfolders/files may tell the pipeline that the associated Task is complete. This means that your scan may start from a point you don't expect. Your options are as follows:
1. Resume existing scan (use any existing scan data & only attempt to scan what isn't already done)
2. Remove existing directory (scan starts from the beginning & all existing results are removed)
3. Save existing directory (your existing folder is renamed and your scan proceeds)
Your choice?
As of version 0.9.0, scan results are stored in a database located (by default) at ~/.local/recon-pipeline/databases. Databases themselves are managed through the database command while viewing their contents is done via view command.
The view command allows one to inspect different pieces of scan information via the following sub-commands
- endpoints (gobuster results)
- nmap-scans
- ports
- searchsploit-results
- targets
- web-technologies (webanalyze results)
Each of the sub-commands has a list of tab-completable options and values that can help drilling down to the data you care about.
All of the subcommands offer a --paged option for dealing with large amounts of output. --paged will show you one page of output at a time (using less under the hood).
A few examples of different view commands are shown below.
All of the results can be piped out to other commands. Let’s say you want to feed some results from recon-pipeline into another tool that isn’t part of the pipeline. Simply using a normal unix pipe | followed by the next command will get that done for you. Below is an example of piping targets into gau
[db-2] recon-pipeline> view targets --paged
3.tesla.cn
3.tesla.com
api-internal.sn.tesla.services
api-toolbox.tesla.com
api.mp.tesla.services
api.sn.tesla.services
api.tesla.cn
api.toolbox.tb.tesla.services
...
[db-2] recon-pipeline> view targets | gau
https://3.tesla.com/pt_PT/model3/design
https://3.tesla.com/pt_PT/model3/design?redirect=no
https://3.tesla.com/robots.txt
https://3.tesla.com/sites/all/themes/custom/tesla_theme/assets/img/icons/favicon-160x160.png?2
https://3.tesla.com/sites/all/themes/custom/tesla_theme/assets/img/icons/favicon-16x16.png?2
https://3.tesla.com/sites/all/themes/custom/tesla_theme/assets/img/icons/favicon-196x196.png?2
https://3.tesla.com/sites/all/themes/custom/tesla_theme/assets/img/icons/favicon-32x32.png?2
https://3.tesla.com/sites/all/themes/custom/tesla_theme/assets/img/icons/favicon-96x96.png?2
https://3.tesla.com/sv_SE/model3/design
...
For more examples of view, please see the documentation.
The backbone of this pipeline is spotify's luigi batch process management framework. Luigi uses the concept of a scheduler in order to manage task execution. Two types of scheduler are available, a local scheduler and a central scheduler. The local scheduler is useful for development and debugging while the central scheduler provides the following two benefits:
- Make sure two instances of the same task are not running simultaneously
- Provide visualization of everything that’s going on
While in the recon-pipeline shell, running install luigi-service will copy the luigid.service file provided in the
repo to its appropriate systemd location and start/enable the service. The result is that the central scheduler is up
and running easily.
The other option is to add --local-scheduler to your scan command from within the recon-pipeline shell.
If you think you've found a bug, please first read through the open Issues. If you're confident it's a new bug, go ahead and create a new GitHub issue. Be sure to include as much information as possible so we can reproduce the bug. At a minimum, please state the following:
recon-pipelineversion- Python version
- OS name and version
- How to reproduce the bug
- Include any traceback or error message associated with the bug
- @aringo for his help on the precursor to this tool
- @kernelsndrs for identifying a few bugs after initial launch
- @GreaterGoodest for identifying bugs and the project's first PR!
- The cmd2 team for a lot of inspiration for project layout and documentation