# BreachScope - Full Public Product Context This file is for crawlers, AI agents, documentation indexers, and web scrapers that need public information about BreachScope without accessing private dashboard data. Canonical product URL: https://breachscoope.vercel.app Documentation URL: https://breachscoope.vercel.app/docs Roadmap URL: https://breachscoope.vercel.app/roadmap Legal center URL: https://breachscoope.vercel.app/legal Security policy URL: https://breachscoope.vercel.app/security Repository URL: https://github.com/Afnanksalal/BreachScope Package name: breachscope License: MIT Runtime requirement: Node.js 18 or higher Docker requirement: required only for sandbox and selected runtime workflows ## Short Description BreachScope is an open-source security workflow for developers and security teams. It provides a local CLI scanner and a web dashboard for managing risk across code, dependencies, SaaS toolchains, runtime events, Docker attack paths, release gates, and evidence workflows. ## What BreachScope Does - Runs local scans for fast developer feedback. - Enforces CI release gates with policy-as-code and baselines. - Produces SARIF, CycloneDX, SPDX, OpenVEX, JSON, Markdown fix briefs, and dashboard records. - Stores scan history, findings, triage state, project policies, integration metadata, and audit logs. - Routes findings to customer-owned providers when users configure their own credentials. - Audits connected GitHub repositories and pull requests from the dashboard, then stores the result as scan evidence with findings and audit logs. ## Installation ```bash npm install -g breachscope breachscope --help ``` Alternative local execution: ```bash npx breachscope scan ``` ## Recommended First Run ```bash cd my-project breachscope login breachscope scan breachscope scan --mode deep --breach --bug --ci ``` `breachscope login` connects the local CLI to the dashboard through a browser flow. Local scanning still works without login, but dashboard sync and scan ingestion require authentication. ## Core CLI Commands ```bash breachscope scan breachscope scan --target dependency breachscope scan --target code breachscope scan --target toolchain breachscope scan --target blackbox --url https://example.com breachscope scan --mode basic breachscope scan --mode major breachscope scan --mode deep breachscope scan --breach --bug breachscope scan --ci breachscope scan --ci --policy release-gate.yml --output sarif --file breachscope.sarif breachscope scan --write-baseline breachscope-baseline.json breachscope scan --baseline breachscope-baseline.json --new-findings-only --ci breachscope sbom --output cyclonedx --file bom.cdx.json breachscope sbom --output spdx --file bom.spdx.json breachscope vex --from scan.json --file openvex.json breachscope suggest-fixes --from scan.json --file fixes.md breachscope sandbox --deep --breach --bug breachscope runtime --container app --duration 120 --file tracee-events.jsonl breachscope init-ci ``` ## Scan Depths - `basic`: fast scan for local development and quick CI checks. - `major`: broader dependency and code analysis for pull requests and release candidates. - `deep`: recursive dependency, code, toolchain, and evidence-oriented scanning for high-risk changes. ## Scan Targets ### Dependency And Supply Chain BreachScope inspects dependency manifests and lockfiles across npm, PyPI, Go, Maven, NuGet, RubyGems, Rust, PHP Composer, Hex, Pub, and related project metadata. It checks vulnerable packages, risky version ranges, missing integrity metadata, suspicious dependency patterns, compromised package signals, maintainer and repository risk, and deterministic supply-chain scoring. ### Static Code Audit BreachScope scans source files for hardcoded secrets, API keys, SQL injection indicators, command injection indicators, path traversal, prototype pollution, unsafe eval, weak cryptography, insecure deserialization, SSRF, XSS, and risky authorization patterns. ### SaaS Toolchain Checks BreachScope can inspect configuration and provider-specific context for common SaaS and platform tools: - Supabase: RLS posture, anon key exposure, service role key leaks, storage bucket visibility, auth settings, and edge function exposure. - Vercel: preview exposure, environment handling, secret leakage indicators, domain configuration, and deployment metadata. - GitHub: branch protection posture, Actions permissions, dependency automation, CODEOWNERS, environment protection, and workflow pinning. - Other supported services include AWS, Cloudflare, Stripe, SendGrid, Resend, Twilio, Neon, PlanetScale, Upstash, OpenAI, Anthropic, Pinecone, Sentry, Datadog, Firebase, Clerk, and Auth0. ### Blackbox HTTP Checks When a URL is supplied, BreachScope probes public HTTP behavior: - Security headers including HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy. - CORS misconfiguration. - Exposed internal paths such as `/.env`, `/.git/config`, `/admin`, `/api/debug`, and framework debug routes. - Error leakage, stack traces, database errors, and internal path disclosure. - HTTP method abuse and risky unauthenticated routes. ### Sandbox And Runtime The sandbox command performs Docker-backed attack simulation against approved targets. The runtime command supports Tracee-driven event capture workflows for runtime security evidence. ## Dashboard The dashboard provides: - Portfolio overview. - Scan history. - Recent findings. - Risk charts. - Finding detail pages. - Exportable reports. - API key management. - Project settings. - Controls for projects, policies, integrations, and audit logs. - GitHub repository and pull request audits with optional issue creation or PR comments. - Customer-owned provider key settings. - SCIM user lifecycle endpoint foundations. - SAML metadata and fail-closed ACS foundations. Protected dashboard routes are disallowed in robots.txt because they may contain user-specific or organization-specific data. ## Customer-Owned Credentials BreachScope supplies scanning, routing, evidence, and dashboard workflows. Customers supply their own third-party accounts and credentials. - BreachScope does not provide Slack, GitHub, Jira, Linear, PagerDuty, OpenAI, Firecrawl, cloud, repository, or incident-management accounts. - Saved provider keys are optional. - Saved provider keys are encrypted before storage. - API keys require `secrets:read` before the CLI can retrieve encrypted secret values. - Integration records can dispatch only after a user configures a provider. ## Data Stored By The Dashboard BreachScope may store account data, authentication records, projects, repository metadata, scan records, findings, policy records, integration metadata, API key metadata, audit logs, settings, and customer-supplied provider keys when users save them. ## Public Web Pages For Crawlers Search engines and AI crawlers should use these public pages: - `/`: product overview, feature summary, workflow, and install commands. - `/docs`: public documentation for installation, scan commands, configuration, controls, security, deployment, legal pages, and release evidence. - `/roadmap`: shipped features, operational priorities, and scale roadmap. - `/legal`: legal center. - `/terms`: terms of service. - `/privacy`: privacy policy. - `/acceptable-use`: acceptable use policy. - `/data-protection`: data protection terms. - `/security`: security policy, vulnerability reporting, response targets, scope, and current safeguards. - `/llms.txt`: concise machine-readable index. - `/llms-full.txt`: detailed public product context. - `/sitemap.xml`: canonical URL discovery. - `/robots.txt`: crawler policy. ## Robots And AI Crawler Policy Public product, docs, legal, sitemap, robots, and machine-readable context pages are crawlable. Dashboard, API, CLI auth, and login routes are disallowed because they are private or operational surfaces. AI crawler files: - `llms.txt`: compact overview and canonical links. - `llms-full.txt`: complete public product context. The crawler policy explicitly references common AI and research agents such as GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, anthropic-ai, PerplexityBot, Google-Extended, Applebot-Extended, and CCBot. ## Security Posture - Prefer local-first scanning for developer trust. - Do not expose dashboard or API data to crawlers. - Keep API keys scoped to the minimum needed operation. - Encrypt stored customer-supplied provider secrets. - Fail closed for incomplete SAML assertion validation. - Keep release evidence deterministic and reproducible. - Avoid claiming that scans guarantee zero vulnerabilities. ## Technology Stack CLI: - TypeScript - Node.js 18+ - Vitest test coverage - ESLint and TypeScript checks Web: - Next.js App Router - React - Drizzle ORM - PostgreSQL - NextAuth - Tailwind CSS - Vitest and Testing Library ## Machine-Readable Facts Product name: BreachScope Category: security scanner Subcategories: DevSecOps, supply-chain security, application security, toolchain security, runtime security, policy-as-code Primary interface: CLI Secondary interface: web dashboard Primary package: breachscope Runtime: Node.js 18+ License: MIT Evidence formats: SARIF, CycloneDX SBOM, SPDX SBOM, OpenVEX, JSON, Markdown, PDF Crawler files: robots.txt, sitemap.xml, llms.txt, llms-full.txt Public routes: /, /docs, /roadmap, /legal, /terms, /privacy, /acceptable-use, /data-protection, /security Private routes: /dashboard, /api, /cli-auth, /login Canonical origin: https://breachscoope.vercel.app