leebaird/discover: Bash and Python scripts for penetration testing recon, scanning and payload generation

What leebaird/discover is for

Discover is a set of custom Bash and Python scripts that automate penetration testing tasks: recon, scanning, enumeration and malicious payload creation using Metasploit. The README states it is for use with Ubuntu, with limited support for Kali Linux. That platform note is the first thing to take seriously. This is not a cross-platform toolkit, and the helper install script behaves differently depending on the host it detects.

The audience is an operator running an engagement end to end. The main menu is organised into RECON, SCANNING, WEB and MISC blocks, and the domain recon flow expects you to move through Passive, then Import, then Active, then Export. The workflow assumes you keep a per-domain report directory and that you care about an audit trail: on first run Discover asks for your first name, saves it to ~/.discover/operator-name, and writes that name on every engagement audit log line.

That audit-log detail tells you who the project is really aimed at. It is built for small teams where more than one operator touches the same engagement and where the report, not the terminal history, is the deliverable.

How the engagement workflow actually runs

The mechanism is a shell menu in front of a directory of scripts, with an HTML report as the shared state between stages. Passive recon uses Amass, ARIN, DNSRecon, dnstwist, Metasploit, subfinder, sublist3r, Shodan CTL, theHarvester, Whois and multiple websites, and builds an HTML report at $HOME/data/<domain>/. From there, Import merges external data into the current report: operator scans, names from tools/names-manual.tsv, names with titles and emails, or subdomains.

Active recon is where the data flow gets specific. It reads public hostnames from tools/subdomains, skips RFC1918 addresses, and probes with httpx into tools/httpx.jsonl. A host counts as alive on status 200 to 399, 401, 403 or 405. Alive URLs then go through whatweb and gowitness, and recon/active-tech.py merges the results. Re-running Active replaces those artifacts and rebuilds the Active and Subdomains pages.

The report server matters for the interactive parts. Host-scan expand controls appear only in operator mode, meaning the report was opened via Open report or Active at http://127.0.0.1:17322/. Opening the same file manually with a file:// URL never shows those chevrons. If you skip the report server, you lose the interactive layer even though the underlying data exists on disk.

Installing Discover and running a first domain recon

The README gives a short setup path: clone into your home directory and run the menu script. There is no package, no installer binary and no release artifact. You get the repository and run it from a shell.

cd ~
git clone https://github.com/leebaird/discover
cd discover/
./discover.sh

On that first run Discover asks for your first name, maximum 10 letters, and saves it to ~/.discover/operator-name. That value is written on every engagement audit log line. To change it later, edit or delete that file and restart Discover. After the menu appears, the README points to option 18 Update, which updates the operating system and installs dependencies. Some options require root credentials to run, and the README notes that Passive and Active cannot be run as root.

API keys are optional but change how much data you get back. The repository ships resource/api-keys.example, and .env.example describes it as a legacy template that is still loaded as a fallback. The recommended path is a file under your home directory with restrictive permissions.

mkdir -p ~/.discover
cp resource/api-keys.example ~/.discover/api-keys
chmod 600 ~/.discover/api-keys
# edit ~/.discover/api-keys

Shell exports always win over file values, so an exported NVD_API_KEY or SHODAN_API_KEY overrides the file. For theHarvester results specifically, the README says to acquire free API keys and place them at $HOME/.theHarvester/api-keys.yaml.

For a first real use, pick option 1 Domain, then Passive. The expected result is an HTML report under $HOME/data/<domain>/. Open it from the menu rather than from the filesystem if you want the interactive features later.

The optional shell helpers and their install trap

The config directory contains a second, separate install step that has nothing to do with the pentest scripts. Running config/install.sh copies zshrc, tmux.conf and vimrc into your home directory and gives you short commands: n for a network summary, s to cd into the repo and show a short git status, m and ms to start and stop the Metasploit database and console, web and web2 for HTTP servers on port 80 and 8000, and update for an apt upgrade chain.

The host detection is the part to watch. On Ubuntu and other non-Kali hosts, including macOS, install.sh copies zshrc to ~/.bash_aliases and sources it. On Kali, detected via /etc/os-release, it appends zshrc to ~/.zshrc instead. That means re-running install.sh on Ubuntu overwrites ~/.bash_aliases with the repo copy, while re-running it on Kali appends again and can duplicate the block. If you are on Kali, edit ~/.zshrc or install only once.

