breachgraph 0.1.0__tar.gz

breachgraph-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+breachgraph-report/
+.env
+.tmp/

breachgraph-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- `breachgraph scan` orchestrating Semgrep (SAST), Gitleaks (secrets), Trivy (SCA, IaC, images,
+  licenses, CycloneDX SBOM), Checkov (IaC) and OWASP ZAP (DAST) in parallel.
+- `--import` for existing reports from any supported tool or any SARIF 2.1.0 producer.
+- Normalized finding model with CWE and OWASP Top 10 (2021) mapping and content-based fingerprints.
+- Two-stage deduplication (same-tool rule overlap and cross-tool clustering, at most one finding
+  per tool in each cluster).
+- CISA KEV and FIRST EPSS enrichment with on-disk caching and offline fallback.
+- Risk score (0–10) and P1–P4 priority with an explanation for every score.
+- Policy as code (`.breachgraph.yml`): thresholds, path excludes and deprioritization, suppressions
+  with mandatory reason and expiry, severity overrides.
+- Baselines (`--write-baseline`) so only new findings fail the gate.
+- Reports: SARIF (GitHub code scanning), JSON, HTML, Markdown, JUnit.
+- GitHub integration: sticky PR comment, job summary, automatic issues for P1 findings.
+- Composite GitHub Action, GitLab CI template, Docker image with pinned and checksum-verified scanners.
+- `breachgraph report`, `breachgraph doctor`, `breachgraph init`.
+
+- **CI/CD and supply chain.** Built-in checks for the attacks that actually hit CI: script
+  injection of outsider-controlled text (`issue.title`, `comment.body`, branch names) into `run:`
+  and `github-script`; pwn requests (`pull_request_target`/`workflow_run` jobs that check out and
+  run pull request code, critical when the job holds secrets or a write token); and dependency
+  confusion via pip `--extra-index-url` / uv `unsafe-best-match`. Maintainer-only `if:` gates lower
+  severity. zizmor runs too (bundled in the image) for broader Actions hygiene; its findings merge
+  with the built-in ones.
+- **CI jobs in the attack graph.** Jobs that outsiders can start are entry points; their OIDC
+  cloud identities (checked against AWS trust `sub` conditions and Azure federated subjects),
+  secrets and write-capable `GITHUB_TOKEN` are linked behind code execution. A role that trusts
+  GitHub OIDC without naming a repository is flagged as reachable from the internet. The demo now
+  includes an `issue_comment` injection that reaches the customer-data bucket through a deploy
+  role scoped "safely" to `main`.
+
+- **Azure and GCP in the attack graph** (Terraform). Azure: role assignments evaluated as
+  Actions/NotActions/DataActions over their scope, custom roles, Key Vault RBAC and access
+  policies, privilege escalation via `roleAssignments/write`, managed identities on VMs, App
+  Service, Functions, Container Apps and AKS, NSG/public-IP exposure, public blob containers and
+  database firewalls, AKS workload identity. GCP: IAM members/bindings/policies from organization
+  to resource level, predefined and custom roles, service-account impersonation chains,
+  `setIamPolicy` escalation, GCE/Cloud Run/Cloud Functions/GKE identities, firewall exposure,
+  public invokers, buckets, datasets and Cloud SQL, GKE Workload Identity. SSRF to the Azure or
+  GCP metadata endpoint is low confidence, because it needs a request header.
+
+- **Attack-path analysis**: a code-to-cloud graph (Kubernetes, Terraform/AWS, HTTP routes in
+  Python/JS/TS/Java/Go) that finds chains from the internet to crown-jewel assets. Every
+  control step requires a real weakness, so network exposure alone never reaches credentials.
+- Real AWS IAM evaluation (scoping, managed policies, explicit-Deny-wins, privilege escalation),
+  EKS IRSA and node roles, Kubernetes RBAC and container-escape detection, exposure analysis.
+- Choke-point analysis: the cheapest fixes that break the most paths.
+- Attack paths render in the HTML report (flow diagram), the PR comment and the console; the gate
+  can fail on new attack paths (`attack_graph.fail_on_new_path`).
+- `breachgraph graph` command to build the graph standalone.
+- `examples/vulnerable-platform` demo with a real internet-to-S3 path.
+- **AI-assisted triage (bring your own key)**: optional, off by default. With your own
+  `ANTHROPIC_API_KEY`, each top finding gets a real / likely-false-positive / needs-review verdict,
+  reasoning with line numbers, and a concrete fix with corrected code. The model sees what a
+  reviewer would open: the whole enclosing function and the HTTP route that runs it, the attack
+  path the finding is a step on, and for dependency CVEs the lines that call the package. Advisory
+  only (never changes the gate), defensive only, secrets redacted before sending, a spend cap
+  enforced before each request, and every failure (no key, refusal, API error) is a warning, never
+  a failed scan. Enable with `--ai`; see docs/ai-triage.md.
+- **Reachability analysis**: for each dependency CVE, checks whether first-party code actually
+  imports the package (Python/JS/TS/Java/Go via tree-sitter) and whether the importing module is
+  reachable from an HTTP entry point. Unused (transitive-only) CVEs are deprioritized and don't
+  gate by default; reachable ones are flagged. Also decides which dependency CVEs can be weapons
+  in the attack graph.
+
+[Unreleased]: https://github.com/amoghnellutla/breachgraph/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/amoghnellutla/breachgraph/releases/tag/v0.1.0

breachgraph-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

breachgraph-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: breachgraph
+Version: 0.1.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.
+
+<p align="center"><img src="docs/img/attack-paths.png" alt="breachgraph attack paths" 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 |
+| 🤖 **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 findings report" 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)
+- [ ] Function-level reachability: is the vulnerable function itself called
+- [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).