Metadata-Version: 2.5
Name: breachgraph
Version: 0.2.0
Summary: Attack-path-aware security gate for CI: runs Semgrep, Gitleaks, Trivy, Checkov, zizmor and ZAP, links findings to code, Kubernetes, cloud IAM (AWS, Azure, GCP) and GitHub Actions, and fails the build on real internet-to-crown-jewel paths.
Project-URL: Homepage, https://github.com/amoghnellutla/breachgraph
Project-URL: Documentation, https://github.com/amoghnellutla/breachgraph/tree/main/docs
Project-URL: Issues, https://github.com/amoghnellutla/breachgraph/issues
Author: breachgraph contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: appsec,attack-path,checkov,cloud-security,devsecops,github-actions,gitleaks,iac,sarif,sast,sca,security,semgrep,supply-chain,trivy,zizmor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.6
Requires-Dist: python-hcl2>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: tree-sitter-go>=0.25
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.25
Requires-Dist: tree-sitter-python>=0.25
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.26
Requires-Dist: typer>=0.12
Provides-Extra: ai
Requires-Dist: anthropic>=1.13; extra == 'ai'
Provides-Extra: dev
Requires-Dist: anthropic>=1.13; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

﻿<div align="center">

# 🛡️ 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](https://github.com/amoghnellutla/breachgraph/actions/workflows/ci.yml/badge.svg)](https://github.com/amoghnellutla/breachgraph/actions/workflows/ci.yml)
[![self-scan](https://github.com/amoghnellutla/breachgraph/actions/workflows/self-scan.yml/badge.svg)](https://github.com/amoghnellutla/breachgraph/actions/workflows/self-scan.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)

</div>

---

## 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](tests/test_graph_paths.py). Fix the one cheapest link
(the "choke point") and the whole path disappears.

**Measured, not claimed.** On 8 public projects (TerraGoat, CloudGoat, Kubernetes Goat, AWS/Azure/GCP
Goat, OWASP Juice Shop, and Google's Online Boutique as a control), 6,346 deduplicated findings reduced to
**12 attack paths, 11 of them real (92% precision)**, with no false paths on the control project. Every
path is hand-labeled, every miss is documented, and anyone can re-run it:
[docs/benchmark.md](docs/benchmark.md).

<p align="center"><img src="docs/img/attack-paths.png" alt="breachgraph attack-graph explorer: a selected path from the internet through an injectable CI job and its OIDC deploy role to the customer-data bucket" width="860"></p>

## 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](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 · **OpenVEX** from reachability, consumable by Trivy/Grype ([docs/vex.md](docs/vex.md)) |
| 🤖 **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](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 |

<p align="center"><img src="docs/img/html-report.png" alt="breachgraph HTML report header" width="820"></p>

## Quick start

### GitHub Actions

```yaml
# .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](docs/github-action.md).

### Docker (any CI, or your laptop)

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

### pip

```bash
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

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

## Try it on the demo app

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

```bash
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

```bash
# 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:
```

```yaml
# .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](docs/configuration.md).

## Attack paths

[`examples/vulnerable-platform`](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:

```bash
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](docs/attack-graph.md).

## How it works

```mermaid
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](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

- [x] **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)
- [x] **Public benchmark** on 8 real projects with hand-labeled paths and documented misses ([docs/benchmark.md](docs/benchmark.md))
- [ ] Function-level reachability: is the vulnerable function itself called
- [ ] Entry points beyond the internet: leaked credentials (IAM user keys, SSH keys) and an "assume breach inside the cluster" mode
- [ ] Know when an SSRF controls request headers (decides whether metadata servers that need a header are reachable)
- [x] **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](docs/ai-triage.md)
- [x] Azure and GCP in the attack graph
- [x] **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](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](CONTRIBUTING.md). To report a vulnerability in
breachgraph itself, see [SECURITY.md](SECURITY.md).

## License

[Apache-2.0](LICENSE). 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).