There is a second shell-level gotcha. On macOS and Kali the default zsh does not load ~/.bash_aliases unless you source it from ~/.zshrc, so the helpers silently do nothing until you wire that up. One design choice here is genuinely good: network identity such as IPs, DNS and MAC is computed when you run n, web or upload, not at shell startup, so new shells stay fast and the values stay current after a VPN or wifi change.

Where Discover gets in the way

The clearest limitation is documented rather than hidden: Discover is for Ubuntu, with limited support for Kali Linux. The helper installer branches on the host, and the Kali path has the duplicate-append behaviour described above. If your team standardises on another distribution, the README offers nothing.

The second limitation is the absence of packaging. Installation is a git clone, and updates arrive through the repository plus menu option 18 Update. There are no retrieved releases, so you cannot pin a version number and audit a changelog. For a tool that runs Metasploit payload generation and host scanning, that is a real operational constraint: you are tracking a moving branch, and the audit log records your operator name but not which revision produced a given artifact.

Third, the interface is a menu, not a scripting API. The README does document CLI backends for the import scripts, which helps for names and subdomains, but the recon and scanning stages are described as menu flows. If you want Discover's logic inside a CI pipeline or an existing orchestration layer, you will be reverse-engineering the scripts. The README also does not document rollback for a completed engagement, so treating a report directory as disposable is not something the documentation supports.

Finally, the interactive features are conditional. Host-scan expand controls require operator mode at http://127.0.0.1:17322/. A manual file:// open shows none of them, which is an easy way to conclude the tool is broken when it is only being opened the wrong way.

How Discover differs from a general-purpose recon framework

The obvious comparison is a modular reconnaissance framework such as recon-ng, which is built around a module and workspace model: you install modules, configure keys, and run them individually against a workspace database. Discover inverts that. It is an opinionated sequence with a fixed menu, where the output is an HTML report rather than a queryable database, and where the stages are meant to run in order: Passive, Import, Active, Export.

The practical difference shows up in two places. First, Discover bundles Metasploit payload generation and listener startup in the same menu as recon, so a single session can move from hostnames to a payload without leaving the tool. A framework focused on reconnaissance does not do that. Second, Discover's collaboration model is file-based: Import merges another operator's unpacked report, including their host scans, screenshots, Active data and audit lines, into the current engagement. That is a deliberate choice for small teams sharing a report directory, and it is a poor fit if you want a central database or concurrent writers.

If your work is mostly passive OSINT against a domain and you want a browsable report you can hand to a client, Discover's shape fits. If your work is a long-running program with many targets and you need to query historical results, the report-directory model will feel like a filing cabinet.

Maintenance, upgrade cost and licence

The repository is not archived, and the last push was on 2026-09-19, which is recent. That is the only maintenance signal available here: there are no retrieved releases, so there is no version history to read and no deprecation notices to check. Treat the branch as the source of truth and read the commit log yourself before upgrading a production host.

Upgrade cost is dominated by dependencies rather than by Discover's own code. Menu option 18 Update runs an operating system update and installs dependencies, and the optional helper installs an apt upgrade chain behind the update command. Passive recon depends on a long list of external tools, and each of those has its own release cadence and its own breakage. A Python script such as recon/active-tech.py merging whatweb and gowitness output is only as stable as the JSON those tools emit.

On licensing, the repository is MIT, and the LICENSE.txt file is at the root alongside README.md. MIT is permissive, but the dependencies Discover invokes carry their own licences, and several of them are separate projects with separate terms. Nothing here is legal advice; if you are shipping Discover inside a commercial service, check the licence of each bundled or invoked tool rather than assuming the MIT badge covers the whole chain. The .env.example file also reminds you that API keys live in ~/.discover/api-keys with permissions set to 600, which is a reasonable default for credentials that grant access to third-party services.

Editorial conclusion

Discover suits operators who run repeatable, report-driven engagements on Ubuntu and want recon, scanning and payload generation behind one menu. It is the wrong tool if you need a packaged installer, Windows or macOS support as a target platform, or per-command documentation, since the README documents menu flows rather than every script. Before adopting it, verify that option 18 Update completes on your host and that your first Passive run writes an HTML report under $HOME/data/<domain>/.

Frequently asked questions

Official sources

1. Issues
2. leebaird/discover on GitHub
3. License: MIT
4. README