Ecosystem audit, distribution surfaces, and 5 precision fixes

.gitignore

@@ -11,6 +11,7 @@ Thumbs.db
 .vscode/
 .idea/
 *.tgz
+*.vsix
 report.md
 report.html
 MARKETING.md

.pre-commit-hooks.yaml

@@ -0,0 +1,34 @@
+# Lets a project add this repo as a pre-commit (https://pre-commit.com) hook
+# source instead of (or alongside) the GitHub Action:
+#
+#   repos:
+#     - repo: https://github.com/akanthed/SecureAI-Scan
+#       rev: v0.10.0
+#       hooks:
+#         - id: secureai-scan
+#
+# `language: node` means pre-commit installs this repo's own package.json
+# into an isolated node_modules the first time the hook runs, cached after
+# that for the same `rev`. That install is a bare `npm install`, which does
+# not build `dist/` (a git checkout, unlike the published npm tarball,
+# ships no prebuilt `dist/`, and there's no npm lifecycle script that builds
+# on a plain install without risking breaking the published package for
+# ordinary end users) — so `entry` points at a small wrapper
+# (scripts/precommit-entry.js) that builds once, then runs the scan.
+#
+# `pass_filenames: false` + `always_run: true`: this scanner traces
+# source→flow→sink dataflow across files (an import-resolved LLM call in file
+# A can depend on a source file B never touched by this commit), so handing
+# it only the changed filenames would silently break that tracing. It scans
+# the whole project every run instead, the same way `tsc`/`mypy` pre-commit
+# hooks do for the same reason. `--fail-on high` keeps it from blocking a
+# commit over the lower-severity/heuristic tail; override via `args:` in the
+# consuming project's own `.pre-commit-config.yaml` to change the threshold.
+- id: secureai-scan
+  name: SecureAI-Scan
+  description: Scan for LLM/MCP/RAG security risks (prompt injection, tool poisoning, RAG misconfig) with dataflow evidence.
+  entry: node scripts/precommit-entry.js
+  args: ["--fail-on", "high"]
+  language: node
+  pass_filenames: false
+  always_run: true

.secureai-policy.json

