Skip to main content

🛡️ breachgraph

Find the attack paths that matter — from code to cloud.

breachgraph runs the open-source scanners you already trust (Semgrep, Gitleaks, Trivy, Checkov, zizmor, ZAP), then does what they can't: it builds one code-to-cloud graph and finds the real attack paths — the chains where an internet-facing route, a vulnerability, a container and an over-broad IAM role line up so an outsider can reach your crown-jewel data. It ranks findings by whether they actually lie on such a path, so you fix the ten things that can hurt you, not the three hundred that can't.

ci self-scan License: Apache-2.0 Python 3.11+


Why this is different

Most tools hand you a list. A big security team already has Snyk, CodeQL and a cloud scanner — what they lack is the connection between layers. A medium-severity SSRF is boring on its own. SSRF on an internet-facing route, in a pod with host networking, whose node role can read the customer-data bucket, is a breach. No single scanner sees that chain, because each one looks at only one layer.

breachgraph joins the layers — code → container → Kubernetes → cloud IAM → data — into one graph and asks the question that matters: what can an attacker actually reach, and how?

It is not a gimmick: every step that represents gaining control requires a real weakness. Being reachable on the network is not the same as being owned. With zero code vulnerabilities, breachgraph reports no path to your data even if the pod is public and its role is over-broad — you can see that guarantee as a test. Fix the one cheapest link (the "choke point") and the whole path disappears.

breachgraph attack paths

What you get

🎯 Attack-path analysis Joins code, containers, Kubernetes and Terraform (AWS, Azure, GCP) into one graph and finds every chain from the internet to a crown-jewel asset. Each independent entry point surfaces separately; each path names the cheapest fix
☁️ Real cloud reasoning Evaluates AWS IAM policies (scoping, managed policies, explicit-Deny-wins, privilege-escalation primitives), Azure role assignments (Actions/NotActions/DataActions by scope, Key Vault access policies), GCP IAM bindings (predefined and custom roles, service-account impersonation), EKS IRSA, AKS and GKE workload identity, node identities, public exposure (LBs, security groups, public buckets/DBs, unauth Lambda URLs), Kubernetes RBAC and container escape
🔍 Coverage SAST (Semgrep) · secrets (Gitleaks) · dependency CVEs, IaC, container images, licenses (Trivy) · IaC (Checkov) · GitHub Actions (zizmor, plus built-in pwn-request, script-injection and dependency-confusion checks) · DAST (ZAP) · plus any SARIF tool (CodeQL, Bandit, gosec…) via --import
🔗 CI/CD attack paths A script injection in an issue_comment workflow is not just a finding: breachgraph follows the job's OIDC deploy role, secrets and write token to what they reach, and checks trust policies against the token the job really gets. See docs/cicd.md
🧹 Deduplication Cross-tool clustering (e.g. Trivy AVD-DS-0002 ≡ Checkov CKV_DOCKER_3) and same-tool rule overlap — at most one finding per tool in each cluster
📊 Risk-based priority CVSS/severity adjusted by CISA KEV (actively exploited → always P1), FIRST EPSS, confidence, multi-tool agreement and reachability to crown jewels. Every score explains itself
🚦 Gate that teams keep on Content-based fingerprints + baselines, so only new findings and new attack paths fail the build. Suppressions require a reason and an expiry date
💬 Feedback where developers are Sticky PR comment with the attack-path diagram · inline code-scanning annotations (SARIF) · job summary · auto-managed GitHub issues
📦 Reports SARIF 2.1.0 · JSON · self-contained HTML (interactive attack-path flows) · Markdown · JUnit · CycloneDX SBOM
🤖 Optional AI triage Bring your own Anthropic key: a real / likely-false-positive / needs-review verdict and a concrete fix per top finding, judged from the enclosing function, its HTTP route, its attack path, and how a vulnerable package is actually called. Advisory only, secrets redacted, spend cap. See docs/ai-triage.md
🔒 Trustworthy itself Scanner binaries pinned and SHA-256 verified · actions pinned to commit SHAs · signed images with SBOM + provenance · secrets always redacted · untrusted scanner output escaped

breachgraph findings report

Quick start

