BreachScope guide

BreachScope docs

Configure the CLI, enforce policy in CI, export release evidence, connect the dashboard, and route findings with credentials your team owns.

Start

Installation

Requires Node.js 18 or higher. Docker is required only for sandbox attack runs.

bash

npm install -g breachscope
pnpm add -g breachscope
bun add -g breachscope
npx breachscope scan

Quick Start

bash

cd my-project
breachscope login
breachscope scan
breachscope scan --mode deep --breach --bug --ci

The CLI pushes results to the dashboard after login. Local scans still work without a dashboard connection.

Configuration

yaml

thresholds:
  failOn: high

policy:
  failOn: high
  maxFindings:
    critical: 0
  blockedPackages:
    - event-stream

output:
  format: console
  verbose: false

Dashboard settings can store customer-supplied OpenAI and Firecrawl keys when a team chooses to enable those workflows. API keys require `secrets:read` before the CLI can retrieve encrypted secret values.

Data and Keys

BreachScope provides the scanning, routing, and evidence layer. Teams bring their own provider accounts, tokens, and credentials for GitHub, Slack, Jira, PagerDuty, Linear, OpenAI, Firecrawl, and other connected systems.

Storedaccount data

users, projects, scan records, findings, audit logs, settings, and integration metadata

Optionalprovider keys

encrypted only when a user saves them for dashboard-connected workflows

Never suppliedthird-party accounts

BreachScope does not provide Slack, GitHub, OpenAI, Firecrawl, or incident-management accounts

Private routesdashboard/API

robots.txt blocks authenticated and operational routes from crawlers

Stored	account data	users, projects, scan records, findings, audit logs, settings, and integration metadata
Optional	provider keys	encrypted only when a user saves them for dashboard-connected workflows
Never supplied	third-party accounts	BreachScope does not provide Slack, GitHub, OpenAI, Firecrawl, or incident-management accounts
Private routes	dashboard/API	robots.txt blocks authenticated and operational routes from crawlers

Commands

breachscope scan

The primary scanner for code, dependency, toolchain, blackbox, smoke, policy, baseline, and evidence workflows.

--modebasic | major | deep

Dependency traversal depth

--breachoff

Supply-chain, CVE, credentials, exposure

--bugoff

Code vulnerability focus

--cioff

Fail on configured threshold or policy violation

--policynone

External policy file

--baselinenone

Suppress known legacy findings

--outputconsole

console | json | sarif

--mode	basic \| major \| deep	Dependency traversal depth
--breach	off	Supply-chain, CVE, credentials, exposure
--bug	off	Code vulnerability focus
--ci	off	Fail on configured threshold or policy violation
--policy	none	External policy file
--baseline	none	Suppress known legacy findings
--output	console	console \| json \| sarif

bash

breachscope scan --ci --policy release-gate.yml --output sarif --file breachscope.sarif

breachscope sandbox

Builds an isolated Docker runtime for active security testing. Secrets are excluded by default.

bash

breachscope sandbox --deep --breach --bug
breachscope sandbox --bug --ci
breachscope sandbox --include-secrets

Use `--include-secrets` only in disposable environments where active exploitation with real credentials is intentional.

breachscope sbom

Generate release evidence in CycloneDX or SPDX JSON.

bash

breachscope sbom --output cyclonedx --file bom.cdx.json
breachscope sbom --output spdx --file bom.spdx.json

OpenVEX and Fix Briefs

Export VEX and remediation briefs from a saved JSON scan.

bash

breachscope scan --output json --file scan.json
breachscope vex --from scan.json --file openvex.json
breachscope suggest-fixes --from scan.json --file fixes.md

Runtime Monitoring

Collect Tracee/eBPF events on Linux hosts where Tracee is installed.

bash

breachscope runtime --container app --duration 120 --file tracee-events.jsonl
breachscope runtime --dry-run

Operations

Controls Model

BreachScope supports policy-as-code, baselines, project-scoped dashboard records, audit logs, scoped API keys, triage fields, and release evidence exports.

Policy

thresholds, budgets, suppressions

Evidence

SARIF, SBOM, OpenVEX, JSON

Triage

status, assignee, due date, risk reason

Audit

project-scoped event history

Policy-as-Code

yaml

policy:
  failOn: high
  maxFindings:
    critical: 0
    high: 3
  blockedPackages:
    - ua-parser-js
  suppressions:
    - fingerprint: "64-character-fingerprint"
      reason: "Accepted during migration"
      expiresAt: "2026-12-31T23:59:59Z"
      approvedBy: "security@example.com"

Dashboard

The dashboard adds projects, policies, integrations, audit logs, scoped keys, settings, scan history, and finding triage.

Projectsweb

Group scans, policies, integrations, and audit history

API keysweb

Least-privilege scopes for automation

Triageweb

Status, ownership, due dates, VEX status, accepted risk

Audit logsweb

Immutable project activity stream

Projects	web	Group scans, policies, integrations, and audit history
API keys	web	Least-privilege scopes for automation
Triage	web	Status, ownership, due dates, VEX status, accepted risk
Audit logs	web	Immutable project activity stream

Identity

SCIM user lifecycle endpoints and SAML metadata are present. SAML ACS fails closed until assertion validation and IdP certificate pinning are configured.

Integrations

Project integrations turn completed scans into provider work: Slack and Teams messages, PagerDuty incidents, Jira and Linear issues, GitHub/GitLab/Bitbucket issues, and audit-backed retry records. Each route uses customer-owned credentials and a configurable severity threshold.

Reference

Security Defaults

API keys are hashed before storage.
Dashboard secrets are AES-256-GCM encrypted.
Scan upload payloads are validated and size-limited.
API key scopes are enforced.
CLI auth polling is replay-safe.
Sandbox excludes secrets by default.

CI/CD

bash

breachscope init-ci
breachscope scan --ci --policy release-gate.yml
breachscope scan --baseline breachscope-baseline.json --new-findings-only --ci

Deployment Checklist

Apply the Drizzle migration.
Configure auth, database, and encryption secrets.
Set Upstash Redis variables for distributed rate limiting.
Connect customer-owned provider credentials for integrations.
Install Tracee on Linux runtime-monitoring hosts.
Configure SAML validation and IdP certificate pinning before enabling SSO.

Legal and Policy Pages

Public terms, privacy, acceptable use, and data protection pages are available as normal App Router pages and included in the sitemap for crawler discovery.

/termspublic

service terms, user responsibilities, customer content, and customer-owned integrations

/privacypublic

data categories, purposes, retention, rights, subprocessors, and contact paths

/acceptable-usepublic

authorized testing rules and abuse boundaries

/data-protectionpublic

controller/processor roles, safeguards, incident process, deletion, and transfer notes

/securitypublic

supported versions, vulnerability reporting, response targets, and security practices

/terms	public	service terms, user responsibilities, customer content, and customer-owned integrations
/privacy	public	data categories, purposes, retention, rights, subprocessors, and contact paths
/acceptable-use	public	authorized testing rules and abuse boundaries
/data-protection	public	controller/processor roles, safeguards, incident process, deletion, and transfer notes
/security	public	supported versions, vulnerability reporting, response targets, and security practices

Changelog

See the repository `CHANGELOG.md` for release history and verification notes.