bugbounty-lab101: a workspace where the scope check is the entry point

The scope check is the entry point, not a feature

Most tooling in this space treats scope as paperwork you did once. This workspace makes it a command that gates everything else. The sequence is four steps. You create a scope tracker for a program, then edit the generated markdown file under the programs directory with the exact scope text from the program's policy. You then run the scope command against a target, and the documentation is blunt about what has to happen next: it must say scope OK before you proceed. Only then does the full pipeline run, which chains recon, vulnerability discovery, brute forcing, secret hunting, API testing and report generation in one invocation. The important property is stated plainly rather than implied: all active scanning commands in the hunter script verify scope against the program files before touching the target. So the failure mode of forgetting your scope is a refusal, not a legal problem, which is the correct way round for a tool that makes hundreds of requests per run. The setup that makes it work is short:

cd bugbounty-lab101
chmod +x bugbounty/*.sh auto-scanner/*.sh
# If the repository was cloned without submodules:
git submodule update --init --recursive

And the gate itself is one command that has to pass before the pipeline will run:

./bugbounty-hunter.sh scope target.com     # must say "Scope OK" before proceeding
./bugbounty-hunter.sh full target.com       # recon -> vuln -> brute -> secrets -> api -> report

Passive recon results are filtered before anything is probed

There is one detail in this workspace that most similar projects get wrong, and it is worth isolating. Passive intelligence gathering feels harmless, because looking something up sends nothing to the target, so it is tempting to let recon results flow straight into active scanning. This workspace does not. The optional Shodan certificate transparency integration uses a pinned vendor submodule when the recon tool is not installed locally, and the documentation states that its hostnames are scope filtered before any HTTP probing. That single sentence closes the most common loophole in a scope-enforced workflow, which is that an out-of-scope hostname discovered passively becomes an in-scope request the moment a scanner touches it. The recon command itself is described as including passive enrichment, so passive collection is part of the normal path rather than a separate mode, which means the filter has to live inside the recon output and it is documented as doing exactly that.

The 400 tool arsenal is explicitly not the starting line

The project is unusually honest about the relationship between its impressive tool count and its actual purpose. The 400-plus generic penetration testing arsenal and the local virtual machine lab are described as available as support, not as the entry point, and the README spends its opening section on the real workflow instead: choose a program, document scope, scan within boundaries, chain findings, and report in a format triagers accept quickly. The support tooling lives in a separate directory from the workflow tooling, which is the structural version of that same statement. It is reached through a script with its own commands for a full tool matrix, searching for a specific function, an express scan, and installing whatever is missing. The tool matrix by phase then arranges the arsenal into four stages, reconnaissance, scanning, enumeration and exploitation, with familiar tools placed in each, which is a reasonable way to think about ordering even if you never invoke the script.

Reports are dated by filename and start from a template

The reporting step is treated as part of the pipeline rather than as an afterthought, which matches the reality that a rejected report costs a researcher more time than a missed finding does. A report command generates a file under a reports directory named for the target with a date stamp in the filename, and the researcher completes it against the HackerOne template rather than writing prose from scratch. The documentation then points at a separate workflow document before submission, and that document covers three specific things: deduplication against Hacktivity, which is the public record of previously reported issues, report quality, and the post-submission steps. Deduplication is the one that catches people out, because a genuine, well-executed finding that has already been reported is worth nothing, and checking a public feed before you write the report is cheaper than checking after. The generated file is a shell to fill in, and the expectation is that the template's structure survives into the submission.

The AI engine is a separate repository you clone yourself

The offensive security engine is not in this repository, which is stated as plainly as the tool count is. It lives in a separate project, is listed in the ignore file, and is cloned into the lab directory as its own checkout, with a Node install step and an environment file you populate with your own model provider keys. Once started, its web interface is served on a local port, and the project then offers a mode that needs no keys at all: you connect a local coding agent through the settings screen and describe targets in plain English. The rest of the feature list is the usual offensive tooling inventory, a recon engine, an eight-operator exploit loop, a payload database with entries for the common injection classes, an MCP server for agent integration, and an evidence vault that keeps findings and retest state. For a reader deciding whether to engage with this at all, the separation is the point: the workflow repository is auditable shell, and the model-driven part is something you opt into separately.

The one benchmark number is a cell in a table

There is a single performance claim in the visible documentation, and it deserves the scrutiny any number in a feature table deserves. The recon engine row lists port scanning, DNS and HTTP fingerprinting alongside a pass rate at one attempt on a benchmark suite. Nothing in the documentation explains the benchmark, the sample size, the scoring rule or how to reproduce it, and the two sibling repositories are separate projects whose internal configuration you would have to read to answer any of that. So the honest reading is that the number belongs to the other project and was carried into a feature table here. The rest of the inventory is more falsifiable: a payload count, an operator count in the kill chain, a named port for the local interface, and a set of vulnerability classes covered. Those you can check by looking. When a project is honest about its own scope discipline, it is reasonable to apply the same standard to its marketing-adjacent numbers.

Submodules decide whether the workspace works at all

A fresh clone is not a working install, and the quick start says so in three commands. You make the shell scripts executable in both the workflow and scanner directories, and then, if the repository was cloned without submodules, you initialise them recursively. The reason this matters is visible in the layout: there is a vendor directory, and one of the documented behaviours depends on a pinned submodule standing in for a tool that may not be installed on your machine. Submodule content is not in the repository you cloned, it is a reference to another commit somewhere else, which means a clone performed with submodule initialisation disabled produces a workspace that is silently incomplete rather than obviously broken. The tests directory and the contributing guide suggest the project expects that kind of care, and the changelog is present at the top level. The practice lab lives in its own directory alongside the workflow, which is the intended answer for anyone who wants to rehearse the process without pointing any of it at a real program.

Scope documents live in version control, so drift is reviewable

The structural choice that makes the rest work is that scope definitions are ordinary files in the repository rather than local state. A program directory holds one markdown file per program, and the hunter script reads those files to decide what it is allowed to touch. Because they are tracked, a change to what you believe is in scope shows up in a diff, can be reviewed, and can be attributed. That is a meaningful improvement over a spreadsheet of targets, and it is the reason the scope check can be relied on: the file the script consults is the same file a colleague would read. Around it sit a code of conduct, a contributing guide, a changelog, documentation including the HackerOne workflow document, the scanner directory, the workflow scripts, a start script for the separate engine, and a tests directory. The project is MIT licensed, the primary language is shell, and the release record is a single version tag.

Editorial conclusion

The design decision here is worth borrowing even if you never run the scripts: scope lives in a file you commit, and the tooling refuses to proceed until that file agrees with the target. Three things to know. The 400 tool arsenal is explicitly framed as support rather than an entry point, so the useful reading of this repository is the workflow, not the tool list. The AI component lives in a separate gitignored repository that you clone in yourself, which means a fresh clone is not a working install until you do that and initialise submodules. And the one benchmark number in the documentation is a figure in a feature table rather than something you can reproduce. The last push was on 2026-08-24 and there is a single tag, v1.0.5, from the same day.

Frequently asked questions

Official sources

1. DevCop95/bugbounty-lab101 on GitHub
2. Issues
3. License: MIT
4. README
5. Releases