@vibefoundry/vibe-shield 1.1.1 → 2.0.0

package/README.md

@@ -14,7 +14,7 @@ vibe-shield is a **static security scanner built for that failure mode**, plus a
 [![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
@@ -27,6 +27,26 @@ npx -y @vibefoundry/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":
@@ -45,7 +65,7 @@ It works. It also has **three critical vulnerabilities** — no authentication,
 `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,7 +81,7 @@ 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 -y @vibefoundry/vibe-shield scan --fix-prompt    # writes SECURITY_PATCH_PROMPT.md for your agent
@@ -126,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 -y @vibefoundry/vibe-shield rules` or `npx -y @vibefoundry/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-*`
 
@@ -243,7 +263,7 @@ 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 |
 
@@ -254,7 +274,7 @@ Three tools:
 {
   "mcpServers": {
     "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
-    "vibe-shield": { "command": "npx", "args": ["--yes", "@vibefoundry/vibe-shield@1.1.0", "mcp"] }
+    "vibe-shield": { "command": "npx", "args": ["--yes", "@vibefoundry/vibe-shield@1.1.1", "mcp"] }
   }
 }
 ```
@@ -392,12 +412,12 @@ This repository runs its own gate on every commit and in CI:
 
 ```console
 $ npx -y @vibefoundry/vibe-shield scan
-🛡️  vibe-shield v1.0.0 · security 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. 🛡️
 
@@ -441,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
@@ -471,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` |

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.
+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 -y @vibefoundry/vibe-shield scan --fail-on high
-
-# 2. If it fails, generate the machine-readable fix list
-npx -y @vibefoundry/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 -y @vibefoundry/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
-
-```
-CRITICAL 47:15    VSB-CLIENT-001  Server-only secret exposed through a public environment prefix
-         const key = process.env.NEXT_PUBLIC_OPENAI_API_KEY;
-```
+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.
 
-| 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 |
+## Phase 3: Deep contextual threat modeling
 
-Need the full picture? `npx -y @vibefoundry/vibe-shield explain VSB-CLIENT-001` prints the vulnerable shape, the fixed shape, remediation steps and references.
+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.
 
-## Hard rules
+## Phase 4: Surgical zero-regression remediation
 
-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.
+- 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.
 
-## Agent surface audit
+## Phase 5: Verification gate
 
-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 -y @vibefoundry/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
+## Phase 6: Executive security sign-off
 
-| 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 |
-
-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 -y @vibefoundry/vibe-shield scan --fail-on high` exits `0`
-- [ ] `npx -y @vibefoundry/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 -y @vibefoundry/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 -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";
+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[];

package/dist/bin/vibe-shield.js

@@ -94,8 +94,10 @@ COMMANDS
   help                   Print this help.
 
 SCAN OPTIONS
-  --format <fmt>         console | compact | summary | json | sarif | github   (console)
-  --out <file>           Write the report to a file instead of stdout.
+  --format <fmt>         console | compact | summary | json | sarif | github | markdown | html
+  --out <file>           Write the report to a file.
+  --report <file>        Write a report (format inferred from extension).
+  --patch-prompt <file>  Write a remediation prompt to this file.
   --fix-prompt           Write ${patch_prompt_writer_1.PATCH_PROMPT_FILENAME} with exact fix instructions.
   --fail-on <severity>   Exit 1 when a finding at/above this severity exists. (critical)
   --severity <severity>  Only report findings at/above this severity.
@@ -130,6 +132,7 @@ const BOOLEAN_FLAGS = new Set([
     // `--mcp` is an alias for the `mcp` subcommand, so `npx -y
     // @vibefoundry/vibe-shield --mcp` works the way most MCP clients expect.
     'mcp',
+    'version',
     'fix-prompt',
     'include-tests',
     'include-docs',
@@ -150,6 +153,8 @@ const BOOLEAN_FLAGS = new Set([
 const VALUE_FLAGS = new Set([
     'format',
     'out',
+    'report',
+    'patch-prompt',
     'fail-on',
     'severity',
     'rules',
@@ -236,9 +241,10 @@ async function emitReport(result, io, options, parsed) {
     if (noColor)
         color.enabled = false;
     let patchPath = null;
-    if (options.fixPrompt) {
+    if (options.fixPrompt || flagString(parsed, 'patch-prompt')) {
         patchPath = await (0, patch_prompt_writer_1.writePatchPrompt)(result, {
             outDir: io.cwd,
+            fileName: flagString(parsed, 'patch-prompt'),
             minSeverity: ((0, types_1.isSeverity)(flagString(parsed, 'severity')) ? flagString(parsed, 'severity') : 'info'),
         });
     }
@@ -262,11 +268,17 @@ async function emitReport(result, io, options, parsed) {
     if (patchPath) {
         write(io, 'stderr', `\n📝 Wrote ${path.relative(io.cwd, patchPath) || patchPath} — hand it to your agent, or run \`npx -y @vibefoundry/vibe-shield scan\` after fixing.\n`);
     }
-    if (options.out) {
-        const target = path.resolve(io.cwd, options.out);
+    const reportPath = flagString(parsed, 'report');
+    const outputPath = reportPath ?? options.out;
+    if (outputPath) {
+        const target = path.resolve(io.cwd, outputPath);
         const { promises: fs } = await Promise.resolve().then(() => __importStar(require('node:fs')));
-        await fs.writeFile(target, (0, formatters_1.formatResult)(result, options.format === 'console' ? 'json' : options.format), 'utf8');
-        write(io, 'stderr', `📄 Report written to ${options.out}\n`);
+        const inferred = { '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.sarif': 'sarif', '.json': 'json' }[path.extname(outputPath).toLowerCase()];
+        const fileFormat = reportPath && !flagString(parsed, 'format') ? inferred : options.format === 'console' ? 'json' : options.format;
+        if (!fileFormat)
+            throw new Error('Cannot infer report format from extension; use --format.');
+        await fs.writeFile(target, (0, formatters_1.formatResult)(result, fileFormat), 'utf8');
+        write(io, 'stderr', `📄 Report written to ${outputPath}\n`);
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -300,9 +312,15 @@ async function commandScan(parsed, io) {
         write(io, 'stderr', `vibe-shield: no such file or directory: ${missing.join(', ')}\n`);
         return exports.EXIT_USAGE;
     }
+    // For a single directory outside cwd, report paths relative to that project,
+    // and discover its own config, middleware and migrations.
+    const target = parsed.positionals.length === 1 ? path.resolve(io.cwd, parsed.positionals[0]) : '';
+    const outside = target && (path.relative(io.cwd, target) === '..' || path.relative(io.cwd, target).startsWith(`..${path.sep}`));
+    const externalRoot = outside ? ((0, node_fs_1.statSync)(target).isDirectory() ? target : path.dirname(target)) : undefined;
+    const externalPaths = externalRoot ? [path.relative(externalRoot, target) || '.'] : undefined;
     const result = await (0, engine_1.scanProject)({
-        rootDir: io.cwd,
-        paths: parsed.positionals.length ? parsed.positionals : undefined,
+        rootDir: externalRoot ?? io.cwd,
+        paths: externalPaths ?? (parsed.positionals.length ? parsed.positionals : undefined),
         rules,
         ignorePatterns: (flagString(parsed, 'ignore') ?? '').split('\n').filter(Boolean),
         // `undefined` means "use the engine default" (which is: include everything
@@ -346,8 +364,12 @@ async function commandAuditSkills(parsed, io) {
         write(io, 'stderr', `vibe-shield: --fail-on expects one of: critical, high, medium, low, info\n`);
         return exports.EXIT_USAGE;
     }
-    const result = await (0, skill_auditor_1.auditSkills)(io.cwd, {
-        paths: parsed.positionals.length ? parsed.positionals : undefined,
+    const target = parsed.positionals.length === 1 ? path.resolve(io.cwd, parsed.positionals[0]) : '';
+    const relative = target ? path.relative(io.cwd, target) : '';
+    const outside = relative === '..' || relative.startsWith(`..${path.sep}`);
+    const externalRoot = outside && (0, node_fs_1.existsSync)(target) && (0, node_fs_1.statSync)(target).isDirectory() ? target : undefined;
+    const result = await (0, skill_auditor_1.auditSkills)(externalRoot ?? io.cwd, {
+        paths: externalRoot ? undefined : parsed.positionals.length ? parsed.positionals : undefined,
         version: await (0, engine_1.packageVersion)(),
     });
     await emitReport(result, io, {
@@ -414,6 +436,7 @@ function commandRules(parsed, io) {
             severity: rule.severity,
             confidence: rule.confidence,
             cwe: rule.cwe.id,
+            owasp: rule.owasp,
             description: rule.description,
             remediation: rule.remediation,
             references: rule.references,
@@ -470,6 +493,10 @@ function commandExplain(parsed, io) {
         out.push(`  ${color.cyan(reference)}`);
     out.push('');
     out.push(color.dim(`CWE: ${rule.cwe.name} — ${rule.cwe.url}`));
+    if (rule.owasp?.web)
+        out.push(color.dim(`OWASP: ${rule.owasp.web.id} ${rule.owasp.web.name} (${rule.owasp.web.basis})`));
+    if (rule.owasp?.llm.length)
+        out.push(color.dim(`OWASP LLM: ${rule.owasp.llm.map(m => `${m.id} ${m.name}`).join(', ')} (contextual)`));
     out.push('');
     write(io, 'stdout', `${out.join('\n')}\n`);
     return exports.EXIT_OK;

package/dist/src/init/scaffold.d.ts

@@ -54,7 +54,7 @@ export interface InitResult {
     blocked: string[];
     warnings: string[];
 }
-export declare const SKILL_TEMPLATE = "---\nname: vibe-shield\ndescription: 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.\nallowed-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\nlicense: MIT\nmetadata:\n  author: VibeFoundry\n  homepage: https://github.com/avivgerz-hue/vibe-shield\n  version: 1.0.0\n---\n\n# vibe-shield\n\nYou are not allowed to say \"done\" until the code you just wrote passes a security audit.\n\nAI 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 \u2014 they are the default shape of code written quickly by something optimising for \"it works\". This skill is the second pair of eyes.\n\n## When to run\n\nRun the audit **after every change that touches**:\n\n- an API route, route handler, server action, RPC endpoint or GraphQL mutation\n- authentication, session, role, permission or ownership logic\n- a database migration, policy, grant, schema or Supabase table\n- an environment variable, config file, `.env*` file or build config\n- anything calling an LLM, a tool, a webhook, a shell command or the filesystem\n- `.claude/`, `.cursor/`, `AGENTS.md`, `mcp.json` or any skill/config file\n\nIf you did not touch any of those, you do not need to run it.\n\n## The loop\n\n```bash\n# 1. Scan (a whole-repo scan finishes in well under a second)\nnpx -y @vibefoundry/vibe-shield scan --fail-on high\n\n# 2. If it fails, generate the machine-readable fix list\nnpx -y @vibefoundry/vibe-shield scan --fix-prompt\n\n# 3. Read SECURITY_PATCH_PROMPT.md and fix every finding, critical first\n#    Each entry has the exact file:line, the vulnerable snippet, the CWE and\n#    the required change. Apply it literally.\n\n# 4. Re-run until it exits 0\nnpx -y @vibefoundry/vibe-shield scan --fail-on high\n```\n\n`--fail-on high` exits non-zero while any high or critical finding exists. That is the gate.\n\n## Reading a finding\n\n```\nCRITICAL 47:15    VSB-CLIENT-001  Server-only secret exposed through a public environment prefix\n         const key = process.env.NEXT_PUBLIC_OPENAI_API_KEY;\n```\n\n| Part | Meaning |\n| --- | --- |\n| `47:15` | exact line and column to edit |\n| `VSB-CLIENT-001` | rule id \u2014 use it with `explain` for full docs |\n| message | why this specific line is exploitable |\n| `(CWE-200)` | bug class, for a deeper search if the fix is unclear |\n\nNeed the full picture? `npx -y @vibefoundry/vibe-shield explain VSB-CLIENT-001` prints the vulnerable shape, the fixed shape, remediation steps and references.\n\n## Hard rules\n\n1. **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.\n2. **Never suppress.** Do not add `// vibe-shield-disable`, do not edit `.vibe-shieldignore`, do not pass `--ignore`. Suppression is a decision for the human.\n3. **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 \u2014 the value may already be in a bundle, a cache or a git history.\n4. **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.\n5. **Re-verify.** A fix is not finished until the gate exits 0.\n\n## Agent surface audit\n\nWhen you add or modify a skill, rule file, MCP server or instruction file, also run:\n\n```bash\nnpx -y @vibefoundry/vibe-shield audit-skills\n```\n\nTwelve `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.\n\nEach 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 \u2014 read the triage.\n\n## Flags worth knowing\n\n| Flag | Effect |\n| --- | --- |\n| `--format json` | full machine-readable report (schemaVersion 1) |\n| `--format sarif` | SARIF 2.1.0 for GitHub code scanning |\n| `--format compact` | one line per finding |\n| `--format github` | inline GitHub Actions annotations |\n| `--severity high` | only report high and critical |\n| `--fail-on medium` | stricter gate |\n| `--include-tests` | include test and fixture files |\n| `--cache` | reuse results between runs |\n| `--quiet` | one-line verdict (ideal for piping) |\n| `rules` | list every rule |\n| `explain <RULE_ID>` | full documentation for one rule |\n\nIf the repository has a `.mcp.json`, the same three capabilities are also\navailable as MCP tools \u2014 `vibe_shield_scan`, `vibe_shield_audit_skills` and\n`vibe_shield_explain_rule`. Prefer those when they are listed, because they\nreturn structured findings instead of text you have to parse.\n\n## Definition of done\n\n- [ ] `npx -y @vibefoundry/vibe-shield scan --fail-on high` exits `0`\n- [ ] `npx -y @vibefoundry/vibe-shield audit-skills` exits `0` if you touched agent files\n- [ ] every credential the scan surfaced has been flagged to the user for rotation\n- [ ] no suppression directive was added\n- [ ] the feature still works and the existing tests still pass\n\n## Install it into a repository\n\n```bash\nnpx -y @vibefoundry/vibe-shield init\n```\n\nThat writes this file to `.claude/skills/vibe-shield/SKILL.md`, appends a security\ngate section to `AGENTS.md`, adds a `.cursor/rules/vibe-shield.mdc`, and installs a\nGitHub Actions workflow that fails the pull request on new high or critical\nfindings. Every future task in that repository starts guarded.\n";
+export declare const SKILL_TEMPLATE = "---\nname: vibe-shield\ndescription: 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.\nallowed-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\nlicense: MIT\nmetadata:\n  author: VibeFoundry\n  homepage: https://github.com/avivgerz-hue/vibe-shield\n  version: 2.0.0\n---\n\n# Defensive AppSec architect protocol\n\nWork 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.\n\n## Phase 1: Attack-surface reconnaissance\n\nMap 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.\n\n## Phase 2: Automated static scan and skill audit\n\n```bash\nnpx -y @vibefoundry/vibe-shield scan . --format json\nnpx -y @vibefoundry/vibe-shield audit-skills . --format json\n```\n\nInspect 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.\n\n## Phase 3: Deep contextual threat modeling\n\nTrace 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.\n\n## Phase 4: Surgical zero-regression remediation\n\n- 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.\n- Enable Supabase RLS and write action-specific policies using the authenticated principal; test both permitted and denied tenants before deploying migrations.\n- Validate inputs at the boundary with a schema such as Zod, then use parameterized database queries. Treat LLM output as untrusted.\n- Use explicit CORS allowlists, secure cookie flags and a CSP appropriate for the application. Test login, redirects, and browser behavior.\n- 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.\n\n## Phase 5: Verification gate\n\nRun 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.\n\n```bash\nnpx -y @vibefoundry/vibe-shield scan --fail-on high\nnpx -y @vibefoundry/vibe-shield audit-skills --fail-on high\n```\n\n## Phase 6: Executive security sign-off\n\nProduce 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.\n\n```bash\nnpx -y @vibefoundry/vibe-shield scan --report SECURITY-REPORT.md --patch-prompt PATCH-PROMPT.md\nnpx -y @vibefoundry/vibe-shield audit-skills --report AGENT-REPORT.html\n```\n";
 export declare const AGENTS_SECTION = "## Security gate (vibe-shield)\n\nThis repository is guarded by [vibe-shield](https://github.com/avivgerz-hue/vibe-shield).\n\nBefore you report any task as complete:\n\n1. Run `npx -y @vibefoundry/vibe-shield scan --fail-on high` and fix every finding it reports.\n2. Never suppress a finding (`vibe-shield-disable`, `.vibe-shieldignore` edits,\n   `--ignore`) to make the gate pass \u2014 that is the human's call.\n3. If you touched `.claude/`, `.cursor/`, `AGENTS.md`, `mcp.json` or a skill,\n   also run `npx -y @vibefoundry/vibe-shield audit-skills`.\n4. Surface any exposed credential to the user for rotation. Do not \"fix\" it by\n   deleting the line and moving on.\n\nThe gate exists because the most common way AI-written code reaches production\nwith a leaked `SUPABASE_SERVICE_ROLE_KEY` or an unauthenticated `DELETE`\nendpoint is that nobody asked it a second question.\n";
 /** Key this tool owns inside `mcpServers`; nothing else is ever touched. */
 export declare const MCP_SERVER_KEY = "vibe-shield";