@vibefoundry/vibe-shield 0.0.0-stage → 1.1.0

package/SECURITY.md

@@ -0,0 +1,110 @@
+# Security policy
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| 1.x | ✅ |
+| < 1.0 | ❌ |
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a security problem.**
+
+Email **security@vibefoundry.dev** with:
+
+- a description of the issue and its impact
+- the affected version (`npx github:avivgerz-hue/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
+
+You get an acknowledgement within **48 hours** and a triage decision within
+**5 business days**. If the report is valid we will:
+
+1. confirm the severity using the CVSS v3.1 vector,
+2. ship a fix in a patch release,
+3. publish a GitHub Security Advisory crediting you (unless you prefer to stay
+   anonymous),
+4. request a CVE if the impact warrants one.
+
+## Security model
+
+vibe-shield is a **static analyser**. It reads files and reports what it finds.
+Understanding the trust boundaries matters when you run it on untrusted input.
+
+### What the tool does
+
+| Behaviour | Detail |
+| --- | --- |
+| Network access | **None.** The runtime has zero dependencies and makes no outbound requests. There is no telemetry, no update check, no crash reporting. |
+| Filesystem access | Read-only, confined to the scan root. `--cache` writes one file (`.vibe-shield-cache.json`) to the scan root; `--fix-prompt` and `--out` write exactly the paths you ask for. |
+| Subprocesses | One optional `git ls-files` / `git rev-parse` call, used to determine whether a `.env` file is tracked. Disable it with `useGitIndex: false` (API) or by running outside a work tree. |
+| Code execution | **None.** Scanned files are never imported, evaluated, executed or served. There is no plugin loading, no `require()` of project code, and no shell invocation derived from file content. |
+| Secret handling | Secret values are matched in memory, then **redacted before they reach any output** (`redactSecret`). `SECURITY_PATCH_PROMPT.md`, JSON, SARIF and GitHub annotations all carry the masked form. The raw value never leaves the process. |
+
+### What it deliberately does not do
+
+- It does not resolve dependencies or run a package manager.
+- It does not follow symlinks (symlinked entries are skipped, which prevents a
+  scan root from being used to read outside the tree).
+- It does not scan `node_modules`, build output or `.git` (pruned by name).
+- It does not fetch remote rule sets. The rule catalogue is compiled into the
+  package and fingerprinted so a cached result can never be reused after a rule
+  change (`RULES_FINGERPRINT`).
+
+### Running it on untrusted code
+
+Scanning a hostile repository is safe by design: nothing is executed. The two
+things to be aware of are resource-related, not exploit-related:
+
+- **Pathological input.** Rules cap match counts (`20_000` per rule per file),
+  brace-block extraction (`8_000` chars), and regex scan windows. Files above
+  1.5 MB are skipped. A crafted file can make a rule slow; it cannot make it
+  hang indefinitely.
+- **Output size.** A repository engineered to produce thousands of findings will
+  produce a large report. Use `--severity`, `--max-findings` or `--format
+  summary` when the input is not trusted.
+
+### Supply chain
+
+- **Zero runtime dependencies.** There is no transitive package to compromise.
+  The only dev dependencies are `typescript` and `vitest` (+ `@vitest/coverage-v8`).
+- **Lockfile committed.** CI installs with `npm ci`, not `npm install`.
+- **Publishing uses provenance.** The release workflow publishes with
+  `--provenance` via GitHub OIDC, so the npm artefact is verifiably built from
+  this repository's workflow run.
+- **Self-scanning.** CI runs `vibe-shield scan --fail-on high` and
+  `vibe-shield audit-skills --fail-on high` against this repository on every
+  push. The detector catalogue is the only excluded path, documented in
+  [`.vibe-shieldignore`](./.vibe-shieldignore).
+
+### Known limitations (not vulnerabilities)
+
+- **Static by design.** Dynamic dispatch, metaprogramming and code generated at
+  runtime can hide a vulnerable shape from any static rule.
+- **Heuristics have false positives.** Every rule is conservative about the
+  legitimate patterns it knows (see the FAQ in the README), but a novel
+  framework can still produce a finding that is not exploitable. That is a bug
+  report, not a security issue — please open a normal issue.
+- **The auditor reads prose.** `audit-skills` flags dangerous *language* in
+  instruction files. It distinguishes prohibitions from instructions and
+  documentation from commands, but an adversarially worded skill can still
+  evade a regex. It is a tripwire, not a sandbox; the real defence is not
+  installing skills you have not read.
+
+## Scope
+
+In scope:
+
+- a rule that crashes, hangs, or reads outside the scan root
+- a secret value appearing unredacted in any output stream or file
+- command injection or path traversal through CLI arguments
+- a `--fix-prompt` / `--out` write escaping the intended directory
+- npm publish / release workflow compromise
+
+Out of scope:
+
+- false positives on unusual framework patterns (open a normal issue)
+- false negatives on obfuscated code (static analysis is not a sandbox)
+- findings in *your* repository that vibe-shield reported correctly
+- vulnerabilities in `npx`'s own resolution behaviour

package/SKILL.md

@@ -0,0 +1,124 @@
+---
+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
+license: MIT
+metadata:
+  author: VibeFoundry
+  homepage: https://github.com/avivgerz-hue/vibe-shield
+  version: 1.0.0
+---
+
+# vibe-shield
+
+You are not allowed to say "done" until the code you just wrote passes a security audit.
+
+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.
+
+## When to run
+
+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
+
+```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
+```
+
+`--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;
+```
+
+| 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.
+
+## Hard rules
+
+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.
+
+## Agent surface audit
+
+When you add or modify a skill, rule file, MCP server or instruction file, also run:
+
+```bash
+npx github:avivgerz-hue/vibe-shield audit-skills
+```
+
+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 |
+
+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
+
+```bash
+npx github:avivgerz-hue/vibe-shield init
+```
+
+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

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * vibe-shield :: command line
+ * ---------------------------
+ *   vibe-shield scan [paths]          scan a project (default: `.`)
+ *   vibe-shield audit-skills [paths]  audit agent skills / MCP config
+ *   vibe-shield init                  install the Agent Skill + CI gate
+ *   vibe-shield rules                 list every rule
+ *   vibe-shield explain <RULE_ID>     full documentation for one rule
+ *   vibe-shield version | help
+ *
+ * The module exports `run(argv, io)` and only executes when invoked directly,
+ * which is what lets the test suite drive the real CLI without a build step.
+ */
+/** Everything the CLI needs from the outside world (injectable for tests). */
+export interface CliIo {
+    stdout: {
+        write(chunk: string): unknown;
+        isTTY?: boolean;
+        columns?: number;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+        isTTY?: boolean;
+        columns?: number;
+    };
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export declare const defaultIo: () => CliIo;
+/** Exit codes: 0 clean, 1 findings at/above `--fail-on`, 2 usage error. */
+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";
+interface ParsedArgs {
+    command: string;
+    positionals: string[];
+    flags: Map<string, string | boolean>;
+    unknown: string[];
+}
+/** Parse `argv` without any dependency. Supports `--flag=value` and repeats. */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare function commandScan(parsed: ParsedArgs, io: CliIo): Promise<number>;
+declare function commandAuditSkills(parsed: ParsedArgs, io: CliIo): Promise<number>;
+declare function commandInit(parsed: ParsedArgs, io: CliIo): Promise<number>;
+declare function commandRules(parsed: ParsedArgs, io: CliIo): number;
+declare function commandExplain(parsed: ParsedArgs, io: CliIo): number;
+/**
+ * Serve MCP over stdio.
+ *
+ * Nothing but JSON-RPC may reach stdout here — a banner or progress line would
+ * corrupt the client session — so the one diagnostic permitted (an explicit
+ * note that the server is ready) goes to stderr.
+ */
+declare function commandMcp(parsed: ParsedArgs, io: CliIo): Promise<number>;
+/** Run the CLI. Returns the process exit code. */
+export declare function run(argv: readonly string[], io?: CliIo): Promise<number>;
+export { HELP as HELP_TEXT, commandScan, commandAuditSkills, commandInit, commandRules, commandExplain, commandMcp };