
bugbountysa CLI Tool
The BugBounty.SA program data sits behind a web console. bugbountysa pulls it over the API and writes it to a directory: the program list, one file per scope, and a flat list of domains beside them.
The domain file is the part I care about. A scope you can cat is a scope you can feed to the next tool. A scope you have to scroll is a screenshot of a scope.
The author’s one-line description calls it the first CLI tool to manage BugBounty.SA programs. Whether it was first matters less than what it leaves on disk, which is the thing you can audit.
Install
pip install bugbountysa
Or from source, which is what you want if you intend to read the parser before you trust it with a token:
git clone https://github.com/ShulkwiSEC/bugbountysa.git
cd bugbountysa
pip install -e .
The project ships under the MIT license.
Authenticate
The tool reads its credentials from the environment, so the repository carries an example file to copy:
cp .env.example .env
ACCOUNT_TOKEN is the required value, and it is your BugBounty.SA API token. The rest of the configuration names where the tool talks and where it writes:
| Variable | Purpose |
|---|---|
ACCOUNT_TOKEN |
BugBounty.SA API token |
API_ENDPOINT |
The API endpoint the tool queries |
HEADERS |
Auth headers sent with the requests |
OUTPUT_DIR |
Default directory for saved data |
A .env inside a git working tree is a credential waiting to be committed. Check git status before the first --save.
Read one program
Start with a single program by name, so the first run costs you one request instead of the whole list:
bugbountysa --program "Program Name"
The console prints an analysis block for it. The tool draws the block with box characters; the fields are what matter, so the borders are stripped here:
Program : Example Program
Status : ACTIVE
Type : PUBLIC
Platform : Web
Start Date : 2025-02-25
End Date : 2025-05-12 (26 days remaining)
Duration : 76 days
Policy Size : 2286 chars
Out of Scope : 1766 chars
Then the bounty table, in SAR:
Critical 5238 to 7000
High 2729 to 5082
Medium 916 to 2635
Low 500 to 885
Two of those fields are not what they look like. Policy Size and Out of Scope are character counts, not rule counts. The tool is telling you how much text it stored, not how many hosts are excluded.
Save the tree
--save writes the data out. --output-dir picks where, defaulting to output/:
bugbountysa --save --output-dir output
output/
├── programs.json
└── program_name/
└── scopes/
├── scope_{id}.json
└── domains.txt
programs.json is the index. The per-program directory is the working set. Each scope_{id}.json holds one scope as the API returned it, and domains.txt is the same scope flattened to one host per line.
Ask it questions with flags
The flags cover the two things you do with bounty data: narrow the set and change the shape of the output.
| Option | What it does |
|---|---|
--save |
Write the data to the output directory |
--output-dir DIR |
Choose that directory (default output) |
--output-file FILE |
Write the output to one file |
--format {json,txt} |
Pick the output format |
--domains |
Print domains only |
--all-domains |
Export every domain as one list |
--no-analysis |
Skip the analysis block |
-v, --verbose |
More output |
--quiet |
Nothing but errors |
--program NAME |
Process one program by name |
--active-only |
Skip programs that are not active |
The verbose flag is the one to run when a program you expected is missing from the output. It tells you which requests happened, and a missing program is almost always a filter or a name mismatch rather than an API failure.
Turn the scope into a work list
The normal end of a run is one file with every in-scope domain:
bugbountysa --all-domains --output-file domains.txt
That is the handoff. From there the file is a plain host list, and the next step is whatever your resolver or scanner takes on stdin. For a single program, --domains prints the same list without writing anything, and --format json gives you the structured version when you want to parse instead of pipe.
What the snapshot cannot answer
The console numbers decay. 26 days remaining was true on the day of the run and wrong the next morning, which is why the JSON is the artifact I keep and the terminal output is not.
The saved scope is a copy, not a subscription. Nothing in the tool re-checks a program after it is written, so a scope saved in February describes February. If a program has been running for months, re-run it before you start work on it, and keep the date in the directory name when you archive a snapshot.
The policy fields are character counts, so the out-of-scope rules still have to be read by a person. A tool that hands you 1766 characters of exclusion text has handed you reading, not a filter.
What to take from this one
The transferable move is not this tool. It is the shape of the workflow it fits into, which works for any platform that has a web console and a token:
- One request first. Name a single program, read the analysis, and confirm the parser agrees with the page before you pull the whole account. Failures are cheaper to read one at a time.
- Keep the JSON, drop the rendering. The console output is a view built for a human, and parts of it expire. The raw scope files are the evidence, and they are what a second person can diff.
- Treat the host list as the deliverable. A scope that ends in
domains.txtcan be counted, sorted, deduplicated and fed forward. Anything that only renders on screen stops at the screen. - Count characters, not conclusions. When a tool reports the size of a policy rather than its rules, it is telling you that the interpretation is still yours.
- Date the snapshot. A saved scope without a run date is a claim about the present that nobody can check.
https://shulkwisec.github.io/05-Resources/bugbountysa-cli-tool-post/
Printed 2026-11-15