break-anything 0.0.0-stage → 0.1.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,252 @@
-# 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
+
+### One MCP for finding vulnerabilities across code, dependencies, apps, and infrastructure.
+
+**Break it before they do. Point your agent at software you own, find the weakness, prove it, fix it.**
+
+[![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) · [How it works](#how-break-anything-works) · [What you can test](#what-you-can-test) · [Showcases](#showcases) · [FAQ](#faq) · [Companion: Patch Anything](#companion-patch-anything)**
+
+<code>npx break-anything setup</code>
+
+</div>
+
+> [!IMPORTANT]
+> Break Anything finds weaknesses in software **you own or are explicitly authorized to test**.
+> It is a defensive, white-box security tool: every finding comes with evidence and a
+> remediation path, and every proof-of-concept runs against your own target.
+> It is not an attack framework and must not be pointed at third-party systems.
+
+> [!WARNING]
+> Get Break Anything only from the official sources listed in this README and in the
+> `break-anything` npm package. A similar repository name or a copied README does not
+> make a download official.
+
+<div align="center">
+
+<!-- Record with: asciinema rec hero.cast -c "bash demos/hero-demo.sh" && agg hero.cast docs/assets/hero.gif -->
+<img src="docs/assets/hero.gif" alt="Break Anything finding reachable CVEs and a secret buried in git history" width="900" />
+
+</div>
+
+---
+
+See a vulnerability land in the news and wonder whether *your* project is exposed? Ask your agent
+to check it with Break Anything. It inspects your code, dependencies, running app, and
+infrastructure without you learning ten different scanners, explains **where** you are
+vulnerable, proves it with a reproducible finding, and hands a fix plan to your agent — or to
+[Patch Anything](#companion-patch-anything).
+
+Break Anything connects your coding agent to mature security tooling (Semgrep, CodeQL, OSV,
+Trivy, Grype, Nuclei, ZAP, gitleaks, and more) through one consistent interface. You can also
+run the same capabilities from your terminal. Analysis runs locally, and every result carries
+the evidence, the exploitability signal, and the limitations behind it.
+
+Most scanners stop at "here is a CVE list, bump the version." Break Anything goes further: it
+reasons about whether a finding is **actually reachable in your usage**, builds a
+proof-of-concept against **your own** target, and — when upstream has no fix — proposes a patch,
+a shim, or a mitigation so an abandoned dependency does not become your breach.
+
+## Quick start
+
+### Set up your agent
+
+With Node.js and npm installed, run:
+
+```bash
+npx break-anything setup
+```
+
+Choose your agents, review the proposed changes, and approve them. Setup registers Break
+Anything's MCP server and installs matching workflow instructions, with backups of existing
+configuration. Restart your agent afterward.
+
+Setup supports Claude Code, Codex, Cursor, Gemini CLI, Windsurf, and any client that can run a
+local MCP server. See [installation](docs/installation.md) for manual registration.
+
+### Ask your agent
+
+```text
+Use Break Anything to check my project for vulnerabilities. Prioritise anything
+that is actually reachable in my code, prove it against my local build, and give
+me a fix plan.
+```
+
+Replace the request with your target — a repository, a lockfile, a running localhost app, a
+container image, or a Terraform directory.
+
+### Use the terminal
+
+```bash
+# Dependencies: known CVEs ranked by reachability + EPSS, with fix versions
+npx -y break-anything deps ./
+
+# Secrets: leaked keys in the working tree and (with --history) git history
+npx -y break-anything secrets ./ --history
+
+# Container image: OS + app CVEs via Trivy
+npx -y break-anything image my-service:latest
+```
+
+> Shipped today: `deps`, `secrets`, `image`, and the matching MCP tools. The rest of the
+> [tool catalog](docs/mcp-tools.md) is the roadmap, landing incrementally.
+
+To install the `brk` command for regular use:
+
+```bash
+npm install --global break-anything
+brk --help
+```
+
+> The CLI command is `brk` (not `break`, which is a shell keyword).
+
+### Update
+
+```bash
+brk update
+```
+
+## How Break Anything works
+
+Your agent calls Break Anything through MCP to inspect a target you control. Break Anything
+returns each finding with its evidence, an exploitability signal, and a suggested remediation.
+The agent uses that to prioritise, reproduce, and fix. CLI commands use the same workflows.
+
+![Break Anything flow: your agent points at an authorized target; Break Anything routes to the right analysis engine, confirms reachability, and returns findings with evidence and a fix plan.](docs/assets/break-flow.svg)
+
+The investigation model:
+
+| Stage | What happens |
+| --- | --- |
+| **Find** | Enumerate weaknesses across dependencies, source, running app, and infrastructure. |
+| **Prove** | Confirm the finding is reachable in your usage and build a proof-of-concept against *your* target. |
+| **Fix** | Produce a patch, pin, shim, or mitigation — directly, or by handing off to Patch Anything. |
+
+Break Anything shows how it reached each conclusion. It separates "confirmed exploitable",
+"reachable but unproven", and "present but not reachable" instead of drowning you in noise.
+
+## What you can test
+
+| Target | What Break Anything returns | Requirements |
+| --- | --- | --- |
+| Dependency manifests | Known CVEs across `package-lock`, `requirements.txt`, `go.mod`, `composer.lock`, `pom.xml`, `Cargo.toml`; EPSS exploit probability; CISA KEV status; fix versions; call-path reachability | OSV / GHSA (built-in); reachability uses local source |
+| Source code | Injection, broken access control, insecure deserialization, path traversal, SSRF, hardcoded secrets — with data-flow evidence | Semgrep / CodeQL rulepacks |
+| Secrets in repo + git history | Exposed API keys, tokens, private keys, and where they leaked | gitleaks / trufflehog style scan |
+| Running web app (your host) | OWASP Top 10 dynamic findings against an authorized localhost or staging target | A Chrome-family browser; OWASP ZAP |
+| HTTP APIs (your host) | Broken access control, IDOR, auth bypass, mass assignment — with a reproducible request | Authorized base URL + credentials |
+| Container images | OS and application-layer CVEs, misconfigurations, exposed secrets in layers | Trivy / Grype |
+| Dockerfile / IaC | Misconfigurations in Dockerfile, Terraform, Kubernetes, CloudFormation | Trivy / checkov rulepacks |
+| Web frontend bundles | Vulnerable JS libraries and secrets shipped to the browser | Node.js + npm |
+| Compiled artifacts | Known-vulnerable bundled dependencies and memory-safety smells | Static inspection |
+| Smart contracts (optional) | Reentrancy, integer overflow, access-control gaps in Solidity | Slither |
+
+Every dynamic capability is **disabled by default** and requires both an operator policy and an
+explicit per-run authorization flag. Static inspection reads your files without running them.
+
+## Showcases
+
+Ten worked demos — **all on targets you own, open-source projects, or deliberately vulnerable
+labs**. See [`demos/`](demos/) for the full scripts.
+
+1. **OWASP Juice Shop** — point at the authorized lab, find an IDOR, prove it with a request, explain the fix.
+2. **The dependency you forgot** — an old `lodash`/`minimist` in your lockfile: find it, confirm the vulnerable function is actually called, get the fix version.
+3. **PHP supply chain after php2shell** — a PHP project pinned to a vulnerable `composer` dependency: Break Anything maps your whole dependency chain so the *next* php2shell does not catch you blind.
+4. **Log4Shell lab** — a Java service with a vulnerable `log4j`: confirm reachability through your logging path, not just presence.
+5. **Leaked key** — a test repo with an AWS key committed three months ago: find it in history, show the blast radius.
+6. **Vulnerable base image** — a `Dockerfile` on an outdated base: list OS + app CVEs and the minimal bump.
+7. **Public bucket** — a Terraform file that makes an S3 bucket world-readable: catch it before `apply`.
+8. **Your own Express API** — an IDOR on `/orders/:id`: prove it against localhost with two accounts.
+9. **Reentrancy** — a Solidity contract in a lab: trace the external call before the state update.
+10. **Find → Fix handoff** — hand any finding above to [Patch Anything](#companion-patch-anything) and watch the fix PR get drafted.
+
+If you break something interesting (that you are allowed to break), open an issue or PR with the
+target, your question, and what you found.
+
+## Companion: Patch Anything
+
+Break Anything and [Patch Anything](https://github.com/PatchAnything/patch-anything) are built to
+work as a pair:
+
+> **Break Anything** finds it and proves it → **Patch Anything** fixes it.
+
+When Break Anything surfaces a finding, your agent can hand it straight to Patch Anything, which
+generates a patch, a dependency bump, a compatibility shim, or — when upstream is dead — a
+maintained fork or local mitigation. One is offense-flavoured discovery; the other is defensive
+repair. Use either alone, or run the loop end to end.
+
+## FAQ
+
+<details>
+<summary><strong>Is this an attack tool? Will it get my repo taken down?</strong></summary>
+
+No. Break Anything is a defensive, white-box tool for software you own or are authorized to
+test. Every proof-of-concept runs against your own target; it ships no weaponized exploits for
+third-party systems. See [DISCLAIMER.md](DISCLAIMER.md). GitHub's policy explicitly supports
+dual-use security research.
+
+</details>
+
+<details>
+<summary><strong>How is this different from `npm audit` / Trivy / Snyk?</strong></summary>
+
+Those report presence. Break Anything adds **reachability** (is the vulnerable code actually
+called in your project), **proof** (a PoC against your own build), and **self-remediation** when
+upstream has no fix. It also unifies dependency, source, runtime, and infrastructure findings
+behind one agent interface.
+
+</details>
+
+<details>
+<summary><strong>Which agents can use it?</strong></summary>
+
+Any agent that supports local MCP servers. Setup configures the common ones automatically;
+others can use manual MCP registration.
+
+</details>
+
+<details>
+<summary><strong>Does it upload my code?</strong></summary>
+
+Analysis runs locally. Your agent receives the tool results, and its model provider has its own
+data policy — review that separately.
+
+</details>
+
+<details>
+<summary><strong>Can it test a site I do not own?</strong></summary>
+
+No. Dynamic capabilities require an explicit authorization flag and are intended for your own or
+contractually authorized targets. Testing systems without authorization is illegal and
+unsupported.
+
+</details>
+
+## Documentation
+
+- [Installation and setup](docs/installation.md)
+- [MCP tool catalog](docs/mcp-tools.md)
+- [Security model](SECURITY.md)
+- [Responsible use](DISCLAIMER.md)
+
+## Disclaimer
+
+Break Anything is for lawful security research, education, and testing of software you own or are
+authorized to examine. See [DISCLAIMER.md](DISCLAIMER.md) for responsible-use guidance. You are
+responsible for using this software in compliance with all applicable laws and the terms of any
+third-party tool it orchestrates.
+
+## License
+
+[MIT](LICENSE)
+
+Break-authored code is licensed under MIT. Third-party tools it orchestrates (Semgrep, CodeQL,
+Trivy, Grype, Nuclei, ZAP, and others) retain their own licenses; you must obtain and use them
+under their applicable terms.

package/bin/brk.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { scanDependencies } from "../src/scan.js";
+import { renderHuman } from "../src/report.js";
+
+const VERSION = "0.1.0";
+
+const HELP = `Break Anything (brk) v${VERSION}
+点你的 Agent 指向你拥有或已授权的软件,找到漏洞、证明它、修好它。
+
+用法:
+  brk deps [path]        扫描依赖 lockfile 的已知漏洞(默认当前目录)
+  brk secrets [path]     扫描泄露的密钥(工作区,--history 加扫 git 历史)
+  brk image <ref>        扫描容器镜像的已知漏洞(需 trivy)
+  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("--")) 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 }) + "\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 === "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,53 @@
+# Hero GIF — recording recipe
+
+The single most important launch asset. 25–35 seconds, no narration, the README's first image.
+
+## What it shows
+
+The runnable script [`demos/hero-demo.sh`](../demos/hero-demo.sh) produces three beats, all on
+targets you own:
+
+1. **The forgotten dependency** — `cat` a `package.json` pinned to an old `lodash`.
+2. **The scan** — `brk deps` returns real CVEs ranked so the *reachable* criticals rise to the
+   top. Not a 400-line wall; the few that matter.
+3. **The buried secret** — `brk secrets --history` finds an AWS key that was deleted from the
+   code but is still sitting in git history, pinned to the commit.
+
+Ending card: `Find → Prove → Fix. npx break-anything`.
+
+## Record it
+
+Install the tools once:
+
+```bash
+brew install asciinema agg      # macOS; agg turns the cast into a GIF
+```
+
+Record and convert:
+
+```bash
+cd /path/to/break-anything
+asciinema rec hero.cast -c "bash demos/hero-demo.sh"
+agg --font-size 22 --theme monokai hero.cast docs/assets/hero.gif
+```
+
+Then reference it at the top of the README:
+
+```markdown
+<img src="docs/assets/hero.gif" alt="Break Anything finding reachable CVEs and a secret buried in git history" width="900" />
+```
+
+## Tips for a GIF that spreads
+
+- Keep the terminal ~90 columns, large font. People watch these on phones.
+- Trim to under 35s. The `deps` result and the "deleted but still in history" reveal are the two
+  moments that make people stop scrolling — land them fast.
+- Do not show a cursor hunting around. The script paces itself; just let it run.
+- Record on a clean prompt, dark theme, no personal paths visible (the script uses a temp dir).
+- Post the GIF in the README, the Show HN, and the X thread. Same asset everywhere.
+
+## Honesty guardrails (keep the credibility that makes it spread)
+
+- Every target in the GIF is a sample project or a throwaway repo you own. Never a third party.
+- The CVEs and EPSS numbers are real (live OSV / FIRST.org lookups), so the demo holds up when
+  someone reruns it. Do not fake the output.

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.