@@ -1,10 +1,10 @@
 {
   "$comment": "SecureAI-Scan policy file — commit this to your repo. See: secureai-scan explain <RULE_ID>",
-  "$skipPathsRationale": "test-fixtures/ is deliberately vulnerable code that the suite requires to fire (see test/corpus.test.js, which scans it directly as its own root); .regression-cache/ holds repos cloned by npm run regression. Neither is this project's source.",
+  "$skipPathsRationale": "test-fixtures/ and docs/demo-source/ contain deliberately vulnerable code used by tests and documentation; .regression-cache/ holds repos cloned by npm run regression. None are this project's production source.",
   "minSeverity": "medium",
   "minConfidence": 0.45,
   "failOnSeverity": "high",
-  "skipPaths": ["test-fixtures", ".regression-cache"],
+  "skipPaths": ["test-fixtures", "docs/demo-source", ".regression-cache"],
   "blockedRules": [],
   "onlyRules": [],
   "requireOutputValidation": true

README.md

@@ -48,6 +48,7 @@ No account, cloud upload, Python interpreter, or configuration required. TypeScr
 - [See it work](#see-it-work)
 - [Commands](#commands)
 - [GitHub Action](#github-action)
+- [Pre-commit hook](#pre-commit-hook)
 - [Rules](#rules)
 - [Architecture](#architecture)
 - [MCP server (use it from Claude)](#mcp-server-use-it-from-claude)
@@ -98,7 +99,9 @@ If you already run Semgrep or GHAS, keep them — add SecureAI-Scan for the risk
 
 ## See it work
 
-<!-- TODO: terminal recording of `secureai-scan scan .` end-to-end, from npx invocation to the evidence-tiered report. Keep it small (compress, or host as a GitHub release asset rather than a raw repo file). No demo GIF exists yet; don't add an <img>/markdown reference here until one is actually committed or hosted, or it renders as a broken image on GitHub. -->
+`secureai-scan scan .` end to end, real output against a real (small, deliberately vulnerable) file — [source](docs/demo-source):
+
+<img src="docs/demo.svg" alt="Terminal recording of secureai-scan scan . finding a traced prompt-injection vulnerability" width="700">
 
 Attack shapes the scanner traces end to end:
 
@@ -168,7 +171,7 @@ secureai-scan mcp owner/mcp-server-repo        # or git, same as `skill`
 ```bash
 secureai-scan bom . --output AI_BOM.md   # AI Bill of Materials
 secureai-scan explain AI001              # why + exploit + fix example, for any rule
-secureai-scan threat-model .             # THREAT_MODEL.md with the OWASP coverage matrix
+secureai-scan threat-model .             # THREAT_MODEL.md with the OWASP coverage matrix — example: docs/examples/THREAT_MODEL.example.md
 secureai-scan init                       # policy file + CI workflow, one-time setup
 ```
 
@@ -205,6 +208,25 @@ Scanning clean? Add the badge to your own README:
 [![secureai-scan](https://img.shields.io/badge/secureai--scan-passing-brightgreen)](https://github.com/akanthed/SecureAI-Scan)
 ```
 
+## Pre-commit hook
+
+Prefer catching findings before they're pushed? Add this repo as a [pre-commit](https://pre-commit.com) hook source instead of, or alongside, the GitHub Action:
+
+```yaml
+repos:
+  - repo: https://github.com/akanthed/SecureAI-Scan
+    rev: v0.10.0
+    hooks:
+      - id: secureai-scan
+```
+
+The hook scans the whole project on every commit (not just changed files — a dataflow trace into file A can depend on file B, which a partial scan would miss) and blocks the commit on `high`+ severity findings by default. Override the threshold in your own config:
+
+```yaml
+      - id: secureai-scan
+        args: ["--fail-on", "critical"]
+```
+
 ## Rules
 
 **42 rules**, mapped to the official OWASP Top 10 for LLM Applications (2026) — plus, where applicable, the OWASP Top 10 for Agentic Applications (2026, ASI), the OWASP MCP Top 10 (2025), and an EU AI Act article. See the [versioned 2026 coverage and limits](docs/OWASP2026.md); `threat-model` renders the matrix for each scanned project.

ROADMAP.md

@@ -52,24 +52,38 @@ Cannot out-engineer Cisco/Snyk on headcount. Can out-trust them on process.
 
 ## Distribution (the actual growth plan)
 
-**The wedge is pre-install, not post-commit.** Shipped: `secureai-scan skill <target>` / `secureai-scan mcp <target>`. Next: get this into the places the decision actually gets made —
+**The wedge is pre-install, not post-commit.** Shipped: `secureai-scan skill <target>` / `secureai-scan mcp <target>`. Also shipped (2026-08-26): a `pre-commit` hook (`.pre-commit-hooks.yaml`, `scripts/precommit-entry.js`) alongside the existing GitHub Action — catches findings before a push, not just after.
+
+**VS Code / Cursor extension — scaffolded (2026-08-26), not published.** `vscode-extension/` wraps the CLI (bundled as a real npm dependency, no network calls at scan time — same offline guarantee as the CLI) and reports findings as Problems-panel diagnostics on save, with `Scan Workspace`/`Scan Current File's Project`/`Clear Findings` commands and a status-bar count. Validated: `tsc` compiles clean under `strict`, `vsce package` produces a real installable `.vsix` (5.47MB — mostly tree-sitter's native Python-parser bindings and ts-morph's bundled TypeScript compiler, both load-bearing, not bloat), and the diagnostic-mapping logic is checked against the CLI's actual `--output <file>.json` schema, not a guessed one. **Not done:** published nowhere — Marketplace publishing needs a publisher account/token this session doesn't have. Also open: bundling/minifying (`vsce` warns about 366 unbundled files; performance, not correctness), an icon, and Cursor-specific packaging if that turns out to differ from plain VS Code.
+
+Remaining distribution surface:
 
 - A Claude Code / MCP-server-side integration (the `mcp-server/index.js` this project already ships is the natural host — scan a skill from *inside* the agent, before it's trusted).
-- A VS Code / Cursor extension.
-- A `pre-commit` hook alongside the existing GitHub Action.
 
 **Ecosystem audit.** Scan every public MCP server and published skill; publish results as a standing, dated report. This is how MCP-Scan built its following, it doubles as marketing, and it feeds the advisory list — the one asset that compounds and that a competitor can't shortcut without doing the same legwork. Today's `vercel/ai` triage is a miniature proof of this: a few hours of pointing the scanner at real code found five real, fixable bugs.
 
+First real round shipped 2026-08-26: six independent MCP servers not in the regression corpus (context7, mcp-server-cloudflare, supabase-mcp, firecrawl-mcp-server, agent-toolkit, awslabs/mcp), five root-cause bugs found and fixed — including a `proven`/critical false positive, the worst-possible-tier miss, and a same-day follow-up that closed the remaining seven `MCP009`/`SKL003` false positives properly (distinguishing "tool referenced as the trigger clause's subject" — the real attack shape — from "tool referenced as the verb's object" — ordinary comparison docs — rather than a shortcut that would have cost recall on the real attack) — plus real confirmed findings (unpinned `@latest` MCP configs and a tenant-filter gap in `awslabs/mcp`). Full writeup in [`docs/RealWorldFindings.md`](docs/RealWorldFindings.md#an-ecosystem-audit-of-public-mcp-servers-found-three-more-false-positive-classes--and-one-provencritical-one). Not yet turned into the "standing" part — a recurring, dated cadence, and a decision on whether audited repos join the permanent `npm run regression` corpus, are still open.
+
 **Compliance packaging.** The OWASP LLM/ASI/MCP triple mapping and auto-generated `threat-model` coverage matrix already exist and are underused as a selling point — EU AI Act evidence generation is badly underserved by US-centric competitors. "Produces the artifact your auditor asks for" sells independently of rule-count comparisons.
 
 ## Honest competitive position
 
+**Correction (2026-08-26):** MCP-Scan (Invariant Labs) and Snyk agent-scan are not two competitors — Invariant Labs was acquired by Snyk in June 2025, and MCP-Scan was rebranded into Snyk's Agent Scan product. That's one competitor with both the 2k+-star open-source mindshare *and* Snyk's enterprise sales/distribution behind it, not two separate smaller ones. Treat it as a single combined entry below.
+
 | | Edge | Gap |
 |---|---|---|
-| Cisco skill-scanner | zero-config npm install, no cloud dependency, precision discipline | multi-engine behavioral + LLM analysis, funded team |
-| MCP-Scan (Invariant Labs) | broader scope (skills + RAG + code, not MCP-only), evidence tiers | mindshare, first-mover, 2k+ stars |
-| Snyk agent-scan | open source, transparent rules, no seat pricing | enterprise distribution, existing customer base |
+| Snyk Agent Scan (formerly MCP-Scan, Invariant Labs — acquired June 2025) | broader static scope (skills + RAG + code, not MCP-only), evidence tiers | mindshare (2k+ stars vs. our 19), first-mover, Snyk's existing enterprise customer base and sales motion |
+| Cisco skill-scanner / DefenseClaw | zero-config npm install, no cloud dependency, precision discipline | multi-engine behavioral + LLM-adjudicated analysis, a shipped VS Code extension, 6 output formats, bundled into Cisco's broader agent-governance platform, funded team, RSA 2026 launch visibility |
 
 **Not worth attempting:** a runtime/behavioral engine, general-purpose SAST/secret-scanning (explicitly out of scope — see `CLAUDE.md`), competing on raw rule count. Each loses on resources against funded competitors.
 
 **Positioning:** the scanner whose findings don't need triaging, that runs before you install anything, and that hands your auditor a document — not the scanner with the most rules.
+
+### Adoption gap (as of 2026-08-26)
+
+The technical comparison above still favors us on precision and dataflow-traced evidence. The gap that actually explains low adoption is distribution and trust signal, not detection quality:
+
+- **19 GitHub stars** (repo created 2026-02-05) vs. 2,000+ for Snyk Agent Scan. There is essentially no organic mindshare — no third-party blog coverage, no HN/Reddit threads, no comparison articles that mention this project unprompted.
+- **No IDE presence.** Cisco's scanner already ships a VS Code extension; ours is CLI/GitHub-Action only. The "ecosystem audit" and "VS Code / Cursor extension" items below are still the two highest-leverage unshipped items in this file for exactly that reason — they're the cheapest way to generate both external citations and an in-editor discovery moment.
+- **Single-maintainer trust ceiling.** Enterprise buyers weight "who backs this" heavily; Snyk and Cisco both answer that by default, we answer it with the release-assurance/precision-contract paper trail instead, which requires a reader who already trusts us enough to go check it.
+- **Compliance angle is a paragraph, not a shipped artifact.** The EU AI Act / OWASP mapping is a real differentiator per this doc's own "Compliance packaging" note, but there is no example generated audit artifact or landing page proving it out yet.