break-anything 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +126 -155
  2. package/bin/brk.js +21 -2
  3. package/docs/assets/hero.gif +0 -0
  4. package/docs/hero-gif.md +32 -34
  5. package/docs/launch.md +68 -80
  6. package/docs/mcp-tools.md +176 -33
  7. package/docs/readme/README_zh.md +89 -126
  8. package/docs/roadmap.md +51 -0
  9. package/package.json +5 -5
  10. package/src/http.js +1 -1
  11. package/src/mcp.js +21 -1
  12. package/src/report.js +141 -40
  13. package/src/sast.js +128 -0
package/docs/launch.md CHANGED
@@ -1,82 +1,70 @@
1
1
  # Launch kit
2
2
 
3
- Timing: publish Friday. Trending incubates over the weekend. Post the moment the hero GIF is
4
- ready, not before.
5
-
6
- ## The one-liner (use everywhere)
7
-
8
- > **Break Anything** — point your agent at code you own, find the weakness, prove it, fix it.
9
- > The REA for vulnerabilities.
10
-
11
- ## Slogans (pick one per channel)
12
-
13
- - Break it before they do.
14
- - Your agent now has a security team.
15
- - Find the bug. Prove the bug. Kill the bug.
16
- - After REA understood everything, Break Anything finds what's broken.
17
-
18
- ## Hero GIF (the single most important asset)
19
-
20
- 15–30 seconds, no narration:
21
-
22
- 1. Drag a repo (or type one prompt) into the agent.
23
- 2. Break Anything returns 3 findings — not 400 — each tagged `reachable`.
24
- 3. One finding expands into a proof request against localhost.
25
- 4. "Hand to Patch Anything" → a fix PR appears.
26
-
27
- Record demo 1 (Juice Shop) or demo 8 (your Express IDOR). Both run on targets you own.
28
-
29
- ## Hacker News (Show HN)
30
-
31
- Title: `Show HN: Break Anything – an MCP that finds, proves, and fixes vulns in your own code`
32
-
33
- Body (short, factual, no hype):
34
-
35
- > After REA wrapped reverse-engineering tools for agents, I wanted the same for AppSec. Break
36
- > Anything is one MCP server that gives your coding agent Semgrep, CodeQL, OSV, Trivy, ZAP and
37
- > friends behind one interface. The part I care about: it ranks findings by whether the
38
- > vulnerable code is actually reachable in your project, builds a PoC against your own build, and
39
- > — when upstream has no fix — proposes a patch or mitigation. Defensive only; dynamic scanning
40
- > is off by default and refuses targets not on your allowlist. Companion project Patch Anything
41
- > does the repair half. Feedback welcome, especially on the reachability engine.
42
-
43
- ## r/netsec / r/programming
44
-
45
- Lead with the reachability angle (that is what this crowd respects):
46
-
47
- > Most SCA tools report presence. Break Anything reports reachability + a PoC against your own
48
- > target, and handles the "upstream won't fix it" case. MCP server, works with Claude Code /
49
- > Cursor / Codex. Defensive, authorized-targets-only. Repo + 10 reproducible demos (all on labs
50
- > you own) inside.
51
-
52
- ## X / 即刻 thread
53
-
54
- 1/ php2shell reminded everyone: your stack breaks even when your code is clean.
55
- 2/ So I built Break Anything — point your agent at software you own, it finds what's broken,
56
- proves it, and fixes it.
57
- 3/ The trick isn't another scanner. It's reachability: 3 findings that matter, not 400 that
58
- don't. [GIF]
59
- 4/ Find → Prove → Fix. The fix half is a companion project, Patch Anything.
60
- 5/ Defensive only, authorized targets only, runs local. Repo + 10 demos ↓
61
-
62
- ## V2EX
63
-
64
- 标题:`给 AI Agent 配一个安全团队:Break Anything(攻破一切)`
65
-
66
- 正文:承接 php2shell 的话题,说清"不是又一个扫描器,卖点是可达性 + 对自己靶子的 PoC + 上游不修时的自救",
67
- 强调防御定位和"只打自己授权的目标",附仓库和 10 个自有靶场 demo。
68
-
69
- ## Cross-promotion with Patch Anything
70
-
71
- - Each README links the other in the first screen.
72
- - Ship them the same week; lead with Break (discovery is more viral), let it funnel stars to
73
- Patch.
74
- - Pinned issue in each repo: "Using Break + Patch together" with the demo 10 loop.
75
-
76
- ## Guardrails for the launch (do not skip)
77
-
78
- - README line 1 states authorized-targets-only. This is your takedown insurance.
79
- - Every demo and screenshot uses a lab or your own host. Never show popping a third party.
80
- - Do not accept PRs that add turnkey exploits for specific live targets.
81
- - Respond to "can it scan example.com?" with the authorization policy, publicly. It sets the tone
82
- and protects the project.
3
+ Research-backed. Sources: Show HN title formula ([signals.sh](https://signals.sh/blog/show-hn-title-formulas)),
4
+ star-spike patterns ([dev.to, 50 repos](https://dev.to/0012303/i-analyzed-50-github-repos-that-went-from-0-to-10k-stars-here-are-the-7-patterns-54o1)),
5
+ launch-day data ([arXiv 2511.04453](https://arxiv.org/abs/2511.04453)).
6
+
7
+ ## The one-liner (use everywhere, unchanged)
8
+
9
+ > **Break Anything** — you think your service is secure, but you've never looked at it the way an
10
+ > attacker would. Point your coding agent at code you own; it finds what's genuinely exploitable,
11
+ > proves it on your own build, and fixes it.
12
+
13
+ Rule: lead with the fear/pain, not the feature. The hook is the awareness gap ("you never actually
14
+ tested it"); the proof is reachability (an attacker only cares about what they can reach — so does
15
+ Break Anything).
16
+
17
+ ## Timing
18
+
19
+ Launch **Tuesday–Thursday, ~8–10am US Eastern**. Timing moves stars more than almost anything
20
+ else; the "Show HN" tag itself adds nothing after controlling for timing and content.
21
+
22
+ ## Hacker News (the multiplier — 87% of 10K-star repos start here)
23
+
24
+ **Title** (formula: `[Name] – [plain description]`; no caps, no `!`, no praise):
25
+
26
+ ```
27
+ Show HN: Break Anything – an MCP that audits your own code the way an attacker would
28
+ ```
29
+
30
+ **First comment** (this is where the story goes, not the title — personal story earns ~3× the
31
+ upvotes of a dry description):
32
+
33
+ > My app was "probably secure" — it shipped, it worked, nobody complained, so I never actually
34
+ > tested it. That's most software. I built Break Anything to close that gap: point your coding
35
+ > agent at code you own and it looks at it the way an attacker would. It's an MCP server + CLI
36
+ > that orchestrates OSV, Trivy, gitleaks (Semgrep/ZAP next), ranks findings by reachability + EPSS
37
+ > (an attacker only cares about what they can actually reach), builds a proof-of-concept against
38
+ > your own build, and — when upstream has no fix — proposes a patch. Defensive, local,
39
+ > authorized-targets-only. Companion project Patch Anything does the repair half. Honest about
40
+ > limits: reachability is today a heuristic (is it imported), not yet full call-path proof.
41
+ > Feedback welcome, especially on the reachability engine.
42
+
43
+ ## Cross-posts (same day → next day)
44
+
45
+ - **r/netsec, r/programming** — lead with the reachability angle: "most SCA reports presence; this
46
+ reports what's actually reachable + a PoC on your own target."
47
+ - **X / 即刻 thread** — beat 1: the 400-vs-3 pain. beat 2: the hero GIF. beat 3: find → prove →
48
+ fix. beat 4: companion Patch Anything. beat 5: repo + 10 demos.
49
+ - **V2EX / 掘金** — 直给、不绕:标题「`npm audit` 报你 47 个漏洞,到底哪 3 个能真打穿你?」正文讲
50
+ 可达性 + 自己靶子的 PoC + 上游不修时的自救,强调防御定位与「只打自己授权的目标」。
51
+ - **Awesome lists** — submit a one-line PR to the relevant awesome-security / awesome-devsecops
52
+ lists. These are GitHub's long-tail search engine (steady stars for months).
53
+
54
+ ## Hero GIF
55
+
56
+ The README's first asset. Current cut (`vhs demos/hero.tape`) tells the whole story in ~19s with
57
+ plain-language captions: *12 vulns here — which actually reach me?* → the reachable ones →
58
+ *a key I deleted is still in git* → *found, proven, fixed.* Keep it under ~20s. See
59
+ [hero-gif.md](hero-gif.md).
60
+
61
+ ## Guardrails (don't skip)
62
+
63
+ - **Never buy stars.** ~6M fake stars exist on GitHub and fake-star repos get flagged/banned;
64
+ a fake curve destroys the credibility a real launch builds.
65
+ - README line 1 is the pain, not the feature. Install command visible without scrolling.
66
+ - Every demo/screenshot uses a lab or your own host. Never a third party.
67
+ - Respond to every early issue within 24h — even just an acknowledgment. It converts drive-by
68
+ visitors into stargazers.
69
+ - Be honest about limits (reachability heuristic, roadmap vs shipped). Restraint reads as
70
+ credibility; overclaiming gets picked apart.
package/docs/mcp-tools.md CHANGED
@@ -1,32 +1,176 @@
1
- # MCP tool catalog
2
-
3
- Break Anything exposes one consistent MCP interface. The public interface describes *what the
4
- agent is trying to learn*; providers decide *how* to answer. Dynamic tools (those that send
5
- traffic to a target) are disabled until an operator policy enables them and a per-run
6
- authorization flag is passed.
7
-
8
- Counts below are a design target. **Shipped in 0.1.0: `deps_scan`** (the dependency & supply
9
- chain family — OSV lookup, reachability heuristic, EPSS enrichment, fix versions). The remaining
10
- families are on the roadmap and land incrementally; the catalog shows the intended shape, not
11
- what is already implemented.
12
-
13
- | Tool family | Count | Examples | Default |
14
- | --- | --- | --- | --- |
15
- | Dependency & supply chain | 9 | `deps.scan`, `deps.reachability`, `deps.epss`, `deps.kev_status`, `deps.fix_versions`, `deps.graph`, `deps.sbom_export`, `deps.transitive_path`, `deps.license_check` | static, on |
16
- | Static code analysis (SAST) | 8 | `sast.scan`, `sast.dataflow`, `sast.taint_trace`, `sast.authz_gaps`, `sast.deserialization`, `sast.ssrf`, `sast.injection`, `sast.rule_explain` | static, on |
17
- | Secret exposure | 4 | `secrets.scan`, `secrets.history_scan`, `secrets.blast_radius`, `secrets.validate` | static, on |
18
- | Container & image | 5 | `image.scan`, `image.layer_secrets`, `image.base_bump`, `image.misconfig`, `image.sbom` | static, on |
19
- | Infrastructure as code | 5 | `iac.terraform`, `iac.kubernetes`, `iac.dockerfile`, `iac.cloudformation`, `iac.explain` | static, on |
20
- | Reachability & exploitability | 4 | `exploit.reachability`, `exploit.rank`, `exploit.confirm`, `exploit.why_safe` | static, on |
21
- | Web app dynamic (DAST) | 6 | `dast.spider`, `dast.active_scan`, `dast.nuclei`, `dast.auth_probe`, `dast.replay`, `dast.stop` | **dynamic, off** |
22
- | API logic | 5 | `api.enumerate`, `api.idor_probe`, `api.authz_matrix`, `api.mass_assignment`, `api.poc_request` | **dynamic, off** |
23
- | Evidence & PoC | 5 | `evidence.record`, `evidence.export`, `evidence.import`, `poc.build`, `poc.verify` | mixed |
24
- | Remediation & handoff | 4 | `fix.plan`, `fix.suggest_patch`, `fix.mitigation`, `fix.handoff_patch_anything` | static, on |
25
- | Workspace & session | 5 | `target.set`, `target.list`, `scan.status`, `scan.cancel`, `policy.show` | control |
1
+ # Tool catalog & MCP contracts
2
+
3
+ Break Anything is one MCP interface over a deep arsenal of industry-standard scanners. The public
4
+ MCP interface describes *what the agent wants to learn*; a provider decides *how* to answer. This
5
+ page is the exhaustive catalog, organized by scan category.
6
+
7
+ Legend: **✅ shipped (0.2.0: `deps_scan`, `secrets_scan`, `image_scan`, `sast_scan`)** · **🧭
8
+ roadmap**. Dynamic (traffic-sending) tools are **off by default** and refuse any target not on the
9
+ authorization allowlist.
10
+
11
+ ---
12
+
13
+ ## ✅ Supply chain & dependencies (SCA) — `deps_scan`
14
+
15
+ | | |
16
+ | --- | --- |
17
+ | **Status** | ✅ shipped |
18
+ | **Primary engine** | OSV.dev query API (built-in, no install) |
19
+ | **Additional engines** | Trivy, Grype, pip-audit, govulncheck, cargo-audit, bundler-audit, `composer audit`, OWASP Dependency-Check |
20
+ | **Ecosystems** | npm, PyPI, Composer (PHP), Go, Maven/Gradle, Cargo, RubyGems, NuGet |
21
+ | **Intel overlay** | EPSS (exploit probability), CISA KEV (known-exploited), GitHub Advisory |
22
+ | **SBOM** | Syft / CycloneDX generation + diff |
23
+ | **Signal** | import-based reachability today; call-path reachability on the roadmap |
24
+ | **MCP tool** | `deps_scan(path, reachability?)` |
25
+ | **CLI** | `brk deps <path> [--json] [--no-reachability]` |
26
+
27
+ ## ✅ Secrets — `secrets_scan`
28
+
29
+ | | |
30
+ | --- | --- |
31
+ | **Status** | ✅ shipped |
32
+ | **Primary engine** | built-in pattern + entropy scanner |
33
+ | **Additional engines** | Gitleaks, TruffleHog, detect-secrets |
34
+ | **Scope** | working tree + full git history (`--history`) |
35
+ | **Patterns** | AWS, GCP, Stripe, GitHub, GitLab, Slack, OpenAI, JWTs, private keys, generic assigned secrets |
36
+ | **Extras** | redacted output; optional live-key validation (roadmap) |
37
+ | **MCP tool** | `secrets_scan(path, history?)` |
38
+ | **CLI** | `brk secrets <path> [--history] [--json]` |
39
+
40
+ ## ✅ Containers & images — `image_scan`
41
+
42
+ | | |
43
+ | --- | --- |
44
+ | **Status** | ✅ shipped (requires Trivy) |
45
+ | **Engines** | Trivy, Grype, Dockle (CIS best practices), Hadolint (Dockerfile lint) |
46
+ | **Finds** | OS + app-layer CVEs, Dockerfile anti-patterns, secrets in layers |
47
+ | **MCP tool** | `image_scan(ref)` |
48
+ | **CLI** | `brk image <ref> [--json]` |
49
+
50
+ ---
51
+
52
+ ## ✅ Static code analysis (SAST) — `sast_scan`
53
+
54
+ | | |
55
+ | --- | --- |
56
+ | **Status** | ✅ shipped (requires Semgrep) |
57
+ | **Primary engine** | Semgrep (default ruleset `p/security-audit`) |
58
+ | **Roadmap engines** | CodeQL, Bandit (Python), gosec (Go), Brakeman (Rails), Find-Sec-Bugs (Java), Psalm/PHPStan (PHP), njsscan (JS/TS), cppcheck (C/C++) |
59
+ | **Finds** | injection, XSS, broken access control, insecure deserialization, path traversal, SSRF, weak crypto — each with file/line, CWE/OWASP tags, and the snippet |
60
+ | **MCP tool** | `sast_scan(path, config?)` |
61
+ | **CLI** | `brk sast <path> [--json] [--config=<ruleset>] [--top=N]` |
62
+
63
+ ## 🧭 Infrastructure as Code (IaC) — `iac_scan`
64
+
65
+ | | |
66
+ | --- | --- |
67
+ | **Engines** | Checkov, tfsec, Terrascan, KICS, Kubescape, kube-bench, kubesec, Falco (runtime) |
68
+ | **Targets** | Terraform, CloudFormation, Kubernetes/Helm, Dockerfile, ARM/Bicep, Ansible |
69
+ | **Finds** | public buckets, open security groups, missing encryption, over-broad IAM, privileged containers |
70
+ | **Planned tool** | `iac_scan(path, framework?)` |
71
+
72
+ ## 🧭 Cloud posture (CSPM) — `cloud_audit`
73
+
74
+ | | |
75
+ | --- | --- |
76
+ | **Engines** | Prowler, ScoutSuite |
77
+ | **Clouds** | AWS, GCP, Azure (your own accounts/credentials) |
78
+ | **Finds** | CIS/PCI/SOC2 control failures, exposed resources, weak IAM |
79
+ | **Planned tool** | `cloud_audit(provider, profile)` — **dynamic, off by default** |
80
+
81
+ ## 🧭 Running web apps (DAST) — `dast_scan`
82
+
83
+ | | |
84
+ | --- | --- |
85
+ | **Engines** | OWASP ZAP, Nuclei, Nikto, Wapiti, sqlmap, ffuf, Katana, Dalfox, gobuster |
86
+ | **Finds** | OWASP Top 10, injection, XSS, SSRF, auth/session flaws, missing headers, hidden content/params — with the triggering request |
87
+ | **Planned tools** | `dast_scan(url, profile)`, `dast_nuclei(url, templates)` — **dynamic, off by default** |
88
+
89
+ ## 🧭 API security — `api_scan`
90
+
91
+ | | |
92
+ | --- | --- |
93
+ | **Engines** | Schemathesis (OpenAPI property-testing/fuzzing), ZAP API scan, auth-matrix prober |
94
+ | **Finds** | BOLA/IDOR, broken authentication, mass assignment, excessive data exposure (OWASP API Top 10) |
95
+ | **Planned tools** | `api_idor_probe`, `api_authz_matrix`, `api_fuzz(openapi)` — **dynamic, off by default** |
96
+
97
+ ## 🧭 Attack surface & recon — `recon`
98
+
99
+ | | |
100
+ | --- | --- |
101
+ | **Engines** | Nmap, Amass (OWASP), ProjectDiscovery suite (subfinder, httpx, naabu, dnsx, katana) |
102
+ | **Finds** | forgotten subdomains, exposed services, open ports, tech fingerprint, TLS/cert config (testssl.sh, sslyze) |
103
+ | **Planned tool** | `recon(domain)` — **dynamic, off by default, your own assets only** |
104
+
105
+ ## 🧭 Smart contracts (Web3) — `contract_scan`
106
+
107
+ | | |
108
+ | --- | --- |
109
+ | **Engines** | Slither, Mythril, Echidna (fuzzing) |
110
+ | **Finds** | reentrancy, integer overflow, access-control gaps, oracle manipulation |
111
+ | **Planned tool** | `contract_scan(path)` |
112
+
113
+ ## 🧭 Mobile — `mobile_scan`
114
+
115
+ | | |
116
+ | --- | --- |
117
+ | **Engines** | MobSF, APKiD, Semgrep mobile rules |
118
+ | **Targets** | Android APK, iOS IPA |
119
+ | **Finds** | insecure storage, hardcoded secrets, weak crypto, exported components |
120
+ | **Planned tool** | `mobile_scan(path)` |
121
+
122
+ ## 🧭 Fuzzing — `fuzz`
123
+
124
+ | | |
125
+ | --- | --- |
126
+ | **Engines** | AFL++, libFuzzer, Atheris (Python), Jazzer (Java), cargo-fuzz |
127
+ | **Finds** | crashes, memory-safety bugs, panics — with a minimized reproducer |
128
+ | **Planned tool** | `fuzz(target, harness)` — **dynamic, off by default** |
129
+
130
+ ## 🧭 Offensive / exploitation (authorized pentest) — `exploit_*`
131
+
132
+ | | |
133
+ | --- | --- |
134
+ | **Scope** | **Authorized targets only.** Gated, **off by default**, requires written permission and an allowlist. |
135
+ | **Engines** | Metasploit Framework, sqlmap, Hydra, Hashcat, BloodHound + Impacket (Active Directory), OpenVAS/Greenbone |
136
+ | **Finds** | confirmed exploitability — turns a "reachable" finding into a proven one on a target you own |
137
+ | **Planned tools** | `exploit_confirm(finding)`, `exploit_ad_path`, `exploit_cred_spray` — **dynamic, off by default** |
138
+
139
+ > This family exists so Break Anything can *prove* exploitability like a pentester, not so it can
140
+ > attack strangers. Every tool here refuses targets outside your authorization allowlist, and the
141
+ > project declines contributions that weaponize it against systems you don't control.
142
+
143
+ ## 🧭 AI / LLM security — `llm_scan`
144
+
145
+ | | |
146
+ | --- | --- |
147
+ | **Engines** | [Garak](https://github.com/NVIDIA/garak), prompt-injection + jailbreak probes |
148
+ | **Targets** | your own models, agents, and MCP tool surfaces |
149
+ | **Finds** | prompt injection, jailbreaks, training-data/secret leakage, unsafe tool exposure |
150
+ | **Planned tool** | `llm_scan(endpoint)` — **dynamic, off by default** |
151
+
152
+ ## 🧭 Binary & artifact analysis — `binary_scan`
153
+
154
+ | | |
155
+ | --- | --- |
156
+ | **Engines** | Ghidra, radare2/rizin, angr (symbolic execution) |
157
+ | **Targets** | compiled binaries, firmware, packaged apps |
158
+ | **Finds** | known-vulnerable bundled deps, memory-safety smells, hardcoded secrets (pairs with the REA companion) |
159
+ | **Planned tool** | `binary_scan(path)` |
160
+
161
+ ## 🧭 Remediation & handoff — `fix_*`
162
+
163
+ | | |
164
+ | --- | --- |
165
+ | **Finds** | n/a — produces fixes |
166
+ | **Planned tools** | `fix_plan(from)`, `fix_suggest_patch(finding)`, `fix_mitigation(finding)`, `fix_handoff_patch_anything(finding)` |
167
+
168
+ ---
26
169
 
27
170
  ## Authorization gates
28
171
 
29
- Dynamic families (`dast.*`, `api.*`, and `poc.*` when it sends traffic) require:
172
+ Dynamic families (`dast_*`, `api_*`, `recon`, `cloud_audit`, `fuzz`, `exploit_*`, `llm_scan`)
173
+ require both:
30
174
 
31
175
  ```bash
32
176
  export BRK_DYNAMIC_ENABLED=true
@@ -38,15 +182,14 @@ that disables this check.
38
182
 
39
183
  ## Evidence envelope
40
184
 
41
- Every tool returns a structured result with:
185
+ Every tool returns a structured result:
42
186
 
43
- - `finding` — the weakness, with a stable ID;
44
- - `provider` — which engine produced it (e.g. `semgrep`, `trivy`, `osv`);
187
+ - `finding` — the weakness, with a stable ID
188
+ - `provider` — which engine produced it (e.g. `osv`, `trivy`, `semgrep`, `zap`)
45
189
  - `exploitability` — `confirmed` | `reachable` | `present` | `not_reachable`, plus EPSS and KEV
46
- when available;
47
- - `evidence` — file/line, data-flow, or the request/response that proves it;
48
- - `remediation` — fix version, patch sketch, or mitigation;
49
- - `limitations` — what this result does **not** establish.
190
+ - `evidence` — file/line, data-flow, or the request/response that proves it
191
+ - `remediation` — fix version, patch sketch, or mitigation
192
+ - `limitations` — what this result does **not** establish
50
193
 
51
194
  ## Manual MCP registration
52
195