breachgraph
Find the few security findings an attacker can actually chain into a breach.
Open the live demo: the real report for a small vulnerable platform (Flask on EKS, Terraform, GitHub Actions). Click a path to trace it, or mark a finding as fixed and watch the paths it breaks disappear. Nothing to install.
breachgraph runs Semgrep, Gitleaks, Trivy, Checkov and zizmor on your repository, then reads your code, Kubernetes manifests, Terraform (AWS, Azure, GCP) and GitHub Actions workflows to build one graph of how they connect. It reports the attack paths: an SSRF on a public route, in a pod on a node whose role can read the customer bucket, is a breach, even though each scanner saw only one piece of it. On a pull request it answers one question first: does this change open a new way in?
Results on real projects
breachgraph was run with default settings on eight public projects: deliberately vulnerable training projects, where the real attack chains are documented, and Google's Online Boutique as a healthy control. Every path it reported was checked by hand.
| Project | Findings after dedupe | Attack paths | Real |
|---|---|---|---|
| terragoat | 1,088 | 2 | 2 |
| kubernetes-goat | 838 | 0 | 0 |
| cloudgoat | 1,446 | 1 | 1 |
| awsgoat | 785 | 3 | 3 |
| azuregoat | 504 | 2 | 2 |
| gcpgoat | 411 | 5 | 4 |
| juice-shop | 411 | 2 | 2 |
| online-boutique (control) | 990 | 0 | 0 |
| Total | 6,473 | 15 | 14 |
6,473 findings come down to 15 attack paths, and 14 of them are real chains an attacker could use (93% precision). The control project gets none.
The method, every path with the reason it is or isn't real, the scenarios breachgraph missed, and what it finds from a leaked key or a foothold inside the cluster are in docs/benchmark.md. Anyone can rerun it.
Quick start
On GitHub, add a workflow:
# .github/workflows/breachgraph.yml
name: breachgraph
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
security-events: write # findings in code scanning
pull-requests: write # the PR comment
jobs:
breachgraph:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: amoghnellutla/breachgraph@v0
Or let breachgraph write it, along with a starter config, and tell you what it found in the repository:
pip install breachgraph
breachgraph init
Anywhere else, the Docker image has every scanner at a pinned version:
docker run --rm -v "$PWD:/src" ghcr.io/amoghnellutla/breachgraph scan .
The report lands in breachgraph-report/ (HTML, JSON, SARIF, Markdown). pip install breachgraph
works too; it runs whichever scanners are installed and breachgraph doctor lists them. There is a
GitLab CI template in templates/ and more GitHub recipes in
docs/github-action.md.
What a pull request sees
The comment leads with the change in attack paths compared with the default branch, drawn as a diagram, then the findings that block the merge:
This change opens 1 new attack path(s)
→ S3 bucket shop-customer-data-prod · high confidence
flowchart LR
n0["Internet"] --> n1["Ingress api"] --> n2["Deployment shop/api"] --> n3["GET /fetch"]
n3 -- "ssrf" --> n4["IAM role eks-node-role"] --> n5["S3 bucket shop-customer-data-prod"]
style n5 stroke-width:3px
Internet→ Ingress api → Deployment shop/api → GET /fetch → IAM role eks-node-role (ssrf,services/api/app.py:19) → S3 bucket shop-customer-data-prodMITRE ATT&CK: T1190, T1552.005, T1530
Fix these first: SSRF
services/api/app.py:23, breaks 1 path
That is the demo in examples/vulnerable-platform, compared with a version of it without the SSRF: the API runs on a node whose role can read the customer bucket, so the SSRF is a way to that bucket, not just a finding.
Findings and paths that already exist on the default branch don't fail the pull request, so you can turn the gate on in a legacy repository on day one. If a pull request edits the gate's own settings (a lower threshold, a new suppression, a scanner turned off), the comment says so.
How it decides what matters
- No free ride. Reaching a workload over the network is not owning it. Every step that gains control needs a real weakness at that step: code execution, injection, SSRF to a metadata endpoint, a committed credential, a known-exploited CVE in a package the code imports. With no such weakness, a public pod with an over-broad role is reported as exposure, not as a path. This is a test, not a promise.
- Cloud permissions are evaluated, not listed. AWS policies with wildcards, resource scoping, explicit deny and privilege-escalation primitives; AssumeRole chains where both the caller's policy and the role's trust allow it; Azure role definitions by scope and data actions; GCP bindings and service-account impersonation; EKS, AKS and GKE workload identity.
- It reads how you deploy. Kubernetes manifests and Helm charts (rendered with
helm template), Docker Compose, Terraform, and hosting platforms: Vercel, Netlify, Render, Fly.io, Procfile apps and App Engine say for themselves what is public. - CI is part of the attack surface. A script injection in an
issue_commentworkflow reaches whatever that job can reach: its OIDC deploy role (checked against the trust policy'ssubclaim), its secrets, a token that can push code. See docs/cicd.md. - The cheapest fix is named, and often written for you. Each path lists the findings it needs,
and the report ranks the fixes that break the most paths.
breachgraph fixwrites the safe ones (a dependency upgrade to its fixed version, theenv:fix for a GitHub Actions script injection) and with--propens one pull request per fix. Anything it can't fix safely gets a reason. - It says what it couldn't see. Every report has a coverage line: how many routes, workloads, cloud resources, Kubernetes objects and CI jobs were modeled, and why a clean result might be incomplete (a scanner that didn't run, Helm charts that weren't rendered, no deployment configuration).
- Findings are scored by exploitability: CISA KEV, FIRST EPSS, whether a vulnerable package is imported at all (and for Go, whether the vulnerable function is called), agreement between tools, and whether the finding sits on a path.
The model, its rules and its limits: docs/attack-graph.md.
Starting points beyond the internet
Some breaches start from a key that leaked or a pod that was already compromised. Turn these on to see what each would reach:
# .breachgraph.yml
attack_graph:
entry_points: [internet, credentials, cluster]
credentials treats every access key Terraform manages as leaked; cluster assumes code running
inside the Kubernetes network, limited by your NetworkPolicies. Paths that start from an assumption
are named that way in every report.
Policy
# .breachgraph.yml
fail_on:
priority: P1 # new P1 findings fail; attack paths, KEV CVEs and secrets always do
suppressions:
- vuln: CVE-2023-12345
reason: "Parser not reachable from any route; tracked in SEC-142"
expires: 2026-12-31
Suppressions need a reason and an expiry date. Everything else is in docs/configuration.md.
Output
SARIF for GitHub code scanning (with MITRE ATT&CK and OWASP CI/CD tags), a sticky PR comment and job
summary, a self-contained HTML report with an interactive graph, JSON, Markdown, a CycloneDX SBOM,
and GitHub issues per finding if you want them. Also available: JUnit, and OpenVEX statements from
reachability for Trivy and Grype (docs/vex.md). Existing reports from ZAP, CodeQL or
any SARIF tool merge in with --import.
For the rest of the team: a Slack or Teams message when a change opens an attack path (set the
action's slack-webhook or teams-webhook input from a secret), and -f evidence, one zip with
the reports, SBOM, the policy and every accepted risk, a plain summary for auditors and a SHA-256
manifest.
Optional AI triage with your own Anthropic key gives each top finding a verdict and a concrete fix, judged from the enclosing function, its route and its attack path. It is advisory, never changes the gate, and has a hard spend cap. See docs/ai-triage.md.
Trust
breachgraph reads code it does not trust, often next to CI credentials. It never executes repository content, never reads outside the scanned tree, and redacts secrets twice. Scanner binaries are checksum-verified, every Python package is installed from a hash-pinned lock, actions are pinned to commits, and releases are signed with Sigstore and ship with SBOM and provenance. The threat model is in docs/architecture.md.
Limits
Dependency reachability is import-level, plus function-level evidence for Go (calls to the vulnerable symbols the Go vulnerability database names); calls made by other dependencies are not traced. Azure and GCP are read from Terraform only. Helm charts are rendered with their default values only, and Kustomize overlays are not built yet.
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md. Report a vulnerability in breachgraph privately as described in 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).
Metadata
Release files for breachgraph 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| breachgraph-0.4.0.tar.gz | 182.8 kB | With provenance | Details for breachgraph-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| breachgraph-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for breachgraph-0.4.0-py3-none-any.whl |
Total release size: 391.5 kB
Release files / breachgraph-0.4.0.tar.gz
| Download URL | breachgraph-0.4.0.tar.gz |
|---|---|
| Size | 182.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d563bb7d95973d3cc72f21a674be46915b29f3b8f8aa790f544cc8c2417f3ee
|
|
BLAKE2b-256 checksum How to use checksums |
1c0749afa6236fd690133ced7f5c48629da4a7ca3a41086fd09ceda5b065d70a
|
| 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 logRelease files / breachgraph-0.4.0-py3-none-any.whl
| Download URL | breachgraph-0.4.0-py3-none-any.whl |
|---|---|
| Size | 208.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cda5aa9003de2bd24e4170720fc40f425b0e07b200094c51c991ea85a428c427
|
|
BLAKE2b-256 checksum How to use checksums |
b57894d17a0d824994d0a2c2e21a9cb08b8cd75d7dfd3cf562566cbedf8fa234
|
| 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 logSecurity for breachgraph 0.4.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.
Attestation for breachgraph-0.4.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 logA 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.