# bbscope for Multi-Platform Bug Bounty Scope Collection

> bbscope is a Go command-line tool that collects public and authorized program scope from HackerOne, Bugcrowd, Intigriti, YesWeHack, and Immunefi. It is suited to bug bounty hunters who need repeated collection, PostgreSQL-backed history, and machine-readable output, but it adds platform credentials, a database, and normalization choices to the workflow.

**sw33tLie/bbscope** — Scope aggregation tool for HackerOne, Bugcrowd, Intigriti, YesWeHack, and Immunefi!

- Repository: https://github.com/sw33tLie/bbscope
- Website: https://bbscope.com
- Stars: 1,448 · Forks: 212
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/sw33tlie-bbscope

## What bbscope Solves for Multi-Program Researchers

bbscope addresses a specific part of bug bounty research: collecting scope data from several bug bounty platforms and making the results usable outside each platform's web interface. The README identifies HackerOne, Bugcrowd, Intigriti, YesWeHack, and Immunefi as supported sources. Its intended user is a bug bounty hunter who moves between programs and needs one command structure rather than separate manual workflows.

The tool can print targets directly, save them to PostgreSQL, query normalized categories, and track additions and removals over time. Those capabilities matter when a hunter wants to compare a changing scope inventory, collect only private programs, restrict results to programs offering monetary rewards, or export records as JSON or CSV. The README also describes bulk HackerOne report downloads as Markdown files with filtering by program, state, or severity.

bbscope does not replace platform authorization, report submission, or vulnerability validation. It is a data collection and management layer. Its value is strongest for repetitive scope aggregation, not for a one-time visit to a single program's page. The project homepage, bbscope.com, is described as an hourly-updated public scope list with statistics, but that website is separate from the command-line tool's local workflow.

## How bbscope Poll and Query Data

The v2 command structure separates collection from database operations. Polling commands live under `bbscope poll`, with platform subcommands such as `bbscope poll h1` and `bbscope poll bc`. A bare `bbscope poll` polls all configured platforms, while `bbscope poll immunefi` selects one platform. Database retrieval is handled separately by `db`.

The polling path can print records directly or write them to PostgreSQL when `--db` is enabled. The README states that database tables are created automatically on the first run. Once records are stored, `db get` can fetch targets by category, including wildcards and CIDRs, and the database feature is required for changes monitoring.

Output can be plain text, JSON, or CSV. The default text output flags are documented as `t` for the target and `u` for the program URL, with `d` for description and `c` for category available as additional output fields. The `--category` flag restricts collected scope categories, with examples including `url`, `cidr`, and `mobile`; its documented default is `all`.

AI scope normalization is opt-in through `--ai`. According to the README, it uses an LLM to clean messy scope strings in bulk before writing to the database. This is a data transformation step, not automatic permission validation. A normalized string can still represent an in-scope asset incorrectly if the underlying platform record or model output is wrong, so hunters should inspect results before relying on them for testing decisions.

## Installing bbscope and Running a First Poll

The README instructs users to install a recent version of Go and then install the v2 module. The module path is `github.com/sw33tLie/bbscope/v2`, so a following installation may otherwise use an obsolete command path or miss the v2 subcommand structure.

Install the command from the repository's documented module path:

```bash
go install github.com/sw33tLie/bbscope/v2@latest
```

The command should be available through the Go installation's configured `GOBIN` or `GOPATH/bin` directory. The README does not specify a universal binary path, so verify the environment settings for your Go installation rather than assuming `/usr/local/bin`.

For a first real use without credentials, poll Immunefi. The README states that this platform requires no authentication:

```bash
bbscope poll immunefi
```

This invocation fetches Immunefi scope using the default output settings. The documented default output is `tu`, meaning target and program URL, and the default category is `all`. The command may therefore print more than just an asset name, depending on the platform records returned.

After the first run, bbscope creates `~/.bbscope.yaml`. Credentials for private programs and the PostgreSQL URL are entered there. Command-line flags can override configuration values for polling. Authentication flags are platform-specific, so do not assume that a HackerOne token can authenticate Bugcrowd or Intigriti.

## Configuring PostgreSQL and AI Normalization

PostgreSQL is optional for basic polling, but it is required for persistent queries and changes monitoring. The configuration file uses `db_url` with a standard PostgreSQL connection string. A local Docker example is provided by the README:

```bash
docker run --name bbscope-db \
  -e POSTGRES_USER=bbscope \
  -e POSTGRES_PASSWORD=<YOUR_SECURE_PASSWORD> \
  -e POSTGRES_DB=bbscope \
  -p 5432:5432 \
  -d postgres:alpine
```

The placeholder is intentional. The README instructs users to replace it with a strong, unique password, then place the resulting connection URL in the configuration file:

```yaml
db_url: "postgres://bbscope:<YOUR_SECURE_PASSWORD>@localhost:5432/bbscope?sslmode=disable"
```

A containerized bbscope needs additional care. The Docker example mounts `~/.bbscope.yaml` into `/root/.bbscope.yaml` so configuration survives container removal:

```bash
docker run --rm \
  -v ~/.bbscope.yaml:/root/.bbscope.yaml \
  ghcr.io/sw33tlie/bbscope:latest poll --db -b -p
```

The command enables database storage, monetary-reward filtering with `-b`, and private-program filtering with `-p`. The README notes that the container connects using `db_url`; a database on the Docker host may require `host.docker.internal` on macOS or Windows, or an address reachable from the container network.

AI normalization is separate from database setup. It requires an API key, and the documented configuration includes provider, model, batch size, and concurrency settings. The README does not state the data retention policy of the configured provider, so users should not enable this option for sensitive scope data without checking that policy themselves.

## Docker Images, Platform Credentials, and Deployment Boundaries