GitHub Actions

# .github/workflows/breachgraph.yml
name: breachgraph
on: [pull_request, push]
permissions:
  contents: read
  security-events: write   # code scanning upload
  pull-requests: write     # PR comment
jobs:
  breachgraph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: amoghnellutla/breachgraph@v0

More recipes (baselines, DAST, container images, issue tracking) are in docs/github-action.md.

Docker (any CI, or your laptop)

docker run --rm -v "$PWD:/src" ghcr.io/amoghnellutla/breachgraph scan .
open breachgraph-report/breachgraph.html

pip

pip install breachgraph
breachgraph doctor          # shows which scanners are on PATH
breachgraph scan .

The pip package only orchestrates. It runs whichever scanners are installed and skips the rest. The Docker image bundles all of them at pinned versions.

GitLab CI

include:
  - remote: https://raw.githubusercontent.com/amoghnellutla/breachgraph/v0/templates/gitlab-ci.yml

Try it on the demo app

examples/vulnerable-app is an intentionally vulnerable Flask app with Terraform, Kubernetes and Dockerfile misconfigurations, fake secrets and Log4Shell:

docker run --rm -v "$PWD:/src" ghcr.io/amoghnellutla/breachgraph scan examples/vulnerable-app
      ok gitleaks     2 findings     0.7s
      ok checkov     50 findings     8.2s
      ok semgrep     26 findings     9.2s
      ok trivy      149 findings    25.5s
| Prio | Risk | Finding                                                      | Location     | Tools            | Status     |
| P1   | 10.0 | CVE-2021-44228 in log4j-core 2.14.1: Remote code exec  KEV   | pom.xml:11   | trivy            | BLOCKS new |
| P1   | 10.0 | Hardcoded secret: Identified a Private Key                   | settings.py:6| gitleaks,semgrep | BLOCKS new |
...
Gate failed: 104 finding(s) at or above the threshold (priority >= P2, any KEV, any secret)

Adopting it on an existing codebase

# 1. Accept what exists today
breachgraph scan --write-baseline .breachgraph-baseline.json && git add .breachgraph-baseline.json

# 2. Turn the gate on. From now on only NEW findings fail PRs.
# 3. Burn down the baseline over time; accepted risks go into .breachgraph.yml with an expiry:
# .breachgraph.yml
fail_on:
  priority: P2        # new P1/P2 findings fail the build
  kev: true           # so does anything actively exploited
  secrets: true       # and any hardcoded secret
suppressions:
  - vuln: CVE-2023-12345
    reason: "Vulnerable code path not reachable; tracked in SEC-142"
    expires: 2026-12-31

Full reference: docs/configuration.md.

Attack paths

examples/vulnerable-platform is a small microservice (Flask API on EKS with IRSA, plus Terraform) with a real internet-to-S3 path. breachgraph reports:

🎯 2 attack path(s) to crown-jewel assets
  1. [high] risk 14.0 BLOCKS
     Internet → Ingress api → Deployment shop/api → GET /thumbnail
       → ServiceAccount shop/api (code_execution) → IAM role api-pod-role
       → S3 bucket shop-customer-data-prod
  2. [high] risk 12.73 BLOCKS
     Internet → Ingress api → Deployment shop/api → GET /fetch
       → IAM role eks-node-role (ssrf → node metadata) → S3 bucket shop-customer-data-prod
  Fix first:
    • Command injection via os.popen (services/api/app.py:30) — breaks 1 path(s)
    • SSRF via requests.get (services/api/app.py:23) — breaks 1 path(s)

Two independent ways in (command injection gives the pod role; SSRF steals the node role via the metadata endpoint) surface separately, because fixing one does not fix the other. Run it yourself:

breachgraph scan examples/vulnerable-platform     # scanners + attack graph
breachgraph graph examples/vulnerable-platform    # attack graph only

How reachability and IAM are modeled: docs/attack-graph.md.

How it works

