break-anything 0.0.0-stage → 0.2.0

package/DISCLAIMER.md

@@ -0,0 +1,44 @@
+# Responsible use
+
+Break Anything is a **defensive security tool**. It helps you find, prove, and fix
+vulnerabilities in software **you own or are explicitly authorized to test**.
+
+## Authorized scope only
+
+Use Break Anything only against:
+
+- code, dependencies, images, and infrastructure that you own;
+- systems you have **written, contractual authorization** to test (e.g. a pentest engagement
+  with a signed scope);
+- deliberately vulnerable labs and open-source projects intended for security practice.
+
+Do **not** point Break Anything — especially its dynamic (running-app and API) capabilities — at
+any system you do not own or are not authorized to test. Unauthorized testing of computer systems
+is illegal in most jurisdictions and is not supported by this project.
+
+## Safety defaults
+
+- **Dynamic capabilities are off by default.** Running-app scanning, API testing, and any
+  capability that sends traffic to a target require both an operator policy and an explicit
+  per-run authorization flag.
+- **Static analysis reads your files; it does not run them.**
+- **Proof-of-concept output targets your own build.** Break Anything is designed to demonstrate a
+  weakness against your target so you can fix it — not to produce reusable weapons against third
+  parties.
+- **Analysis is local.** Break Anything does not ship your code to a hosted analysis service. The
+  coding agent and model provider you use have their own data policies.
+
+## Not weaponization
+
+Break Anything orchestrates well-known security tooling to help defenders. It is not intended for
+developing malware, building attack infrastructure, targeting systems at scale, or evading the
+defenses of systems you do not control. Contributions that turn it in those directions will be
+declined.
+
+## Your responsibility
+
+You are responsible for using Break Anything in compliance with all applicable laws and
+regulations, and with the license terms of every third-party tool it orchestrates. If you are
+unsure whether you are authorized to test a given target, assume you are not.
+
+Report security issues in Break Anything itself through the process in [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Break Anything contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](docs/readme/README_zh.md)
+
+# Break Anything
+
+### You think your service is secure. You've never seen it the way an attacker would.
+
+Break Anything points your coding agent at your own code, apps, and infrastructure and hunts them
+**like an attacker** — surfacing what's genuinely exploitable, proving it on your own build, and
+fixing it. Before someone else finds it first.
+
+*See your own service through an attacker's eyes.*
+
+[![npm version](https://img.shields.io/badge/npm-break--anything-cb3837?style=flat-square)](https://www.npmjs.com/package/break-anything)
+[![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-tools.md)
+[![Authorized use only](https://img.shields.io/badge/scope-authorized_targets_only-d13438?style=flat-square)](DISCLAIMER.md)
+[![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
+
+**[Quick start](#quick-start) · [Why it's different](#why-its-different) · [See it in 30s](#see-it-in-30-seconds) · [The arsenal](#the-arsenal) · [FAQ](#faq)**
+
+<code>npx break-anything setup</code>
+
+</div>
+
+> [!IMPORTANT]
+> Break Anything tests software **you own or are explicitly authorized to test**. Every
+> proof-of-concept runs against your own target. It's a defensive tool, not an attack framework,
+> and must never be pointed at third-party systems.
+
+<div align="center">
+
+<!-- Record with: vhs demos/hero.tape -->
+<img src="docs/assets/hero.gif" alt="Break Anything: which vulnerabilities actually reach your code, plus a secret hiding in git history" width="900" />
+
+</div>
+
+---
+
+"It's probably fine." It shipped, it works, nobody has complained — so you assume it's secure. But
+"no breach yet" was never a security test. The only honest one is to look at your own service the
+way an attacker will: which dependency is an open door, what key is still in your git history,
+which endpoint hands over another user's data.
+
+And you're never done. A critical unauthenticated RCE turned up in PHP itself in October 2026 after
+years in plain sight (php2shell) — if the language behind much of the web still has critical holes,
+so does your app. Every dependency you add widens the surface, and you can't close them all. So fix
+the few an attacker can reach *today*.
+
+And the economics just flipped: the same AI agents that write code now hunt vulnerabilities at
+scale — and attackers have them too. Find your holes first, with the same leverage.
+
+**Break Anything gives your coding agent that attacker's-eye view** — in one sentence, on software
+you own: what's genuinely exploitable, proven on *your* build, with the fix. Everything runs
+locally. Nothing is pointed anywhere you don't own.
+
+## Quick start
+
+```bash
+npx break-anything setup
+```
+
+Pick your agent, approve the changes, restart. Works with Claude Code, Codex, Cursor, Gemini CLI,
+Windsurf, and anything that runs a local MCP server. Then just ask:
+
+```text
+Use Break Anything on this project. Show me only the vulnerabilities that are
+actually reachable in my code, prove the worst one, and give me the fix.
+```
+
+Prefer the terminal? One command, shipped today:
+
+```bash
+npx -y break-anything deps ./              # dependency CVEs, ranked by reachability + EPSS
+npx -y break-anything secrets ./ --history # leaked keys in the tree and full git history
+npx -y break-anything image my-svc:latest  # OS + app CVEs in a container image
+npx -y break-anything sast ./src           # static code analysis (injection, authz, SSRF…)
+```
+
+## Why it's different
+
+Every scanner can hand you a list. The list is the problem. Break Anything is built around the
+three things a list can't do:
+
+- **Reachability — it thinks like an attacker.** An attacker doesn't work through 400 theoretical
+  CVEs; they go straight for the few they can actually reach. Break Anything does the same:
+  `confirmed` → `reachable` → `present` → `not-reachable`. The vulnerable `lodash` you never call
+  is noise; the one on a live code path is the finding. You triage 3, not 400.
+- **Proof, not prose.** Instead of a CVSS paragraph, it builds a proof-of-concept against *your*
+  build — the exact input or request that breaks it — so "theoretically vulnerable" becomes
+  "here's the repro."
+- **A fix, even when upstream is gone.** No patched version because the maintainer vanished? It
+  proposes a patch, a pin, a compatibility shim, or a maintained fork — so an abandoned dependency
+  doesn't become your breach. Hand it to [Patch Anything](#companion-patch-anything) for a
+  merge-ready PR.
+
+It doesn't replace OSV, Trivy, Semgrep or ZAP — it **orchestrates** them behind one agent
+interface and does the reasoning they can't.
+
+## See it in 30 seconds
+
+Three things you'll reach for it, each one sentence to your agent:
+
+| The moment | Ask | What you get back |
+| --- | --- | --- |
+| **"A CVE is trending — are we hit?"** | *"Scan my deps, only flag what's reachable."* | 3 reachable CVEs with fix versions — not a 400-line wall |
+| **"Did someone commit a key?"** | *"Scan the repo and git history for secrets."* | The leaked key, the commit that introduced it, "rotate don't delete" |
+| **"Can user A read user B's data?"** | *"Check /orders/:id for broken access control."* | The IDOR, proven against localhost with two accounts |
+
+## What you point it at
+
+You don't pick a mode. Hand it whatever you have — it detects the form and routes to the right
+engine.
+
+| You give it | Form | Categories |
+| --- | --- | --- |
+| A repo or source tree | source / tech stack | SCA, SAST, Secrets |
+| A lockfile (`package-lock.json`, `composer.lock`, `go.mod`…) | manifest | SCA |
+| A container image | build artifact | Containers |
+| An APK / IPA or compiled binary | build artifact | Mobile, Fuzzing |
+| A Terraform / Kubernetes / Dockerfile | config | IaC |
+| A running URL or API (yours) | live system | DAST, API |
+| Cloud credentials (yours) | live account | Cloud posture |
+| Git history | repo metadata | Secrets |
+
+## The arsenal
+
+Organized by scan category — the language security teams speak — each orchestrating tools that
+already run in real pipelines. ✅ shipped in 0.1.0 · 🧭 on the roadmap.
+
+### ✅ Shipped today
+
+- **Dependencies (SCA)** — known CVEs across your whole tree, ranked by reachability + EPSS, with fix versions. Engines: [OSV](https://osv.dev), [Trivy](https://github.com/aquasecurity/trivy), [Grype](https://github.com/anchore/grype), `pip-audit`, `govulncheck`, `composer audit`. Ecosystems: npm, PyPI, Composer, Go, Maven, Cargo, RubyGems, NuGet.
+- **Secrets** — leaked keys/tokens/private keys in the working tree and full git history, redacted. Engines: [Gitleaks](https://github.com/gitleaks/gitleaks), [TruffleHog](https://github.com/trufflesecurity/trufflehog).
+- **Container images** — OS + app CVEs, Dockerfile smells, secrets in layers. Engines: [Trivy](https://github.com/aquasecurity/trivy), [Grype](https://github.com/anchore/grype), [Hadolint](https://github.com/hadolint/hadolint).
+- **Static code (SAST)** — injection, broken access control, insecure deserialization, SSRF, hardcoded secrets — each with file/line, CWE/OWASP tags, and the offending snippet. Engine: [Semgrep](https://semgrep.dev).
+
+### 🧭 On the roadmap
+
+- **More SAST engines** — [CodeQL](https://codeql.github.com), SonarQube CE, Bandit (Python), gosec (Go), Brakeman (Rails), Find-Sec-Bugs (Java), security-code-scan (.NET), retire.js (frontend JS).
+- **Infrastructure & Kubernetes (IaC)** — public buckets, open ports, over-broad IAM, misconfigured clusters — before `apply`. [Checkov](https://www.checkov.io), tfsec, Terrascan, [KICS](https://kics.io), [Kubescape](https://github.com/kubescape/kubescape), kube-bench, [Falco](https://falco.org) (runtime).
+- **Running apps & attack surface (DAST)** — OWASP Top 10, content/parameter discovery, XSS, injection against your authorized app. [OWASP ZAP](https://www.zaproxy.org), [Nuclei](https://github.com/projectdiscovery/nuclei), [Nikto](https://github.com/sullo/nikto), [ffuf](https://github.com/ffuf/ffuf), [Katana](https://github.com/projectdiscovery/katana), [Dalfox](https://github.com/hahwul/dalfox), [sqlmap](https://sqlmap.org); surface mapping via [Nmap](https://nmap.org) + [Amass](https://github.com/owasp-amass/amass) + ProjectDiscovery.
+- **API** — BOLA/IDOR, broken auth, mass assignment (OWASP API Top 10). [Schemathesis](https://github.com/schemathesis/schemathesis), ZAP.
+- **Offensive / exploitation** — *authorized pentest only; gated, off by default, written permission required.* Prove exploitability on targets you own. [Metasploit](https://www.metasploit.com), sqlmap, [Hydra](https://github.com/vanhauser-thc/thc-hydra), [Hashcat](https://hashcat.net), [BloodHound](https://github.com/SpecterOps/BloodHound) + Impacket (Active Directory), [OpenVAS](https://www.openvas.org).
+- **AI / LLM security** — prompt injection, jailbreaks, data leakage in your own models and agents. [Garak](https://github.com/NVIDIA/garak).
+- **Binary & artifact analysis** — known-vulnerable deps and unsafe patterns in compiled binaries. [Ghidra](https://ghidra-sre.org), [radare2](https://github.com/radareorg/radare2), [angr](https://github.com/angr/angr) (pairs with REA).
+- **Cloud posture · Smart contracts · Mobile · Fuzzing** — [Prowler](https://github.com/prowler-cloud/prowler) · [Slither](https://github.com/crytic/slither), Mythril, Echidna · [MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF) · [AFL++](https://github.com/AFLplusplus/AFLplusplus), libFuzzer, Jazzer.
+
+Full per-tool catalog and MCP contracts: [docs/mcp-tools.md](docs/mcp-tools.md). Every dynamic
+(traffic-sending) category is **off by default** and refuses any target not on your allowlist.
+
+## How it works
+
+Your agent calls Break Anything over MCP to inspect a target you control. It routes to the right
+engine, confirms reachability, and returns each finding with its evidence and a fix. The CLI uses
+the same workflows.
+
+![Find, prove, fix flow](docs/assets/break-flow.svg)
+
+**Find** weaknesses across deps, code, secrets, images, IaC, and running apps → **Prove** the
+finding is reachable with a PoC against your target → **Fix** it inline or via Patch Anything.
+Absence of a finding is never reported as proof of safety.
+
+## Companion: Patch Anything
+
+> **Break Anything** finds it and proves it → **[Patch Anything](https://github.com/EnkiHQ/patch-anything)** fixes it.
+
+Hand any finding over and it drafts the patch, bump, shim, or fork. Discovery and repair, one
+loop. Use either alone, or run it end to end.
+
+## FAQ
+
+<details>
+<summary><strong>How is this different from `npm audit` / Trivy / Snyk?</strong></summary>
+
+They report presence — every vulnerability that exists anywhere in your tree. Break Anything adds
+**reachability** (is it actually called), **proof** (a PoC against your own build), and
+**self-remediation** when upstream has no fix, and unifies deps, code, secrets, images, IaC, and
+runtime behind one agent interface.
+
+</details>
+
+<details>
+<summary><strong>Does it replace those tools?</strong></summary>
+
+No — it orchestrates them. Break Anything is the brain and the interface; OSV, Trivy, Semgrep, ZAP
+are the engines. You get their depth without learning each one.
+
+</details>
+
+<details>
+<summary><strong>Is this an attack tool? Will my repo get taken down?</strong></summary>
+
+No. It's defensive and authorized-targets-only; every PoC runs against your own target and it
+ships no weaponized exploits. See [DISCLAIMER.md](DISCLAIMER.md). GitHub policy explicitly supports
+dual-use security research.
+
+</details>
+
+<details>
+<summary><strong>Does it upload my code?</strong></summary>
+
+Analysis runs locally. Your agent receives the results; its model provider has its own data
+policy — review that separately.
+
+</details>
+
+<details>
+<summary><strong>Which agents can use it?</strong></summary>
+
+Any agent that supports local MCP servers. Setup configures the common ones automatically.
+
+</details>
+
+## Documentation
+
+[Installation](docs/installation.md) · [Tool catalog & MCP contracts](docs/mcp-tools.md) ·
+[Roadmap](docs/roadmap.md) · [Security model](SECURITY.md) · [Responsible use](DISCLAIMER.md)
+
+## License
+
+[MIT](LICENSE). Break-authored code is MIT; the engines it orchestrates keep their own licenses —
+see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/bin/brk.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { scanDependencies } from "../src/scan.js";
+import { renderHuman } from "../src/report.js";
+
+const VERSION = "0.2.0";
+
+const HELP = `Break Anything (brk) v${VERSION}
+点你的 Agent 指向你拥有或已授权的软件,找到漏洞、证明它、修好它。
+
+用法:
+  brk deps [path]        扫描依赖 lockfile 的已知漏洞(默认当前目录)
+  brk secrets [path]     扫描泄露的密钥(工作区,--history 加扫 git 历史)
+  brk image <ref>        扫描容器镜像的已知漏洞(需 trivy)
+  brk sast [path]        静态代码分析找漏洞(需 semgrep)
+  brk mcp                以 MCP server 模式启动(供 Agent 调用)
+  brk doctor             检查运行环境与网络连通性
+  brk setup              打印把 Break Anything 接入 Agent 的 MCP 配置
+  brk --help             显示本帮助
+  brk --version          显示版本
+
+通用选项:
+  --json                 输出 JSON(用于脚本 / Agent)
+  --no-color             关闭彩色输出
+deps 选项:
+  --no-reachability      跳过源码可达性初判
+secrets 选项:
+  --history              加扫 git 历史中的密钥
+
+范围声明:只对你拥有、或已获得明确授权的目标使用。详见 DISCLAIMER.md。
+`;
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (const a of argv) {
+    if (a === "--json") flags.json = true;
+    else if (a === "--no-reachability") flags.reachability = false;
+    else if (a === "--no-color") flags.color = false;
+    else if (a.startsWith("--") && a.includes("=")) { const [k, v] = a.slice(2).split("="); flags[k] = v; }
+    else if (a.startsWith("--")) flags[a.slice(2)] = true;
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (cmd === "--version" || cmd === "-v") {
+    process.stdout.write(VERSION + "\n");
+    return;
+  }
+
+  if (cmd === "mcp") {
+    const { startMcpServer } = await import("../src/mcp.js");
+    await startMcpServer();
+    return; // 保持进程存活
+  }
+
+  if (cmd === "deps") {
+    const { flags, positional } = parseFlags(rest);
+    const target = positional[0] || process.cwd();
+    const result = await scanDependencies(target, {
+      reachability: flags.reachability !== false,
+    });
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      const color = flags.color !== false && process.stdout.isTTY;
+      process.stdout.write(renderHuman(result, { color, top: flags.top ? Number(flags.top) : undefined }) + "\n");
+    }
+    // 有高危且可达的发现时用非零退出码,方便接 CI
+    const hasReachableHigh = result.findings?.some(
+      (f) => f.reachability === "imported" && (f.severity === "CRITICAL" || f.severity === "HIGH"),
+    );
+    process.exitCode = hasReachableHigh ? 1 : 0;
+    return;
+  }
+
+  if (cmd === "secrets") {
+    const { flags, positional } = parseFlags(rest);
+    const target = positional[0] || process.cwd();
+    const { scanSecrets } = await import("../src/secrets.js");
+    const { renderSecrets } = await import("../src/report.js");
+    const result = await scanSecrets(target, { history: !!flags.history });
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      const color = flags.color !== false && process.stdout.isTTY;
+      process.stdout.write(renderSecrets(result, { color }) + "\n");
+    }
+    process.exitCode = result.findings.length ? 1 : 0;
+    return;
+  }
+
+  if (cmd === "image") {
+    const { flags, positional } = parseFlags(rest);
+    const ref = positional[0];
+    if (!ref) {
+      process.stderr.write("用法:brk image <镜像引用>,例如 brk image nginx:1.21\n");
+      process.exitCode = 2;
+      return;
+    }
+    const { scanImage } = await import("../src/image.js");
+    const { renderImage } = await import("../src/report.js");
+    const result = await scanImage(ref);
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      const color = flags.color !== false && process.stdout.isTTY;
+      process.stdout.write(renderImage(result, { color }) + "\n");
+    }
+    const hasHigh = result.findings?.some((f) => f.severity === "CRITICAL" || f.severity === "HIGH");
+    process.exitCode = hasHigh ? 1 : 0;
+    return;
+  }
+
+  if (cmd === "sast") {
+    const { flags, positional } = parseFlags(rest);
+    const target = positional[0] || process.cwd();
+    const { scanSast } = await import("../src/sast.js");
+    const { renderSast } = await import("../src/report.js");
+    const result = await scanSast(target, flags.config ? { config: flags.config } : {});
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      const color = flags.color !== false && process.stdout.isTTY;
+      process.stdout.write(renderSast(result, { color, top: flags.top ? Number(flags.top) : undefined }) + "\n");
+    }
+    const hasHigh = result.findings?.some((f) => f.severity === "CRITICAL" || f.severity === "HIGH");
+    process.exitCode = hasHigh ? 1 : 0;
+    return;
+  }
+
+  if (cmd === "doctor") {
+    await doctor();
+    return;
+  }
+
+  if (cmd === "setup") {
+    printSetup();
+    return;
+  }
+
+  process.stderr.write(`未知命令:${cmd}\n\n${HELP}`);
+  process.exitCode = 2;
+}
+
+async function doctor() {
+  const out = [];
+  const [maj] = process.versions.node.split(".").map(Number);
+  out.push(`Node.js ${process.versions.node} ${maj >= 18 ? "✓" : "✗ 需要 >= 18.17"}`);
+  try {
+    const { fetchJson } = await import("../src/http.js");
+    await fetchJson("https://api.osv.dev/v1/query", {
+      method: "POST",
+      body: { version: "4.17.4", package: { name: "lodash", ecosystem: "npm" } },
+      timeoutMs: 8000,
+    });
+    out.push("OSV API 可达 ✓");
+  } catch (e) {
+    out.push(`OSV API 不可达 ✗ (${e instanceof Error ? e.message : e})`);
+  }
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+function printSetup() {
+  const config = {
+    mcpServers: {
+      "break-anything": { command: "npx", args: ["-y", "break-anything", "mcp"] },
+    },
+  };
+  process.stdout.write(
+    "把下面的配置加入你的 MCP 客户端(Claude Code / Cursor / Codex 等):\n\n" +
+      JSON.stringify(config, null, 2) +
+      "\n\n然后重启 Agent,对它说:用 Break Anything 扫描我的项目依赖。\n",
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`错误:${err instanceof Error ? err.stack || err.message : String(err)}\n`);
+  process.exitCode = 1;
+});

package/docs/assets/break-flow.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1180 360" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#8b93a7"/>
+    </marker>
+    <style>
+      .box{rx:12;ry:12;stroke-width:1.5;}
+      .t{fill:#0f1222;font-size:15px;font-weight:600;}
+      .s{fill:#5b6478;font-size:12px;}
+      .lbl{fill:#8b93a7;font-size:11px;}
+    </style>
+  </defs>
+
+  <rect x="24" y="140" width="180" height="80" class="box" fill="#eef1fb" stroke="#5c4ee5"/>
+  <text x="114" y="172" text-anchor="middle" class="t">Coding agent</text>
+  <text x="114" y="194" text-anchor="middle" class="s">or your terminal</text>
+
+  <line x1="204" y1="180" x2="300" y2="180" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="304" y="130" width="200" height="100" class="box" fill="#f4f6fd" stroke="#5c4ee5"/>
+  <text x="404" y="166" text-anchor="middle" class="t">Break Anything</text>
+  <text x="404" y="188" text-anchor="middle" class="s">CLI + MCP</text>
+  <text x="404" y="208" text-anchor="middle" class="s">capability router</text>
+
+  <line x1="504" y1="180" x2="600" y2="180" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="604" y="40" width="200" height="56" class="box" fill="#fff" stroke="#c7ccda"/>
+  <text x="704" y="66" text-anchor="middle" class="t">Dependencies</text>
+  <text x="704" y="84" text-anchor="middle" class="lbl">OSV · GHSA · EPSS · KEV</text>
+
+  <rect x="604" y="110" width="200" height="56" class="box" fill="#fff" stroke="#c7ccda"/>
+  <text x="704" y="136" text-anchor="middle" class="t">Source (SAST)</text>
+  <text x="704" y="154" text-anchor="middle" class="lbl">Semgrep · CodeQL · gitleaks</text>
+
+  <rect x="604" y="180" width="200" height="56" class="box" fill="#fff" stroke="#c7ccda"/>
+  <text x="704" y="206" text-anchor="middle" class="t">Running app (DAST)</text>
+  <text x="704" y="224" text-anchor="middle" class="lbl">ZAP · Nuclei · API tests</text>
+
+  <rect x="604" y="250" width="200" height="56" class="box" fill="#fff" stroke="#c7ccda"/>
+  <text x="704" y="276" text-anchor="middle" class="t">Images · IaC</text>
+  <text x="704" y="294" text-anchor="middle" class="lbl">Trivy · Grype · checkov</text>
+
+  <line x1="804" y1="68" x2="900" y2="150" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <line x1="804" y1="138" x2="900" y2="168" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <line x1="804" y1="208" x2="900" y2="190" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <line x1="804" y1="278" x2="900" y2="210" stroke="#8b93a7" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="904" y="130" width="250" height="100" class="box" fill="#eafaf0" stroke="#1f9d57"/>
+  <text x="1029" y="162" text-anchor="middle" class="t">Findings + evidence</text>
+  <text x="1029" y="184" text-anchor="middle" class="s">reachability · PoC on your target</text>
+  <text x="1029" y="206" text-anchor="middle" class="s">→ fix plan / Patch Anything</text>
+
+  <text x="590" y="332" text-anchor="middle" class="lbl">Authorized targets only — software you own or are explicitly permitted to test</text>
+</svg>

package/docs/hero-gif.md

@@ -0,0 +1,51 @@
+# Hero GIF — how it's made
+
+The README's first image. Short (~12s), tight, cool, real tool output. Generated with
+[VHS](https://github.com/charmbracelet/vhs) from a repeatable script.
+
+## What it shows
+
+Two beats:
+
+1. **Dependencies** — `brk deps` plays a quick scanning animation, then snaps the real top
+   findings for an old `lodash`/`minimist`: two CRITICALs + a HIGH at 21.3% EPSS, each tagged
+   `reachable`, with fix versions, over a bold `12 findings · 10 reachable` summary.
+2. **Secrets** — `brk secrets --history` finds an AWS key removed from the code but still in git
+   history, pinned to the commit, with the "rotate, don't just delete" warning.
+
+Outro: `# find -> prove -> fix    npx break-anything`.
+
+## Why the deps output is pre-captured
+
+The `deps` scan hits the OSV network, which adds several seconds of dead air to a recording. So
+the real colored output is captured once, off-camera, and replayed instantly behind a scanning
+animation — the data is genuine, the GIF stays tight.
+
+Re-capture it (real, colored, top 3) any time:
+
+```bash
+script -q demos/.hero/deps.ansi node bin/brk.js deps demos/sample-npm --top=3
+```
+
+`demos/hero-brk.sh` is the tape's `brk` wrapper: it animates + replays that file for `deps`, and
+runs the real CLI for everything else (`secrets` is local and instant, so it runs live).
+
+## Re-render
+
+```bash
+brew install vhs       # once
+vhs demos/hero.tape    # writes docs/assets/hero.gif
+```
+
+## Tuning
+
+- **Look:** `Set Theme / FontSize / Width / Height / WindowBar / MarginFill / BorderRadius` at the
+  top of [`demos/hero.tape`](../demos/hero.tape).
+- **Findings shown:** `--top=N` in the capture command (and the real CLI).
+- **Avoid `→` in `Type` lines** — VHS can drop the multibyte arrow; use `->`. Arrows inside the
+  captured `deps.ansi` render fine.
+
+## Guardrails
+
+- Every target is a sample project or a throwaway repo you own — never a third party.
+- The CVEs and EPSS numbers are real (captured from a live OSV / FIRST.org scan). Don't fake them.

package/docs/installation.md

@@ -0,0 +1,73 @@
+# Installation and setup
+
+## Requirements
+
+- Node.js 22.19+ and npm
+- macOS, Linux, or Windows (WSL recommended on Windows for dynamic tools)
+- Optional analysis engines depending on the target (see below)
+
+## Set up your agent
+
+```bash
+npx break-anything setup
+```
+
+Setup detects installed agents, prints every proposed change, backs up existing configuration,
+and asks before applying anything. Supported agents:
+
+- Claude Code
+- Claude Desktop
+- Codex
+- Cursor
+- Gemini CLI
+- Windsurf
+
+Any other client that can run a local MCP server can use the
+[manual registration](mcp-tools.md#manual-mcp-registration).
+
+## Install the CLI
+
+```bash
+npm install --global break-anything
+brk --help
+brk doctor
+```
+
+`brk doctor` is read-only. It reports which optional engines are present and which capabilities
+are therefore available.
+
+## Optional analysis engines
+
+Break Anything orchestrates tools you already trust. It does not bundle or re-license them.
+
+| Capability | Engine | Install |
+| --- | --- | --- |
+| Dependency CVEs | OSV database | built-in (queries OSV.dev) |
+| SAST | Semgrep | `pipx install semgrep` |
+| SAST (deep) | CodeQL | CodeQL CLI from GitHub |
+| Secrets | gitleaks | `brew install gitleaks` |
+| Images / IaC | Trivy | `brew install trivy` |
+| Images (second opinion) | Grype | `brew install grype` |
+| Dynamic web | OWASP ZAP | ZAP desktop or `zaproxy` |
+| Templates | Nuclei | `brew install nuclei` |
+| Smart contracts | Slither | `pipx install slither-analyzer` |
+
+## Enable dynamic (running-app) capabilities
+
+Dynamic tools are off by default. To test your own running app or API:
+
+```bash
+export BRK_DYNAMIC_ENABLED=true
+export BRK_AUTHORIZED_TARGETS_JSON='["http://localhost:3000"]'
+```
+
+Dynamic tools refuse any target not in the allowlist. See [DISCLAIMER.md](../DISCLAIMER.md).
+
+## Uninstall
+
+```bash
+brk uninstall          # remove MCP registrations + managed skill
+brk uninstall --purge  # also remove ~/.brk cache and state
+```
+
+Uninstall preserves your other MCP servers, your installed engines, and your evidence bundles.