The repository includes a multi-stage Dockerfile that builds a static Go binary and places it in an Alpine-based runtime image. The image is published on GHCR and the README documents pulling it with `ghcr.io/sw33tlie/bbscope:latest`. Its entry point is the `bbscope` executable, so commands and flags follow the container command shape:

```bash
docker pull ghcr.io/sw33tlie/bbscope:latest
```

```bash
docker run --rm ghcr.io/sw33tlie/bbscope:latest [command] [flags]
```

The repository describes the image as being built and published on every push. That is a deployment detail, not a claim that the project has a formal release process. The repository currently has no GitHub releases, and the last push was on 2026-09-02. The image is therefore convenient for a current snapshot, while organizations that require pinned, auditable releases must decide how they will pin and track the image themselves.

Credentials are the main operational boundary. HackerOne uses a username and API token. Bugcrowd and YesWeHack can use login credentials with an OTP secret, while also accepting live session or bearer token alternatives in their respective polling commands. Intigriti uses a personal access token. Immunefi is the documented unauthenticated source. These are different authentication models, and storing them in a shared YAML file creates a credential-management responsibility outside bbscope.

The configuration example permits `OPENAI_API_KEY` as an alternative to putting the key in the YAML file. The README does not document encryption, secret rotation, or access-control behavior for `~/.bbscope.yaml`, so those controls must be handled by the host environment.

## Limits of Scope Collection and Normalization

bbscope's central limitation is that aggregation cannot guarantee that every program has identical scope semantics across platforms. URL categories may contain wildcards, exclusions, ports, paths, or descriptions that do not fit one clean string. AI normalization is explicitly opt-in and dependent on an external model, which introduces cost, latency, and a dependency on provider behavior. It also creates a review burden because normalized output should not be treated as an authoritative scope decision.

Changes monitoring is unavailable without the database. A user who only prints polling results cannot rely on bbscope's documented history mechanism. Conversely, storing records in PostgreSQL adds schema, backup, connection, and access-control work. Automatic table creation simplifies the first setup, but it does not remove database operations from the deployment plan.

Another boundary is authentication scope. Public Immunefi polling is straightforward, while private programs require credentials with different token and session formats. A polling command that succeeds for one platform does not demonstrate access to private programs on another. The tool also does not document a universal retry policy, rate-limit policy, or guaranteed completeness guarantee across providers in the README. Those behaviors should be checked against platform API terms and observed output before scheduling frequent collection.

Compared with manually using each platform's interface, bbscope adds persistence, filtering, and export but also adds configuration and operational components. Compared with writing platform-specific scripts, it supplies one command model and one database path, but it reduces direct control over each provider's native response and authorization details. It is the better fit only when that shared abstraction is worth more than platform-specific control.

## License, Maintenance, and Upgrade Considerations

The repository declares the Apache-2.0 license. That identifies the project's licensing terms and provides the starting point for reviewing use, modification, and redistribution conditions. It is not legal advice, and downstream users still need to review the license text and any separate platform terms that govern bug bounty programs, credentials, reports, and automated collection.

The repository is not archived, and its last push was on 2026-09-02. There are no GitHub releases, so version pinning through GitHub release artifacts is not available from the documented release history. The README tells Go users to install `@latest`, which is convenient for obtaining the latest module but makes upgrade review dependent on the Go module workflow and the project's evolving v2 command structure. The Docker documentation likewise uses `latest` and suggests `--pull=always` for users who want the newest image.

The breaking change from `bbscope h1` to `bbscope poll h1` is important during upgrades. Existing scripts, shell history, documentation, and automation may need command changes even if the module major version remains `v2`. The repository layout includes `cmd/`, `internal/`, `pkg/`, and `docs/`, but the README does not provide a compatibility matrix for every subcommand or database migration. Users who depend on scheduled collection should verify command syntax, configuration format, database behavior, and image behavior during each upgrade rather than relying on `latest` without review.

## Conclusion

Adopt bbscope if a bug bounty hunter repeatedly collects scope across several platforms and can account for PostgreSQL, platform authentication, and potentially paid LLM normalization. Do not adopt it as a replacement for each platform's own authorization or reporting system. Before deployment, verify the Go version requirement, credential storage at `~/.bbscope.yaml`, PostgreSQL reachability, Docker network routing, and whether the target-category filters match the programs being polled. For organizations that only need occasional manual lookup, the individual platform interfaces remain the simpler alternative; for adoption, the first concrete checkpoint is a successful `bbscope poll immunefi` without committing private credentials to the command line.

## FAQ

### How do I install bbscope?

The README says to install a recent Go version, then run `go install github.com/sw33tLie/bbscope/v2@latest`. A GHCR image is also documented with `docker pull ghcr.io/sw33tlie/bbscope:latest`.

### Does bbscope need credentials for every supported platform?

No. The README states that `bbscope poll immunefi` requires no authentication. Private-program polling on HackerOne, Bugcrowd, Intigriti, and YesWeHack uses platform-specific credentials or tokens.

### Can bbscope track changes to program scope?

Yes, but the documented changes-monitoring feature requires PostgreSQL. Without the database, polling can still print fetched scope, but the history and `db get` workflows are unavailable.

### What does the `--ai` flag do?

The `--ai` flag enables opt-in bulk scope normalization through an LLM before database writes. It requires an API key and adds an external provider dependency to the collection workflow.

## Sources

- [Issues](https://github.com/sw33tLie/bbscope/issues)
- [License: Apache-2.0](https://github.com/sw33tLie/bbscope/blob/main/LICENSE)
- [Project website](https://bbscope.com)
- [README](https://github.com/sw33tLie/bbscope/blob/main/README.md)
- [sw33tLie/bbscope on GitHub](https://github.com/sw33tLie/bbscope)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sw33tlie-bbscope