flowchart LR
    A[Semgrep · Gitleaks · Trivy · Checkov · zizmor · built-in CI/CD · ZAP · SARIF] --> B[Normalize<br/>CWE · OWASP · fingerprint]
    B --> C[Dedupe] --> D[Enrich<br/>KEV · EPSS] --> E[Score P1–P4]
    E --> G2[Attack graph<br/>code→cloud paths]
    CFG[Kubernetes · Terraform · routes] --> G2
    G2 --> F[Baseline ·<br/>suppressions]
    F --> GATE{Gate}
    GATE --> H[SARIF · PR comment · HTML · issues]

Design notes and how to add a scanner: docs/architecture.md.

CLI

breachgraph scan [PATH]      Scan and gate
  -c, --config FILE        .breachgraph.yml (auto-detected)
  -b, --baseline FILE      accepted findings (auto-detected .breachgraph-baseline.json)
  --write-baseline FILE    accept all current findings
  -f, --format LIST        json,sarif,html,md,junit
  --only / --skip LIST     choose scanners
  --import TOOL=FILE       ingest existing reports (semgrep, gitleaks, trivy, checkov, zap, sarif)
  --fail-on P1..P4|none    override the threshold
  --dast-url URL           run ZAP against a running app
  --image REF              scan a container image
  --github-comment         sticky PR comment
  --github-issues P1       open/close issues per finding
  --ai                     AI triage (bring your own ANTHROPIC_API_KEY): verdicts + fixes, advisory
  --offline                skip KEV/EPSS
  --no-fail                report only
breachgraph graph [PATH]          build the attack graph only (--findings a prior scan)
breachgraph report results.json   re-render reports, optionally with a new policy
breachgraph doctor                show installed scanners
breachgraph init                  write a starter .breachgraph.yml and workflow

Exit codes: 0 pass · 1 gate failed · 2 usage/config error · 3 scanner error (opt-in).

Roadmap

  • Reachability for dependency CVEs: is the package imported by first-party code, and is that code reachable from an HTTP route (Python/JS/TS/Java/Go)
  • Function-level reachability: is the vulnerable function itself called
  • Bring-your-own-key AI triage: optional; with your own Anthropic key, a verdict and fix per top finding, grounded in the enclosing code, route and attack path. Advisory, defensive-only, with a spend cap. See docs/ai-triage.md
  • Azure and GCP in the attack graph
  • CI/CD and supply chain: GitHub Actions script injection and pwn requests, zizmor audits, dependency confusion, and CI jobs as attack-graph entry points (OIDC roles, secrets, write tokens). See docs/cicd.md
  • Malicious-package detection; GitLab CI
  • OSV-Scanner and Grype adapters; GitLab merge-request notes; trend history across runs

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md. To report a vulnerability in breachgraph itself, see SECURITY.md.

License

Apache-2.0. The bundled scanners keep their own licenses: Semgrep CE (LGPL-2.1), Gitleaks (MIT), Trivy (Apache-2.0), Checkov (Apache-2.0), zizmor (MIT), ZAP (Apache-2.0).

Metadata

Release files for breachgraph 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for breachgraph 0.1.0
File Size Uploaded Provenance Actions
breachgraph-0.1.0.tar.gz 130.3 kB With provenance Details for breachgraph-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for breachgraph 0.1.0
File Interpreter ABI Platform Actions
breachgraph-0.1.0-py3-none-any.whl Python 3 none any Details for breachgraph-0.1.0-py3-none-any.whl

Total release size: 285.8 kB

Release files / breachgraph-0.1.0.tar.gz

Download URL breachgraph-0.1.0.tar.gz
Size 130.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0e833e4c5fdd1dd53b033701ea32d07769845dff03240d0d692f99dc68d48ce0
BLAKE2b-256 checksum
How to use checksums
8cf372a7648ffc6e914dcd4cd827bf0dd387a6be73dfc012e559aaddde1e8342
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / breachgraph-0.1.0-py3-none-any.whl

Download URL breachgraph-0.1.0-py3-none-any.whl
Size 155.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b95459c2f5b8e9ee60c5ab811848ba9a0fef446f17a24b63213bb44c78a17f28
BLAKE2b-256 checksum
How to use checksums
d7498a70176e07a223fc2756967ff6040a5f08c936f1f99a41c46078d0f66e45
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for breachgraph 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for breachgraph-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page