shulkwisec
05 Resources/Resources//4 min read

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

BugBounty.SA API

bugbountysa

programs.json

scopes/scope_{id}.json

scopes/domains.txt

next tool

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.txt can 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.