@vibefoundry/vibe-shield 1.1.0 → 2.0.0

package/README.md

@@ -8,17 +8,17 @@ Your agent ships fast. It also ships `NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY`, a
 
 vibe-shield is a **static security scanner built for that failure mode**, plus an **Agent Skill** that makes Claude Code, Codex, Cursor and Windsurf audit before they say *"done"*.
 
-[![version](https://img.shields.io/github/package-json/v/avivgerz-hue/vibe-shield?style=flat-square&label=version&color=cb3837)](https://github.com/avivgerz-hue/vibe-shield/blob/main/package.json)
-[![install](https://img.shields.io/badge/install-github%3Aavivgerz--hue%2Fvibe--shield-cb3837?style=flat-square&logo=npm)](#-quick-start)
+[![npm version](https://img.shields.io/npm/v/@vibefoundry/vibe-shield.svg)](https://www.npmjs.com/package/@vibefoundry/vibe-shield)
+[![npm downloads](https://img.shields.io/npm/dm/@vibefoundry/vibe-shield.svg)](https://www.npmjs.com/package/@vibefoundry/vibe-shield)
 [![CI](https://img.shields.io/github/actions/workflow/status/avivgerz-hue/vibe-shield/ci.yml?branch=main&style=flat-square&logo=githubactions&label=CI)](https://github.com/avivgerz-hue/vibe-shield/actions/workflows/ci.yml)
 [![node](https://img.shields.io/badge/node-%E2%89%A518.17.0-5fa04e?style=flat-square&logo=nodedotjs)](#-requirements)
 [![license](https://img.shields.io/github/license/avivgerz-hue/vibe-shield?style=flat-square&color=blue)](./LICENSE)
 [![zero dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen?style=flat-square)](./package.json)
-[![rules](https://img.shields.io/badge/detection%20signatures-60-8b5cf6?style=flat-square)](./src/scanner/rules)
+[![rules](https://img.shields.io/badge/detection%20signatures-91-8b5cf6?style=flat-square)](./src/scanner/rules)
 [![self-scan](https://img.shields.io/badge/self--scan-100%2F100%20A%2B-16a34a?style=flat-square)](#-it-scans-itself)
 
 ```bash
-npx github:avivgerz-hue/vibe-shield scan
+npx -y @vibefoundry/vibe-shield scan
 ```
 
 ![vibe-shield terminal preview](./assets/hero-terminal.svg)
@@ -27,6 +27,26 @@ npx github:avivgerz-hue/vibe-shield scan
 
 ---
 
+## v2.0.0: eight defensive vectors
+
+The v2 catalogue covers client exposure; auth and route protection; database/RLS; AI and web sinks; infrastructure; dependency hygiene; secrets and cryptography; and agent/MCP integrity. The new hardening checks include production source maps, insecure JWT settings, explicit and omitted cookie flags, locally absent security headers, container users, lifecycle scripts, lockfiles and weak cryptography. Run `rules` for the complete catalogue.
+
+The scanner produces a heuristic **attack-surface inventory** of route methods, observed guard signals, SQL tables and RLS signals, AI entrypoints, and MCP/agent files. Header checks cover recognized server configuration files; cookie checks cover common literal setter options. Both are advisory: external middleware, deployment settings and dynamic options require review. Signals do not prove guards or policies work, and code outside the scanned scope is not assessed. Run `audit-skills` separately for agent-integrity checks.
+
+Generate an executive report or agent remediation prompt explicitly:
+
+```bash
+npx -y @vibefoundry/vibe-shield scan --report SECURITY-REPORT.md --patch-prompt PATCH-PROMPT.md
+npx -y @vibefoundry/vibe-shield scan --format html --out security-report.html
+npx -y @vibefoundry/vibe-shield audit-skills --report agent-report.html
+```
+
+Reports include severity, CWE, locations, snippets, OWASP 2025 web mappings for every rule and contextual LLM mappings when applicable, and illustrative remediation. Examples are **not** automatic project-specific patches; validate them against the application. The scanner itself is offline and read-only by default; `--cache`, `--out`, `--report`, `--patch-prompt` and `init` explicitly write files. Installing with `npx` can require network access. An A+ score applies only to the rules and files examined and is not a security certification.
+
+> The source tree targets v2.0.0; the npm commands acquire the published version, which may lag this branch until a release is published. To exercise this checkout locally, run `npm ci && npm run build`, then `node dist/bin/vibe-shield.js` with the same arguments.
+
+---
+
 ## The problem, in one file
 
 This is the shape of code an agent writes when you ask for "a delete endpoint":
@@ -42,10 +62,10 @@ export async function DELETE(req: Request) {
 
 It works. It also has **three critical vulnerabilities** — no authentication, SQL injection, and an IDOR that lets the caller choose whose data they delete. Nothing in a normal review loop catches all three, and the agent reported the task as complete.
 
-`npx github:avivgerz-hue/vibe-shield scan` catches all three in **17 milliseconds**:
+`npx -y @vibefoundry/vibe-shield scan` catches all three in **17 milliseconds**:
 
 ```
-🛡️  vibe-shield v1.0.0 · security scan
+🛡️  vibe-shield · security scan (illustrative output)
 target  /home/you/app
 
 💀 GRADE F — 0/100 · 3 critical
@@ -61,18 +81,18 @@ app/api/users/route.ts
            await db.query(`DELETE FROM users WHERE id = ${id} AND owner = ${userId}`);
   CRITICAL 4:22     VSB-AUTH-004  Record ownership taken from the request instead of the session (IDOR)
 
-  7 files  ·  1 KiB  ·  412 files/s  ·  17 ms  ·  48 rules
+  7 files  ·  1 KiB  ·  412 files/s  ·  17 ms  ·  79 rules
 
   ⚠  3 critical findings — rotate any exposed credential before anything else.
-  Fix it      npx github:avivgerz-hue/vibe-shield scan --fix-prompt    # writes SECURITY_PATCH_PROMPT.md for your agent
-  Explain     npx github:avivgerz-hue/vibe-shield explain VSB-AUTH-001
-  Gate CI     npx github:avivgerz-hue/vibe-shield scan --fail-on critical --format github
+  Fix it      npx -y @vibefoundry/vibe-shield scan --fix-prompt    # writes SECURITY_PATCH_PROMPT.md for your agent
+  Explain     npx -y @vibefoundry/vibe-shield explain VSB-AUTH-001
+  Gate CI     npx -y @vibefoundry/vibe-shield scan --fail-on critical --format github
 ```
 
 Then hand the fix list to the agent that wrote the bug:
 
 ```bash
-npx github:avivgerz-hue/vibe-shield scan --fix-prompt   # → SECURITY_PATCH_PROMPT.md
+npx -y @vibefoundry/vibe-shield scan --fix-prompt   # → SECURITY_PATCH_PROMPT.md
 ```
 
 That file contains, for every finding: the severity, the CWE id and link, the exact `file:line`, the vulnerable snippet, the ordered remediation steps, the target code shape, and a verification command. It is written for a machine to execute and a human to audit.
@@ -83,22 +103,23 @@ That file contains, for every finding: the severity, the CWE id and link, the ex
 
 ```bash
 # 1. Scan (no install, no config, no network calls)
-npx github:avivgerz-hue/vibe-shield scan
+npx -y @vibefoundry/vibe-shield scan
 
 # 2. Give your agent the fix list
-npx github:avivgerz-hue/vibe-shield scan --fix-prompt
+npx -y @vibefoundry/vibe-shield scan --fix-prompt
 
 # 3. Install the gate permanently — skill + CI + ignore file
-npx github:avivgerz-hue/vibe-shield init
+npx -y @vibefoundry/vibe-shield init
 ```
 
-> **Why GitHub and not `npx vibe-shield`?** The name `vibe-shield` on the npm
-> registry belongs to a different project with no connection to this one. Running
-> `npx vibe-shield` installs *their* package, not this repository's. Install from
-> GitHub — the compiled CLI is committed, so it needs **no TypeScript** and starts
-> in milliseconds. A scoped npm release (`@vibefoundry/vibe-shield`) may follow.
+> **Use the scoped name.** vibe-shield is published as
+> [`@vibefoundry/vibe-shield`](https://www.npmjs.com/package/@vibefoundry/vibe-shield).
+> The *unscoped* name `vibe-shield` on npm belongs to an unrelated project, so
+> `npx vibe-shield` runs someone else's code. Always include the `@vibefoundry/`
+> scope. The package ships a prebuilt `dist/`, needs **no TypeScript**, and
+> starts in milliseconds.
 
-`npx github:avivgerz-hue/vibe-shield init` writes:
+`npx -y @vibefoundry/vibe-shield init` writes:
 
 | File | What it does |
 | --- | --- |
@@ -125,13 +146,13 @@ Traditional SAST rules are built around human mistakes: a forgotten escape, a mi
 | writes `CREATE TABLE` | writes `CREATE TABLE` **and forgets the `ENABLE ROW LEVEL SECURITY`**, so the anon key reads everything |
 | adds `dangerouslySetInnerHTML` to render a doc | renders **model output** with it, creating stored XSS with a step counter |
 
-vibe-shield encodes those specific shapes: 60 signatures across five families, each one derived from a real agent-generated bug rather than a generic CWE checklist.
+vibe-shield encodes those specific shapes: 91 signatures across eight defensive categories, each one derived from a real agent-generated bug rather than a generic CWE checklist.
 
 ---
 
 ## 📊 Vulnerability Coverage Matrix
 
-**48 code signatures + 12 agent-integrity signatures = 60.** Every rule has an id, a CWE, a vulnerable example, a fixed example, and ordered remediation steps — run `npx github:avivgerz-hue/vibe-shield rules` or `npx github:avivgerz-hue/vibe-shield explain <ID>`.
+**79 code signatures + 12 agent-integrity signatures = 91.** Every rule has an id, a CWE, an illustrative vulnerable shape, remediation guidance, and an OWASP association — run `npx -y @vibefoundry/vibe-shield rules` or `npx -y @vibefoundry/vibe-shield explain <ID>`.
 
 ### Client-side secret & data exposure — `VSB-CLIENT-*`
 
@@ -234,33 +255,38 @@ Claude Code, Claude Desktop, Cursor and Codex can call the scanner as a tool
 instead of shelling out and parsing console output.
 
 ```bash
-npx github:avivgerz-hue/vibe-shield mcp          # JSON-RPC 2.0 over stdio
+npx -y @vibefoundry/vibe-shield mcp          # JSON-RPC 2.0 over stdio
+npx -y @vibefoundry/vibe-shield --mcp        # same thing, if your client prefers a flag
 ```
 
 Three tools:
 
 | Tool | What it does |
 | --- | --- |
-| `vibe_shield_scan` | Runs the 60 rules over a project or specific paths → grade, score, findings with file:line, CWE and remediation |
+| `vibe_shield_scan` | Runs the code-scanning rules over a project or specific paths → grade, score, findings with file:line, CWE and remediation |
 | `vibe_shield_audit_skills` | Audits `.claude/skills`, `.cursor` rules, `AGENTS.md` and MCP configs for prompt injection and exfiltration traps |
 | `vibe_shield_explain_rule` | Full CWE detail, vulnerable/fixed examples and remediation for any rule id or slug |
 
-`npx github:avivgerz-hue/vibe-shield init` writes the config for you, merging into `.mcp.json`
+`npx -y @vibefoundry/vibe-shield init` writes the config for you, merging into `.mcp.json`
 **without clobbering** servers you already have:
 
 ```jsonc
 {
   "mcpServers": {
     "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
-    "vibe-shield": { "command": "npx", "args": ["--yes", "github:avivgerz-hue/vibe-shield", "mcp"] }
+    "vibe-shield": { "command": "npx", "args": ["--yes", "@vibefoundry/vibe-shield@1.1.1", "mcp"] }
   }
 }
 ```
 
+The version pin is not cosmetic: an unpinned `npx -y` server is exactly what
+`VSB-AGENT-004` flags as high severity, so vibe-shield's own audit would write
+itself a finding. `init` pins the running version automatically.
+
 Or add it by hand:
 
 ```bash
-claude mcp add vibe-shield -- npx --yes github:avivgerz-hue/vibe-shield mcp
+claude mcp add vibe-shield -- npx -y @vibefoundry/vibe-shield mcp
 ```
 
 The server is zero-dependency, writes **only** JSON-RPC to stdout, honours
@@ -275,15 +301,15 @@ a scanner that says "clean" when it read nothing is worse than no scanner.
 
 ## 🤖 Use it as an Agent Skill
 
-`npx github:avivgerz-hue/vibe-shield init` installs the skill. Once it is in a repository, every
+`npx -y @vibefoundry/vibe-shield init` installs the skill. Once it is in a repository, every
 agent session starts with a contract:
 
 > You are not allowed to say "done" until the code you just wrote passes a security audit.
 
 ```bash
-npx github:avivgerz-hue/vibe-shield init                 # Claude Code + Cursor + AGENTS.md + CI
-npx github:avivgerz-hue/vibe-shield init --agent claude  # just the skill
-npx github:avivgerz-hue/vibe-shield init --no-workflow   # skip the GitHub Action
+npx -y @vibefoundry/vibe-shield init                 # Claude Code + Cursor + AGENTS.md + CI
+npx -y @vibefoundry/vibe-shield init --agent claude  # just the skill
+npx -y @vibefoundry/vibe-shield init --no-workflow   # skip the GitHub Action
 ```
 
 **Why this works better than a prompt snippet:** it names the three commands, gives the agent a reading guide for a finding (`line:col`, rule id, message, CWE), states five hard rules (never suppress, never weaken, always rotate, report honestly, re-verify), and defines "done" as an exit code rather than an opinion.
@@ -294,7 +320,7 @@ The skill itself is [SKILL.md](./SKILL.md) — read it, it is short.
 
 ```bash
 # marketplace-style install
-npx github:avivgerz-hue/vibe-shield init --agent claude
+npx -y @vibefoundry/vibe-shield init --agent claude
 # → .claude/skills/vibe-shield/SKILL.md
 
 # or globally, for every project
@@ -308,7 +334,7 @@ curl -sL https://raw.githubusercontent.com/avivgerz-hue/vibe-shield/main/SKILL.m
 
 ### GitHub Actions (recommended)
 
-`npx github:avivgerz-hue/vibe-shield init` installs a workflow that runs the scan, uploads SARIF to
+`npx -y @vibefoundry/vibe-shield init` installs a workflow that runs the scan, uploads SARIF to
 code scanning, audits the agent surface, and fails the job:
 
 ```yaml
@@ -329,7 +355,7 @@ jobs:
           node-version: 20
 
       - name: Scan and upload SARIF
-        run: npx --yes github:avivgerz-hue/vibe-shield scan --format sarif --out vibe-shield.sarif --fail-on high
+        run: npx -y @vibefoundry/vibe-shield scan --format sarif --out vibe-shield.sarif --fail-on high
         continue-on-error: true
 
       - uses: github/codeql-action/upload-sarif@v3
@@ -339,7 +365,7 @@ jobs:
           category: vibe-shield
 
       - name: Enforce the gate
-        run: npx --yes github:avivgerz-hue/vibe-shield scan --fail-on high
+        run: npx -y @vibefoundry/vibe-shield scan --fail-on high
 ```
 
 Findings appear **inline on the pull request diff** (GitHub annotations) and in
@@ -349,11 +375,11 @@ on the line that introduced it.
 ### Any other CI
 
 ```bash
-npx github:avivgerz-hue/vibe-shield scan --fail-on high                         # exit 1 on findings
-npx github:avivgerz-hue/vibe-shield scan --format compact                       # one line per finding
-npx github:avivgerz-hue/vibe-shield scan --format json > vibe-shield.json       # full report
-npx github:avivgerz-hue/vibe-shield scan --format summary                       # JSON, counts + grade only
-npx github:avivgerz-hue/vibe-shield scan --format github                        # workflow annotations
+npx -y @vibefoundry/vibe-shield scan --fail-on high                         # exit 1 on findings
+npx -y @vibefoundry/vibe-shield scan --format compact                       # one line per finding
+npx -y @vibefoundry/vibe-shield scan --format json > vibe-shield.json       # full report
+npx -y @vibefoundry/vibe-shield scan --format summary                       # JSON, counts + grade only
+npx -y @vibefoundry/vibe-shield scan --format github                        # workflow annotations
 ```
 
 Exit codes: **0** clean · **1** findings at/above `--fail-on` · **2** usage error
@@ -385,17 +411,17 @@ Penalties per finding: critical −30, high −12, medium −5, low −2, info
 This repository runs its own gate on every commit and in CI:
 
 ```console
-$ npx github:avivgerz-hue/vibe-shield scan
-🛡️  vibe-shield v1.0.0 · security scan
+$ npx -y @vibefoundry/vibe-shield scan
+🛡️  vibe-shield · security scan (illustrative output)
 target  /you/vibe-shield
 
 🏆 GRADE A+ — 100/100
 
-  21 files  ·  172 KiB  ·  236 files/s  ·  89 ms  ·  48 rules
+  21 files  ·  172 KiB  ·  236 files/s  ·  89 ms  ·  79 rules
 
   Nothing to fix. Keep the shield up. 🛡️
 
-$ npx github:avivgerz-hue/vibe-shield audit-skills
+$ npx -y @vibefoundry/vibe-shield audit-skills
 🏆 GRADE A+ — 100/100
 
   1 file  ·  6 KiB  ·  14 files/s  ·  69 ms  ·  12 rules
@@ -435,7 +461,7 @@ Suppressed findings are **counted and reported** in the scorecard, never silentl
 ```
  discover ──▶ project context ──▶ rule gate ──▶ detect ──▶ suppress ──▶ score ──▶ report
    │              │                  │           │
-   │              │                  │           └─ 60 rules, each a pure (FileContext) => RuleHit[]
+   │              │                  │           └─ 91 rules, each a pure (FileContext) => RuleHit[]
    │              │                  └─ cheap content hints: most rules skip most files
    │              └─ manifests, framework flags, cross-file RLS index, git index, middleware matchers
    └─ one tree walk, gitignore/.vibe-shieldignore layering, binary + size + test/doc pruning
@@ -447,7 +473,7 @@ Suppressed findings are **counted and reported** in the scorecard, never silentl
 2. **Honest.** Every finding carries the exact snippet the developer wrote. Nothing is inferred from a filename alone, and every suppression is counted, not hidden.
 3. **Composable.** `scanProject()` for the CLI, `runRulesOnFile()` for the auditor, `scoreFindings()` for anything that produces findings. The whole API is exported from `vibe-shield`.
 
-**Zero runtime dependencies.** No network calls, no telemetry, no language server, no native binaries. `npx github:avivgerz-hue/vibe-shield scan` works offline and in an air-gapped CI runner.
+**Zero runtime dependencies.** No network calls, no telemetry, no language server, no native binaries. `npx -y @vibefoundry/vibe-shield scan` works offline and in an air-gapped CI runner.
 
 ---
 
@@ -465,7 +491,7 @@ vibe-shield version | help
 
 | Flag | Default | Meaning |
 | --- | --- | --- |
-| `--format <fmt>` | `console` | `console` `compact` `summary` `json` `sarif` `github` |
+| `--format <fmt>` | `console` | `console` `compact` `summary` `json` `sarif` `github` `markdown` `html` |
 | `--fail-on <sev>` | `critical` | Exit 1 at/above this severity |
 | `--severity <sev>` | — | Only report at/above this severity |
 | `--fix-prompt` | off | Write `SECURITY_PATCH_PROMPT.md` |
@@ -567,5 +593,5 @@ Three tools for the same problem: agents move fast, and something has to keep th
 | 👻 | **[ghost-qa](https://github.com/avivgerz-hue/ghost-qa)** | Autonomous headless-browser QA & self-healing verification loop — stops agents from claiming a UI works when it does not |
 
 ```bash
-npx github:avivgerz-hue/vibe-shield init   # security gate
+npx -y @vibefoundry/vibe-shield init   # security gate
 ```

package/SECURITY.md

@@ -14,7 +14,7 @@
 Email **security@vibefoundry.dev** with:
 
 - a description of the issue and its impact
-- the affected version (`npx github:avivgerz-hue/vibe-shield version`)
+- the affected version (`npx -y @vibefoundry/vibe-shield version`)
 - a minimal reproduction (a snippet, a repository, or a failing test)
 - whether you intend to publish, and any deadline you are working to
 

package/SKILL.md

@@ -1,124 +1,57 @@
 ---
 name: vibe-shield
-description: Audit any change for AI-introduced security bugs (leaked keys, unguarded API routes, disabled Row Level Security, SQL injection, prompt injection, poisoned MCP servers) and fix them before reporting a task as done. Use whenever you write or modify application code, API routes, server actions, database migrations, auth logic, environment variables, LLM calls, webhook handlers, agent skills or MCP configuration.
-allowed-tools: Bash(npx github:avivgerz-hue/vibe-shield scan*), Bash(npx github:avivgerz-hue/vibe-shield audit-skills*), Bash(npx github:avivgerz-hue/vibe-shield explain*), Read(./**), Grep, Glob
+description: Apply a six-phase defensive security review to changes affecting applications, APIs, data, AI agents, and MCP configuration. Use static evidence, preserve behavior, and report limitations.
+allowed-tools: Bash(npx -y @vibefoundry/vibe-shield scan*), Bash(npx -y @vibefoundry/vibe-shield audit-skills*), Bash(npx -y @vibefoundry/vibe-shield explain*), Read(./**), Grep, Glob
 license: MIT
 metadata:
   author: VibeFoundry
   homepage: https://github.com/avivgerz-hue/vibe-shield
-  version: 1.0.0
+  version: 2.0.0
 ---
 
-# vibe-shield
+# Defensive AppSec architect protocol
 
-You are not allowed to say "done" until the code you just wrote passes a security audit.
+Work only within the authorized project. Static findings are evidence for review, not proof of exploitability or a guarantee of safety. Do not transmit source code or secrets. Ask before changing production services, rotating credentials, or making destructive changes.
 
-AI coding agents ship a specific, repeatable class of vulnerability: a `SUPABASE_SERVICE_ROLE_KEY` behind a `NEXT_PUBLIC_` prefix, a `DELETE` route handler with no session check, a `CREATE TABLE` with no `ENABLE ROW LEVEL SECURITY`, a tool whose `execute` forwards model output into `exec`. These are not exotic — they are the default shape of code written quickly by something optimising for "it works". This skill is the second pair of eyes.
+## Phase 1: Attack-surface reconnaissance
 
-## When to run
+Map entrypoints and trust boundaries: API methods, authentication and authorization, middleware matchers, database tables and policies, storage, LLM inputs and tools, webhooks, and agent/MCP configuration. Check deployment configuration and exclusions. Identify what the scanner cannot see.
 
-Run the audit **after every change that touches**:
-
-- an API route, route handler, server action, RPC endpoint or GraphQL mutation
-- authentication, session, role, permission or ownership logic
-- a database migration, policy, grant, schema or Supabase table
-- an environment variable, config file, `.env*` file or build config
-- anything calling an LLM, a tool, a webhook, a shell command or the filesystem
-- `.claude/`, `.cursor/`, `AGENTS.md`, `mcp.json` or any skill/config file
-
-If you did not touch any of those, you do not need to run it.
-
-## The loop
+## Phase 2: Automated static scan and skill audit
 
 ```bash
-# 1. Scan (a whole-repo scan finishes in well under a second)
-npx github:avivgerz-hue/vibe-shield scan --fail-on high
-
-# 2. If it fails, generate the machine-readable fix list
-npx github:avivgerz-hue/vibe-shield scan --fix-prompt
-
-# 3. Read SECURITY_PATCH_PROMPT.md and fix every finding, critical first
-#    Each entry has the exact file:line, the vulnerable snippet, the CWE and
-#    the required change. Apply it literally.
-
-# 4. Re-run until it exits 0
-npx github:avivgerz-hue/vibe-shield scan --fail-on high
+npx -y @vibefoundry/vibe-shield scan . --format json
+npx -y @vibefoundry/vibe-shield audit-skills . --format json
 ```
 
-`--fail-on high` exits non-zero while any high or critical finding exists. That is the gate.
-
-## Reading a finding
+Inspect findings, inventory, ignored paths, and the files scanned. The explicit `.` includes test and documentation files: review fixtures as examples rather than blindly changing them. Use `explain <RULE_ID>` to investigate a rule. These commands run locally; first-time installation with npx requires registry access.
 
-```
-CRITICAL 47:15    VSB-CLIENT-001  Server-only secret exposed through a public environment prefix
-         const key = process.env.NEXT_PUBLIC_OPENAI_API_KEY;
-```
+## Phase 3: Deep contextual threat modeling
 
-| Part | Meaning |
-| --- | --- |
-| `47:15` | exact line and column to edit |
-| `VSB-CLIENT-001` | rule id — use it with `explain` for full docs |
-| message | why this specific line is exploitable |
-| `(CWE-200)` | bug class, for a deeper search if the fix is unclear |
+Trace untrusted input through authentication, ownership checks and tenant boundaries to database, filesystem, network, HTML, and LLM sinks. Inspect IDOR, business-logic bypasses, webhook signature verification and asynchronous jobs. Check cross-file guards and deployed database policies; absence of a static finding is not evidence of protection.
 
-Need the full picture? `npx github:avivgerz-hue/vibe-shield explain VSB-CLIENT-001` prints the vulnerable shape, the fixed shape, remediation steps and references.
+## Phase 4: Surgical zero-regression remediation
 
-## Hard rules
+- On Next.js mutation routes, authenticate the session on the server and authorize the target resource against the session principal before writes. Do not trust identity from request bodies.
+- Enable Supabase RLS and write action-specific policies using the authenticated principal; test both permitted and denied tenants before deploying migrations.
+- Validate inputs at the boundary with a schema such as Zod, then use parameterized database queries. Treat LLM output as untrusted.
+- Use explicit CORS allowlists, secure cookie flags and a CSP appropriate for the application. Test login, redirects, and browser behavior.
+- Report exposed credentials to the owner for provider-side rotation; avoid reproducing their values in reports. Do not suppress findings or weaken controls to obtain a higher score. Ask for missing business or deployment decisions.
 
-1. **Fix the root cause.** Never delete an auth check, disable RLS, silence a log or add a catch-all `catch {}` to make the finding disappear.
-2. **Never suppress.** Do not add `// vibe-shield-disable`, do not edit `.vibe-shieldignore`, do not pass `--ignore`. Suppression is a decision for the human.
-3. **Rotate exposed credentials.** If the scan reported a live key, tell the user to rotate it at the provider in the same message. Removing the line does not un-leak it — the value may already be in a bundle, a cache or a git history.
-4. **Report honestly.** If you cannot fix a finding (you need a decision, a credential or a provider change), say so explicitly, name the rule id, and stop.
-5. **Re-verify.** A fix is not finished until the gate exits 0.
+## Phase 5: Verification gate
 
-## Agent surface audit
-
-When you add or modify a skill, rule file, MCP server or instruction file, also run:
+Run project tests and both audits again. Aim for 100/100 Grade A+ with no high or critical findings, but report any unresolved finding, exclusion, false positive, or verification limitation honestly rather than claiming success. Never equate a clean score with a complete security assessment.
 
 ```bash
-npx github:avivgerz-hue/vibe-shield audit-skills
+npx -y @vibefoundry/vibe-shield scan --fail-on high
+npx -y @vibefoundry/vibe-shield audit-skills --fail-on high
 ```
 
-Twelve `VSB-AGENT-*` rules check for hidden Unicode (zero-width and bidi characters used to smuggle instructions past review), `curl`/`wget` exfiltration of environment variables, credential-harvesting instructions (`.env`, `~/.ssh`, `~/.aws`), registry-tag or remote MCP servers, literal tokens in an `env` block, safety-override language, over-broad tool permissions, base64 `eval` payloads, remote-instruction fetching, wildcard `allowed-tools`, and shell injection in skill scripts.
-
-Each finding carries a `triage` field: `block` means refuse and escalate, `review` means ask the user, `report` means mention it and continue. Do not blanket-refuse a repository because a rule fired — read the triage.
-
-## Flags worth knowing
-
-| Flag | Effect |
-| --- | --- |
-| `--format json` | full machine-readable report (schemaVersion 1) |
-| `--format sarif` | SARIF 2.1.0 for GitHub code scanning |
-| `--format compact` | one line per finding |
-| `--format github` | inline GitHub Actions annotations |
-| `--severity high` | only report high and critical |
-| `--fail-on medium` | stricter gate |
-| `--include-tests` | include test and fixture files |
-| `--cache` | reuse results between runs |
-| `--quiet` | one-line verdict (ideal for piping) |
-| `rules` | list every rule |
-| `explain <RULE_ID>` | full documentation for one rule |
+## Phase 6: Executive security sign-off
 
-If the repository has a `.mcp.json`, the same three capabilities are also
-available as MCP tools — `vibe_shield_scan`, `vibe_shield_audit_skills` and
-`vibe_shield_explain_rule`. Prefer those when they are listed, because they
-return structured findings instead of text you have to parse.
-
-## Definition of done
-
-- [ ] `npx github:avivgerz-hue/vibe-shield scan --fail-on high` exits `0`
-- [ ] `npx github:avivgerz-hue/vibe-shield audit-skills` exits `0` if you touched agent files
-- [ ] every credential the scan surfaced has been flagged to the user for rotation
-- [ ] no suppression directive was added
-- [ ] the feature still works and the existing tests still pass
-
-## Install it into a repository
+Produce a Markdown or HTML report with scope, inventory, risks prioritized by severity, evidence, actions, test results and remaining uncertainty. Illustrative code examples are not project-specific patches; review and adapt them. Obtain human approval before deployment or provider-side action.
 
 ```bash
-npx github:avivgerz-hue/vibe-shield init
+npx -y @vibefoundry/vibe-shield scan --report SECURITY-REPORT.md --patch-prompt PATCH-PROMPT.md
+npx -y @vibefoundry/vibe-shield audit-skills --report AGENT-REPORT.html
 ```
-
-That writes this file to `.claude/skills/vibe-shield/SKILL.md`, appends a security
-gate section to `AGENTS.md`, adds a `.cursor/rules/vibe-shield.mdc`, and installs a
-GitHub Actions workflow that fails the pull request on new high or critical
-findings. Every future task in that repository starts guarded.

package/dist/bin/vibe-shield.d.ts

@@ -32,7 +32,7 @@ export declare const defaultIo: () => CliIo;
 export declare const EXIT_OK = 0;
 export declare const EXIT_FINDINGS = 1;
 export declare const EXIT_USAGE = 2;
-declare const HELP = "vibe-shield \u2014 security scanner for AI-generated code\n\nUSAGE\n  vibe-shield <command> [options]\n\nCOMMANDS\n  scan [paths...]        Scan the project (default: current directory).\n  audit-skills [paths...]  Audit agent skills, Cursor rules, AGENTS.md and MCP configs.\n  init                   Install the Agent Skill, AGENTS.md section and CI workflow.\n  rules                  List every detection rule.\n  explain <RULE_ID>      Show full documentation for a rule.\n  mcp                    Serve the Model Context Protocol tools over stdio.\n  version                Print the version.\n  help                   Print this help.\n\nSCAN OPTIONS\n  --format <fmt>         console | compact | summary | json | sarif | github   (console)\n  --out <file>           Write the report to a file instead of stdout.\n  --fix-prompt           Write SECURITY_PATCH_PROMPT.md with exact fix instructions.\n  --fail-on <severity>   Exit 1 when a finding at/above this severity exists. (critical)\n  --severity <severity>  Only report findings at/above this severity.\n  --rules <ids>          Comma-separated rule ids/slugs (supports VSB-DB-*).\n  --ignore <glob>        Extra gitignore-style pattern (repeatable).\n  --include-tests        Include test, spec and fixture files.\n  --include-docs         Include Markdown and docs/.\n  --cache                Reuse .vibe-shield-cache.json between runs.\n  --max-findings <n>     Limit the console list (0 = all).   (50)\n  --quiet                Print only the verdict line and the exit code.\n  --no-color             Disable ANSI colour.\n  --no-shield-ignore     Ignore .vibe-shieldignore (e.g. to scan excluded fixtures).\n  --json                 Shorthand for --format json.\n\nINIT OPTIONS\n  --target <dir>         Repository to install into.          (cwd)\n  --agent <kind>         claude | cursor | generic | all.      (all)\n  --no-workflow          Skip the GitHub Actions workflow.\n  --force                Overwrite existing files.\n  --yes                  Accepted for non-interactive CI use (init never prompts).\n\nEXAMPLES\n  npx github:avivgerz-hue/vibe-shield scan\n  npx github:avivgerz-hue/vibe-shield scan --fail-on high --format github\n  npx github:avivgerz-hue/vibe-shield scan --fix-prompt\n  npx github:avivgerz-hue/vibe-shield init\n  npx github:avivgerz-hue/vibe-shield explain VSB-DB-001\n  npx github:avivgerz-hue/vibe-shield audit-skills .claude\n";
+declare const HELP = "vibe-shield \u2014 security scanner for AI-generated code\n\nUSAGE\n  vibe-shield <command> [options]\n\nCOMMANDS\n  scan [paths...]        Scan the project (default: current directory).\n  audit-skills [paths...]  Audit agent skills, Cursor rules, AGENTS.md and MCP configs.\n  init                   Install the Agent Skill, AGENTS.md section and CI workflow.\n  rules                  List every detection rule.\n  explain <RULE_ID>      Show full documentation for a rule.\n  mcp                    Serve the Model Context Protocol tools over stdio.\n  version                Print the version.\n  help                   Print this help.\n\nSCAN OPTIONS\n  --format <fmt>         console | compact | summary | json | sarif | github | markdown | html\n  --out <file>           Write the report to a file.\n  --report <file>        Write a report (format inferred from extension).\n  --patch-prompt <file>  Write a remediation prompt to this file.\n  --fix-prompt           Write SECURITY_PATCH_PROMPT.md with exact fix instructions.\n  --fail-on <severity>   Exit 1 when a finding at/above this severity exists. (critical)\n  --severity <severity>  Only report findings at/above this severity.\n  --rules <ids>          Comma-separated rule ids/slugs (supports VSB-DB-*).\n  --ignore <glob>        Extra gitignore-style pattern (repeatable).\n  --include-tests        Include test, spec and fixture files.\n  --include-docs         Include Markdown and docs/.\n  --cache                Reuse .vibe-shield-cache.json between runs.\n  --max-findings <n>     Limit the console list (0 = all).   (50)\n  --quiet                Print only the verdict line and the exit code.\n  --no-color             Disable ANSI colour.\n  --no-shield-ignore     Ignore .vibe-shieldignore (e.g. to scan excluded fixtures).\n  --json                 Shorthand for --format json.\n\nINIT OPTIONS\n  --target <dir>         Repository to install into.          (cwd)\n  --agent <kind>         claude | cursor | generic | all.      (all)\n  --no-workflow          Skip the GitHub Actions workflow.\n  --force                Overwrite existing files.\n  --yes                  Accepted for non-interactive CI use (init never prompts).\n\nEXAMPLES\n  npx -y @vibefoundry/vibe-shield scan\n  npx -y @vibefoundry/vibe-shield scan --fail-on high --format github\n  npx -y @vibefoundry/vibe-shield scan --fix-prompt\n  npx -y @vibefoundry/vibe-shield init\n  npx -y @vibefoundry/vibe-shield explain VSB-DB-001\n  npx -y @vibefoundry/vibe-shield audit-skills .claude\n";
 interface ParsedArgs {
     command: string;
     positionals: string[];