@vibefoundry/vibe-shield 1.1.0 → 2.0.0

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

@@ -1,5 +1,5 @@
 /**
- * vibe-shield :: `npx github:avivgerz-hue/vibe-shield init`
+ * vibe-shield :: `npx -y @vibefoundry/vibe-shield init`
  * -------------------------------------
  * One command turns any repository into a guarded one. It installs:
  *
@@ -36,14 +36,14 @@ export interface InitOptions {
     force?: boolean;
     /** Print what would happen without writing. */
     dryRun?: boolean;
-    /** Pin a specific version in the workflow (default `latest`). */
-    version?: string;
     /**
-     * Commit to pin the `.mcp.json` entry to. Resolved from the installed package
-     * when omitted; see `resolveInstallRev`.
+     * Version to pin in both the workflow and the `.mcp.json` entry.
+     *
+     * Resolved from the installed package when omitted; see
+     * `packageVersionFromDisk`.
      */
-    rev?: string | null;
-    /** Environment to read the revision override from. Defaults to `process.env`. */
+    version?: string | null;
+    /** Environment to read the version override from. Defaults to `process.env`. */
     env?: NodeJS.ProcessEnv;
 }
 export interface InitResult {
@@ -54,8 +54,8 @@ 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 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\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 github:avivgerz-hue/vibe-shield scan --fail-on high\n\n# 2. If it fails, generate the machine-readable fix list\nnpx github:avivgerz-hue/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 github:avivgerz-hue/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 github:avivgerz-hue/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 github:avivgerz-hue/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 github:avivgerz-hue/vibe-shield scan --fail-on high` exits `0`\n- [ ] `npx github:avivgerz-hue/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 github:avivgerz-hue/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 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 github:avivgerz-hue/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 github:avivgerz-hue/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";
+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";
 /**
@@ -64,19 +64,23 @@ export declare const MCP_SERVER_KEY = "vibe-shield";
  * `npx` is used rather than a local path so the config keeps working when the
  * project is cloned elsewhere or the package is upgraded.
  *
- * The spec carries a `#<commit>` pin when `init` can determine one. A bare
- * `github:owner/repo` re-resolves to the default branch head on every fresh
- * install, so a mixed commit could change what runs the next time the server
- * starts. Pin the commit that wrote this file and upgrades become explicit
- * (`init --force` rewrites it).
+ * The spec is always pinned to an exact version — `@vibefoundry/vibe-shield@1.1.0`.
+ * Two reasons: a bare name re-resolves to whatever `latest` points at on every
+ * launch, and vibe-shield's own `VSB-AGENT-004` rule flags an unpinned `npx -y`
+ * server as high severity. Pinning keeps the gate at A+ for projects that adopt
+ * the tool, and upgrades become explicit (`init --force` rewrites the pin).
  */
-export declare const MCP_SERVER_SPEC = "github:avivgerz-hue/vibe-shield";
-/** Build the `.mcp.json` entry, pinned to `rev` when one is known. */
-export declare function mcpServerEntry(rev?: string | null): {
+export declare const MCP_SERVER_SPEC = "@vibefoundry/vibe-shield";
+/** Build the `.mcp.json` entry, pinned to `version` when one is known. */
+export declare function mcpServerEntry(version?: string | null): {
     command: string;
     args: string[];
 };
-/** The unpinned entry, kept for callers that have no commit available. */
+/**
+ * The entry as this install writes it: pinned to the running package version.
+ * Falls back to unpinned only in a stripped checkout where no `package.json`
+ * names this package, which is the one case where no version is knowable.
+ */
 export declare const MCP_SERVER_ENTRY: {
     command: string;
     args: string[];
@@ -91,28 +95,22 @@ export declare const MCP_SERVER_ENTRY: {
  * rewriting someone's MCP config could break every server they run.
  */
 /**
- * Find the commit of the running install, so `.mcp.json` can pin it.
- *
- * Deliberately conservative: returns `null` rather than guessing, because a
- * wrong pin is worse than no pin (it would silently freeze the server on an
- * unrelated commit). The revision is only derivable when the CLI is running
- * from inside an npm install of this package, which is the `npx github:` case.
+ * The version of the running install, used to pin `.mcp.json`.
  *
- * Order:
- *   1. `VIBE_SHIELD_REV` — an explicit override, used by tests and CI.
- *   2. The `resolved` field npm records in the *parent* project's lockfile.
- *   3. `/app/.rev` — written into the container image at build time.
+ * Read from the nearest `package.json` that names this package. Falls back to
+ * the range in `package.json` only if nothing is found, which keeps `init`
+ * working in a stripped-down checkout rather than writing a nameless spec.
  */
-export declare function resolveInstallRev(rootDir?: string, env?: NodeJS.ProcessEnv): Promise<string | null>;
+export declare function packageVersionFromDisk(): string | null;
 export declare function mergeMcpConfig(existing: string | null, options?: {
     force?: boolean;
-    rev?: string | null;
+    version?: string | null;
 }): {
     contents: string;
     changed: boolean;
     error?: string;
 };
-export declare const WORKFLOW_TEMPLATE = "name: vibe-shield\n\non:\n  push:\n    branches: [main, master]\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  security-events: write\n  pull-requests: write\n\njobs:\n  scan:\n    name: Security audit\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 20\n\n      - name: Scan for vulnerabilities\n        run: npx --yes github:avivgerz-hue/vibe-shield scan --format sarif --out vibe-shield.sarif --fail-on high\n        continue-on-error: true\n\n      - name: Upload SARIF to code scanning\n        if: always()\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: vibe-shield.sarif\n          category: vibe-shield\n\n      - name: Audit agent surface\n        run: npx --yes github:avivgerz-hue/vibe-shield audit-skills --fail-on high\n\n      - name: Enforce the gate\n        run: npx --yes github:avivgerz-hue/vibe-shield scan --fail-on high --quiet\n";
+export declare const WORKFLOW_TEMPLATE = "name: vibe-shield\n\non:\n  push:\n    branches: [main, master]\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  security-events: write\n  pull-requests: write\n\njobs:\n  scan:\n    name: Security audit\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 20\n\n      - name: Scan for vulnerabilities\n        run: npx -y @vibefoundry/vibe-shield scan --format sarif --out vibe-shield.sarif --fail-on high\n        continue-on-error: true\n\n      - name: Upload SARIF to code scanning\n        if: always()\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: vibe-shield.sarif\n          category: vibe-shield\n\n      - name: Audit agent surface\n        run: npx -y @vibefoundry/vibe-shield audit-skills --fail-on high\n\n      - name: Enforce the gate\n        run: npx -y @vibefoundry/vibe-shield scan --fail-on high --quiet\n";
 export declare const IGNORE_TEMPLATE = "# .vibe-shieldignore \u2014 gitignore syntax.\n#\n# Keep this file as short as possible: every line hides real code from the\n# security gate. Prefer an inline suppression with a reason where it applies:\n#\n#   // vibe-shield-disable-next-line VSB-AI-001 -- path comes from a fixed enum\n#\n# Generated code, vendored third-party sources and build output are the only\n# good reasons to ignore a path wholesale.\n\n# Generated / vendored\n# vendor/**\n# **/*.generated.ts\n# **/__generated__/**\n\n# Local-only scratch work\n# scratch/**\n";
 /** Build the full set of files for a given target repository. */
 export declare function buildScaffold(options: InitOptions): ScaffoldFile[];

package/dist/src/init/scaffold.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * vibe-shield :: `npx github:avivgerz-hue/vibe-shield init`
+ * vibe-shield :: `npx -y @vibefoundry/vibe-shield init`
  * -------------------------------------
  * One command turns any repository into a guarded one. It installs:
  *
@@ -50,7 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IGNORE_TEMPLATE = exports.WORKFLOW_TEMPLATE = exports.MCP_SERVER_ENTRY = exports.MCP_SERVER_SPEC = exports.MCP_SERVER_KEY = exports.AGENTS_SECTION = exports.SKILL_TEMPLATE = void 0;
 exports.mcpServerEntry = mcpServerEntry;
-exports.resolveInstallRev = resolveInstallRev;
+exports.packageVersionFromDisk = packageVersionFromDisk;
 exports.mergeMcpConfig = mergeMcpConfig;
 exports.buildScaffold = buildScaffold;
 exports.installScaffold = installScaffold;
@@ -58,134 +58,67 @@ exports.locateBundledSkill = locateBundledSkill;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
 const shared_1 = require("../scanner/rules/shared");
-const BANNER = '<!-- Managed by vibe-shield. Edit freely; `npx github:avivgerz-hue/vibe-shield init --force` regenerates this file. -->';
+const BANNER = '<!-- Managed by vibe-shield. Edit freely; `npx -y @vibefoundry/vibe-shield init --force` regenerates this file. -->';
 /* -------------------------------------------------------------------------- */
 /* SKILL.md                                                                   */
 /* -------------------------------------------------------------------------- */
 exports.SKILL_TEMPLATE = `---
 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.
+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.
 
-## Reading a finding
+## Phase 3: Deep contextual threat modeling
 
-\`\`\`
-CRITICAL 47:15    VSB-CLIENT-001  Server-only secret exposed through a public environment prefix
-         const key = process.env.NEXT_PUBLIC_OPENAI_API_KEY;
-\`\`\`
-
-| 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 |
-
-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.
+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 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.
 `;
 /* -------------------------------------------------------------------------- */
 /* AGENTS.md section                                                          */
@@ -196,11 +129,11 @@ This repository is guarded by [vibe-shield](https://github.com/avivgerz-hue/vibe
 
 Before you report any task as complete:
 
-1. Run \`npx github:avivgerz-hue/vibe-shield scan --fail-on high\` and fix every finding it reports.
+1. Run \`npx -y @vibefoundry/vibe-shield scan --fail-on high\` and fix every finding it reports.
 2. Never suppress a finding (\`vibe-shield-disable\`, \`.vibe-shieldignore\` edits,
    \`--ignore\`) to make the gate pass — that is the human's call.
 3. If you touched \`.claude/\`, \`.cursor/\`, \`AGENTS.md\`, \`mcp.json\` or a skill,
-   also run \`npx github:avivgerz-hue/vibe-shield audit-skills\`.
+   also run \`npx -y @vibefoundry/vibe-shield audit-skills\`.
 4. Surface any exposed credential to the user for rotation. Do not "fix" it by
    deleting the line and moving on.
 
@@ -219,20 +152,24 @@ exports.MCP_SERVER_KEY = 'vibe-shield';
  * `npx` is used rather than a local path so the config keeps working when the
  * project is cloned elsewhere or the package is upgraded.
  *
- * The spec carries a `#<commit>` pin when `init` can determine one. A bare
- * `github:owner/repo` re-resolves to the default branch head on every fresh
- * install, so a mixed commit could change what runs the next time the server
- * starts. Pin the commit that wrote this file and upgrades become explicit
- * (`init --force` rewrites it).
+ * The spec is always pinned to an exact version — `@vibefoundry/vibe-shield@1.1.0`.
+ * Two reasons: a bare name re-resolves to whatever `latest` points at on every
+ * launch, and vibe-shield's own `VSB-AGENT-004` rule flags an unpinned `npx -y`
+ * server as high severity. Pinning keeps the gate at A+ for projects that adopt
+ * the tool, and upgrades become explicit (`init --force` rewrites the pin).
  */
 exports.MCP_SERVER_SPEC = shared_1.SELF_GITHUB_SPEC;
-/** Build the `.mcp.json` entry, pinned to `rev` when one is known. */
-function mcpServerEntry(rev) {
-    const spec = rev ? `${exports.MCP_SERVER_SPEC}#${rev}` : exports.MCP_SERVER_SPEC;
+/** Build the `.mcp.json` entry, pinned to `version` when one is known. */
+function mcpServerEntry(version) {
+    const spec = version ? `${exports.MCP_SERVER_SPEC}@${version}` : exports.MCP_SERVER_SPEC;
     return { command: 'npx', args: ['--yes', spec, 'mcp'] };
 }
-/** The unpinned entry, kept for callers that have no commit available. */
-exports.MCP_SERVER_ENTRY = mcpServerEntry();
+/**
+ * The entry as this install writes it: pinned to the running package version.
+ * Falls back to unpinned only in a stripped checkout where no `package.json`
+ * names this package, which is the one case where no version is knowable.
+ */
+exports.MCP_SERVER_ENTRY = mcpServerEntry(packageVersionFromDisk());
 /**
  * Merge the vibe-shield server into an existing `.mcp.json` without disturbing
  * anything already there.
@@ -243,55 +180,34 @@ exports.MCP_SERVER_ENTRY = mcpServerEntry();
  * rewriting someone's MCP config could break every server they run.
  */
 /**
- * Find the commit of the running install, so `.mcp.json` can pin it.
- *
- * Deliberately conservative: returns `null` rather than guessing, because a
- * wrong pin is worse than no pin (it would silently freeze the server on an
- * unrelated commit). The revision is only derivable when the CLI is running
- * from inside an npm install of this package, which is the `npx github:` case.
+ * The version of the running install, used to pin `.mcp.json`.
  *
- * Order:
- *   1. `VIBE_SHIELD_REV` — an explicit override, used by tests and CI.
- *   2. The `resolved` field npm records in the *parent* project's lockfile.
- *   3. `/app/.rev` — written into the container image at build time.
+ * Read from the nearest `package.json` that names this package. Falls back to
+ * the range in `package.json` only if nothing is found, which keeps `init`
+ * working in a stripped-down checkout rather than writing a nameless spec.
  */
-async function resolveInstallRev(rootDir, env = process.env) {
-    const explicit = env.VIBE_SHIELD_REV?.trim();
-    if (explicit)
-        return explicit;
-    const shaPattern = /(?:[?#]([0-9a-f]{40}))\b/i;
-    // A lockfile one or two directories above this file, in an npm install.
+function packageVersionFromDisk() {
     let dir = __dirname;
-    for (let depth = 0; depth < 4; depth += 1) {
-        for (const name of ['package-lock.json', 'npm-shrinkwrap.json']) {
-            try {
-                const raw = await node_fs_1.promises.readFile(path.join(dir, name), 'utf8');
-                const match = raw.match(shaPattern);
-                if (match?.[1])
-                    return match[1];
-            }
-            catch {
-                // Keep walking.
+    for (let depth = 0; depth < 6; depth += 1) {
+        try {
+            const raw = (0, node_fs_1.readFileSync)(path.join(dir, 'package.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if ((parsed.name === shared_1.SELF_GITHUB_SPEC || parsed.name === 'vibe-shield') && parsed.version) {
+                return parsed.version;
             }
         }
+        catch {
+            // Keep walking up.
+        }
         const parent = path.dirname(dir);
         if (parent === dir)
             break;
         dir = parent;
     }
-    try {
-        const rev = (await node_fs_1.promises.readFile('/app/.rev', 'utf8')).trim();
-        if (/^[0-9a-f]{40}$/i.test(rev))
-            return rev;
-    }
-    catch {
-        // Not in the container image.
-    }
-    void rootDir;
     return null;
 }
 function mergeMcpConfig(existing, options = {}) {
-    const entry = mcpServerEntry(options.rev);
+    const entry = mcpServerEntry(options.version ?? packageVersionFromDisk());
     if (existing === null || existing.trim() === '') {
         return {
             contents: `${JSON.stringify({ mcpServers: { [exports.MCP_SERVER_KEY]: entry } }, null, 2)}\n`,
@@ -356,7 +272,7 @@ jobs:
           node-version: 20
 
       - name: Scan for vulnerabilities
-        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
 
       - name: Upload SARIF to code scanning
@@ -367,10 +283,10 @@ jobs:
           category: vibe-shield
 
       - name: Audit agent surface
-        run: npx --yes github:avivgerz-hue/vibe-shield audit-skills --fail-on high
+        run: npx -y @vibefoundry/vibe-shield audit-skills --fail-on high
 
       - name: Enforce the gate
-        run: npx --yes github:avivgerz-hue/vibe-shield scan --fail-on high --quiet
+        run: npx -y @vibefoundry/vibe-shield scan --fail-on high --quiet
 `;
 /* -------------------------------------------------------------------------- */
 /* .vibe-shieldignore                                                         */
@@ -406,7 +322,7 @@ ${BANNER}
 
 # Security gate
 
-Before reporting a task complete, run \`npx github:avivgerz-hue/vibe-shield scan --fail-on high\` and
+Before reporting a task complete, run \`npx -y @vibefoundry/vibe-shield scan --fail-on high\` and
 fix every finding. Never suppress a finding to make the gate pass. If the scan
 reports an exposed credential, tell the user to rotate it at the provider.
 `;
@@ -474,7 +390,7 @@ const exists = async (file) => {
 async function installScaffold(options) {
     const rootDir = path.resolve(options.rootDir);
     const result = { written: [], appended: [], skipped: [], blocked: [], warnings: [] };
-    const resolvedRev = options.rev === undefined ? await resolveInstallRev(rootDir, options.env) : options.rev;
+    const resolvedVersion = options.version ?? options.env?.VIBE_SHIELD_VERSION ?? packageVersionFromDisk();
     const files = buildScaffold(options);
     for (const file of files) {
         const absolute = path.join(rootDir, file.relativePath);
@@ -513,7 +429,7 @@ async function installScaffold(options) {
                     existing = null;
                 }
             }
-            const merged = mergeMcpConfig(existing, { force: options.force, rev: resolvedRev });
+            const merged = mergeMcpConfig(existing, { force: options.force, version: resolvedVersion });
             if (merged.error) {
                 // Not a `skipped` entry: `--force` cannot repair invalid JSON, so the
                 // summary must not suggest it can.
@@ -546,10 +462,10 @@ async function installScaffold(options) {
         await node_fs_1.promises.writeFile(absolute, file.contents, 'utf8');
         result.written.push(file.relativePath);
     }
-    // A repository without a package.json will not be able to `npx github:avivgerz-hue/vibe-shield`
+    // A repository without a package.json will not be able to `npx -y @vibefoundry/vibe-shield`
     // as a dev dependency; it still works through npx, so this is only a warning.
     if (!(await exists(path.join(rootDir, 'package.json')))) {
-        result.warnings.push('No package.json found — run the gate with `npx github:avivgerz-hue/vibe-shield scan`.');
+        result.warnings.push('No package.json found — run the gate with `npx -y @vibefoundry/vibe-shield scan`.');
     }
     if (!(await exists(path.join(rootDir, '.git')))) {
         result.warnings.push('No .git directory found — the workflow only runs once this is a git repository.');

package/dist/src/mcp/server.js

@@ -230,6 +230,7 @@ const toToolResult = (result, options) => {
             filesScanned: result.stats.filesScanned,
             durationMs: result.stats.durationMs,
             rootDir: result.rootDir,
+            attackSurface: result.attackSurface,
             findings: shown.map((finding) => ({
                 ruleId: finding.ruleId,
                 slug: finding.slug,
@@ -239,10 +240,12 @@ const toToolResult = (result, options) => {
                 title: finding.title,
                 message: finding.message,
                 filePath: finding.filePath,
+                file: finding.file,
                 line: finding.line,
                 column: finding.column,
                 snippet: finding.snippet,
                 cwe: finding.cwe,
+                owasp: finding.owasp,
                 remediation: finding.remediation,
                 secureExample: finding.secureExample,
                 references: finding.references,
@@ -281,6 +284,7 @@ const explainRuleResult = (rule) => {
             severity: rule.severity,
             confidence: rule.confidence,
             cwe: rule.cwe,
+            owasp: rule.owasp,
             description: rule.description,
             insecureExample: rule.insecureExample,
             secureExample: rule.secureExample,
@@ -334,7 +338,7 @@ async function callTool(name, args, options = {}) {
                 return errorResult('`ruleId` is required, e.g. "VSB-CLIENT-001".');
             const rule = (0, rules_1.getRule)(ruleId);
             if (!rule)
-                return errorResult(`Unknown rule "${ruleId}". Call tools/list or \`npx github:avivgerz-hue/vibe-shield rules\` for the catalogue.`);
+                return errorResult(`Unknown rule "${ruleId}". Call tools/list or \`npx -y @vibefoundry/vibe-shield rules\` for the catalogue.`);
             return explainRuleResult(rule);
         }
         return errorResult(`Unknown tool "${name}".`);
@@ -393,7 +397,7 @@ async function handleMessage(message, options = {}) {
                 serverInfo: {
                     name: exports.SERVER_NAME,
                     title: 'vibe-shield',
-                    version: options.version ?? '1.1.0',
+                    version: options.version ?? await (0, engine_1.packageVersion)(),
                 },
                 instructions: 'vibe-shield finds security bugs that AI coding agents ship: leaked secrets, unguarded API routes, missing Postgres RLS, SQL injection, prompt injection and poisoned agent skills. Call vibe_shield_scan after writing application code and before reporting a task as done, and vibe_shield_audit_skills after touching any agent instruction or MCP config file.',
             });