Hacker-Scoper: A Complete Guide to Bug Bounty Scope Filtering
Hacker-Scoper: A Complete Guide to Bug Bounty Scope Filtering
Hacker-Scoper is a command-line tool designed to filter a mixed list of targets (URLs, IPs, CIDRs, etc.) according to a bug bounty program's scope. It solves a common problem in bug bounty workflows: you have a large list of assets from reconnaissance, but only a subset is in scope. Manually filtering is error-prone and time-consuming. Hacker-Scoper automates this by accepting a scope definition—either manually provided or automatically detected from the program's name—and outputting only the targets that match.
It supports IP addresses, URLs, wildcards (*.example.com), CIDR ranges, Nmap octet ranges (e.g., 192.168.1.1-254), and even full regular expressions. This makes it flexible enough for any bug bounty program, from simple domain scopes to complex regex-based inclusions and exclusions.
⚠️ Legal and ethical notice: Hacker-Scoper is intended for authorized bug bounty programs and security testing. Always ensure you have permission to test the targets you are filtering. Respect program scope and rules. Unauthorized testing is illegal and unethical.
Table of Contents
- Why Hacker-Scoper Exists
- Installation
- Basic Usage
- Scope File Format
- Automatic Scope Detection
- Filtering Logic & Examples
- Command Reference
- Real-World Workflow
- Best Practices
- Final Tips
1. Why Hacker-Scoper Exists
Bug bounty programs often have intricate scopes. A program might include:
*.example.combut excludedev.example.com- A set of IP ranges like
192.168.1.0/24and10.0.0.1-10.0.0.50 - Specific URLs like
https://api.example.com/v1/* - Regex patterns for paths or subdomains
Manually cross-referencing a reconnaissance output (thousands of subdomains, IPs, URLs) against such a scope is impractical. Hacker-Scoper automates the process:
- Accepts mixed input – URLs, IPs, CIDRs, hostnames.
- Parses complex scopes – Wildcards, CIDR, octet ranges, regex.
- Filters in-scope and out-of-scope – Outputs only what you can test.
- Auto-detects scope – Pulls scope directly from HackerOne or Bugcrowd using the program name.
This reduces false positives and ensures you stay within program rules, avoiding wasted effort and potential legal issues.
2. Installation
Hacker-Scoper is written in Go. You can install it via go install or download a precompiled binary from the releases page.
Using Go
go install github.com/Ice3man543/hacker-scoper@latest
Ensure $GOPATH/bin is in your PATH.
Precompiled Binaries
Download the latest release for your OS from the GitHub releases page. Extract and place the binary in your PATH.
Verify Installation
hacker-scoper --help
3. Basic Usage
The typical workflow:
- Prepare a file containing your targets (one per line).
- Provide a scope file (or use automatic detection).
- Run Hacker-Scoper to filter.
Filter with a Manual Scope File
hacker-scoper -t targets.txt -s scope.txt -o filtered.txt
-t– Input targets file (URLs, IPs, etc.)-s– Scope file (defines in-scope and out-of-scope rules)-o– Output file for in-scope targets
Filter with Automatic Scope Detection
hacker-scoper -t targets.txt -p "Example Corp" -o filtered.txt
-p– Program name (e.g., "Example Corp"). Hacker-Scoper queries HackerOne/Bugcrowd for the scope.
Read from Stdin
cat targets.txt | hacker-scoper -s scope.txt -o filtered.txt
4. Scope File Format
The scope file is a plain text file where each line defines a rule. Lines starting with ! denote exclusions (out-of-scope). Supported formats:
| Format | Example | Description |
|---|---|---|
| Domain | example.com | Exact domain |
| Wildcard | *.example.com | Any subdomain of example.com |
| URL | https://api.example.com | Exact URL |
| URL wildcard | https://api.example.com/* | Any path under the URL |
| IP | 192.168.1.1 | Single IP |
| CIDR | 192.168.1.0/24 | IP range in CIDR notation |
| Nmap octet range | 192.168.1.1-254 | Range of last octet |
| Regex | regex:^api\..*\.com$ | Full regular expression (prefix with regex:) |
Example scope file:
# In-scope*.example.com192.168.1.0/2410.0.0.1-10.0.0.50https://api.example.com/v1/*regex:^staging\..*\.example\.com$# Out-of-scope!dev.example.com!192.168.1.100!https://api.example.com/v1/internal/*
In this example, *.example.com is in scope, but dev.example.com is excluded. Similarly, the IP range is included but 192.168.1.100 is excluded.
5. Automatic Scope Detection
Hacker-Scoper can automatically fetch scope from bug bounty platforms if you provide the program name. This is incredibly convenient—no need to manually copy scope rules.
Supported Platforms
- HackerOne – Uses the HackerOne API (requires an API token if the program is private; public programs may work without).
- Bugcrowd – Uses the Bugcrowd API (may require credentials).
Usage
hacker-scoper -t targets.txt -p "Example Corp" -o filtered.txt
You may need to set environment variables for API tokens:
export HACKERONE_API_TOKEN="your_token"export BUGCROWD_API_TOKEN="your_token"
Check the tool's documentation for the exact environment variable names and authentication requirements.
How It Works
Hacker-Scoper queries the platform's API for the program's scope, parses the in-scope and out-of-scope assets, and then applies the same filtering logic as a manual scope file. This ensures you always have the latest scope.
6. Filtering Logic & Examples
Hacker-Scoper compares each target against every rule. A target is considered in scope if it matches at least one inclusion rule and does not match any exclusion rule.
Example 1: Subdomain Filtering
Targets:
api.example.comdev.example.comstaging.example.comevil.com
Scope:
*.example.com!dev.example.com
Result:
api.example.comstaging.example.com
Example 2: IP Range Filtering
Targets:
192.168.1.1192.168.1.100192.168.1.20010.0.0.5
Scope:
192.168.1.1-192.168.1.150!192.168.1.100
Result:
192.168.1.1192.168.1.200? -> 200 is not in range 1-150, so excluded.10.0.0.5 -> not in scope.
Wait, 192.168.1.200 is outside the range, so it's excluded. 192.168.1.100 is explicitly excluded. So the output is only 192.168.1.1.
Example 3: URL Path Filtering
Targets:
https://api.example.com/v1/usershttps://api.example.com/v1/internal/confighttps://api.example.com/v2/users
Scope:
https://api.example.com/v1/*!https://api.example.com/v1/internal/*
Result:
https://api.example.com/v1/users
Example 4: Regex Scope
Targets:
staging.example.comprod.example.comtest.example.com
Scope:
regex:^staging\..*\.com$
Result:
staging.example.com
7. Command Reference
| Flag | Description |
|---|---|
-t, --targets | File containing targets (one per line) |
-s, --scope | File containing scope rules |
-p, --program | Program name for automatic scope detection |
-o, --output | Output file for in-scope targets |
--out-of-scope | Output file for out-of-scope targets |
--silent | Suppress banner and extra output |
--version | Show version |
--help | Show help |
8. Real-World Workflow
A typical bug bounty reconnaissance pipeline:
- Subdomain enumeration – Use Subfinder, Amass, etc.
- Resolve and probe – Use httpx to find live hosts.
- Filter with Hacker-Scoper – Ensure only in-scope assets remain.
- Vulnerability scanning – Run Nuclei, ffuf, etc. on the filtered list.
Example:
# 1. Enumerate subdomainssubfinder -d example.com -o subdomains.txt# 2. Probe for live hostscat subdomains.txt | httpx -silent -o live.txt# 3. Filter with Hacker-Scoper (manual scope)hacker-scoper -t live.txt -s scope.txt -o in_scope.txt# 4. Scan in-scope targetscat in_scope.txt | nuclei -t cves/ -o findings.txt
If the program is on HackerOne, you can skip the manual scope file:
hacker-scoper -t live.txt -p "Example Corp" -o in_scope.txt
9. Best Practices
- Always verify scope manually – Automatic detection is convenient but may not capture every nuance. Cross-check with the program's policy.
- Use exclusions wisely – Excluding out-of-scope assets prevents accidental testing and legal issues.
- Keep scope files updated – Programs change scope; re-run Hacker-Scoper regularly.
- Combine with other tools – Use Hacker-Scoper early in the pipeline to avoid wasting resources on out-of-scope targets.
- Log both in-scope and out-of-scope – Use
--out-of-scopeto keep a record of what was excluded. - Respect rate limits – When using automatic detection, be mindful of API rate limits.
10. Final Tips
- Test with a small list first – Verify your scope file works as expected before running on thousands of targets.
- Use regex sparingly – Regex is powerful but can be slow and error-prone. Prefer wildcards and CIDR when possible.
- Check the GitHub repository – The tool is actively maintained; new features and bug fixes are added regularly.
- Integrate into scripts – Hacker-Scoper is designed for automation. Use it in your recon pipelines.
- Stay legal and ethical – Only test assets that are explicitly in scope. When in doubt, leave it out.
Official Resources:
- GitHub: github.com/Ice3man543/hacker-scoper
- Releases: github.com/Ice3man543/hacker-scoper/releases
- HackerOne API: api.hackerone.com
- Bugcrowd API: docs.bugcrowd.com/api
Remember: Bug bounty programs have rules. Hacker-Scoper helps you follow them by filtering out-of-scope targets. Always obtain proper authorization and respect program boundaries.
Author
Discussion · 0
No comments yet — start the discussion.
Sign in to join the discussion.