npx github:avivgerz-hue/vibe-shield scan

The problem, in one file

This is the shape of code an agent writes when you ask for "a delete endpoint":

// app/api/users/route.ts
export async function DELETE(req: Request) {
  const { id, userId } = await req.json();
  await db.query(`DELETE FROM users WHERE id = ${id} AND owner = ${userId}`);
  return new Response('ok');
}

It works. It also has three critical vulnerabilities — no authentication, SQL injection, and an IDOR that lets the caller choose whose data they delete. Nothing in a normal review loop catches all three, and the agent reported the task as complete.

npx github:avivgerz-hue/vibe-shield scan catches all three in 17 milliseconds:

🛡️  vibe-shield v1.0.0 · security scan
target  /home/you/app

💀 GRADE F — 0/100 · 3 critical

  CRITICAL 3    ███

Findings

app/api/users/route.ts
  CRITICAL 2:1      VSB-AUTH-001  Next.js App Router mutation handler has no authentication check
           export async function DELETE(req: Request) {
  CRITICAL 4:22     VSB-DB-007    SQL statement built by concatenating request data
           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

  ⚠  3 critical findings — rotate any exposed credential before anything else.
  Fix it      npx github:avivgerz-hue/vibe-shield scan --fix-prompt    # writes SECURITY_PATCH_PROMPT.md for your agent
  Explain     npx github:avivgerz-hue/vibe-shield explain VSB-AUTH-001
  Gate CI     npx github:avivgerz-hue/vibe-shield scan --fail-on critical --format github

Then hand the fix list to the agent that wrote the bug:

npx github:avivgerz-hue/vibe-shield scan --fix-prompt   # → SECURITY_PATCH_PROMPT.md

That file contains, for every finding: the severity, the CWE id and link, the exact file:line, the vulnerable snippet, the ordered remediation steps, the target code shape, and a verification command. It is written for a machine to execute and a human to audit.

⚡ Quick start

# 1. Scan (no install, no config, no network calls)
npx github:avivgerz-hue/vibe-shield scan

# 2. Give your agent the fix list
npx github:avivgerz-hue/vibe-shield scan --fix-prompt

# 3. Install the gate permanently — skill + CI + ignore file
npx github:avivgerz-hue/vibe-shield init

Why GitHub and not npx vibe-shield? The name vibe-shield on the npm
registry belongs to a different project with no connection to this one. Running
npx vibe-shield installs their package, not this repository's. Install from
GitHub — the compiled CLI is committed, so it needs no TypeScript and starts
in milliseconds. A scoped npm release (@vibefoundry/vibe-shield) may follow.

npx github:avivgerz-hue/vibe-shield init writes:

Nothing is overwritten without --force, and re-running is a no-op.

🧠 Why AI code needs its own scanner

Traditional SAST rules are built around human mistakes: a forgotten escape, a missing prepare(). Agent-written code fails differently — it is confidently complete and structurally plausible:

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.

📊 Vulnerability Coverage Matrix

48 code signatures + 12 agent-integrity signatures = 60. Every rule has an id, a CWE, a vulnerable example, a fixed example, and ordered remediation steps — run npx github:avivgerz-hue/vibe-shield rules or npx github:avivgerz-hue/vibe-shield explain <ID>.

Client-side secret & data exposure — VSB-CLIENT-*

Unguarded mutation routes — VSB-AUTH-*

Database exposure — VSB-DB-*

* critical when Supabase/PostgREST is detected — the anon key in every browser makes the table publicly addressable.

AI / LLM & classic web — VSB-AI-*

Hardcoded credentials — VSB-SECRET-*

Agent skill & MCP poisoning — VSB-AGENT-* (audit-skills)

🔌 Native MCP server

vibe-shield is itself a Model Context Protocol server, so
Claude Code, Claude Desktop, Cursor and Codex can call the scanner as a tool
instead of shelling out and parsing console output.

npx github:avivgerz-hue/vibe-shield mcp          # JSON-RPC 2.0 over stdio

Three tools:

npx github:avivgerz-hue/vibe-shield init writes the config for you, merging into .mcp.json
without clobbering servers you already have:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "vibe-shield": { "command": "npx", "args": ["--yes", "github:avivgerz-hue/vibe-shield", "mcp"] }
  }
}

Or add it by hand:

claude mcp add vibe-shield -- npx --yes github:avivgerz-hue/vibe-shield mcp

The server is zero-dependency, writes only JSON-RPC to stdout, honours
JSON-RPC notifications (no spurious replies), and returns tool errors as
isError results so a bad argument degrades one call instead of killing the
session. Requests are handled in arrival order.

An empty target is reported as No files were scanned rather than a green pass —
a scanner that says "clean" when it read nothing is worse than no scanner.

🤖 Use it as an Agent Skill

npx github:avivgerz-hue/vibe-shield init installs the skill. Once it is in a repository, every
agent session starts with a contract:

You are not allowed to say "done" until the code you just wrote passes a security audit.

npx github:avivgerz-hue/vibe-shield init                 # Claude Code + Cursor + AGENTS.md + CI
npx github:avivgerz-hue/vibe-shield init --agent claude  # just the skill
npx github:avivgerz-hue/vibe-shield init --no-workflow   # skip the GitHub Action

Why this works better than a prompt snippet: it names the three commands, gives the agent a reading guide for a finding (line:col, rule id, message, CWE), states five hard rules (never suppress, never weaken, always rotate, report honestly, re-verify), and defines "done" as an exit code rather than an opinion.

The skill itself is SKILL.md — read it, it is short.

Anthropic Agent Skills quickstart

# marketplace-style install
npx github:avivgerz-hue/vibe-shield init --agent claude
# → .claude/skills/vibe-shield/SKILL.md

# or globally, for every project
curl -sL https://raw.githubusercontent.com/avivgerz-hue/vibe-shield/main/SKILL.md \
  -o ~/.claude/skills/vibe-shield/SKILL.md

🔁 CI/CD: fail the PR before the bug ships

GitHub Actions (recommended)

npx github:avivgerz-hue/vibe-shield init installs a workflow that runs the scan, uploads SARIF to
code scanning, audits the agent surface, and fails the job:

name: vibe-shield
on: [push, pull_request]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Scan and upload SARIF
        run: npx --yes github:avivgerz-hue/vibe-shield scan --format sarif --out vibe-shield.sarif --fail-on high
        continue-on-error: true

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: vibe-shield.sarif
          category: vibe-shield

      - name: Enforce the gate
        run: npx --yes github:avivgerz-hue/vibe-shield scan --fail-on high

Findings appear inline on the pull request diff (GitHub annotations) and in
the Security → Code scanning tab (SARIF), so a reviewer sees the vulnerability
on the line that introduced it.

Any other CI

npx github:avivgerz-hue/vibe-shield scan --fail-on high                         # exit 1 on findings
npx github:avivgerz-hue/vibe-shield scan --format compact                       # one line per finding
npx github:avivgerz-hue/vibe-shield scan --format json > vibe-shield.json       # full report
npx github:avivgerz-hue/vibe-shield scan --format summary                       # JSON, counts + grade only
npx github:avivgerz-hue/vibe-shield scan --format github                        # workflow annotations

Exit codes: 0 clean · 1 findings at/above --fail-on · 2 usage error
(a target path that does not exist, or a target that matches no scannable files).
An empty scan prints NO FILES SCANNED — this is not a pass and is never
reported as a grade — a gate pointed at an ignored path fails instead of
succeeding forever.

🎯 The scorecard

Grades are deliberately unforgiving, because "B+" for a leaked production key is how security tools lose credibility:

Penalties per finding: critical −30, high −12, medium −5, low −2, info −0.5. One leaked live key fails the build on its own; a handful of informational notes never will.

🪄 It scans itself

This repository runs its own gate on every commit and in CI:

$ npx github:avivgerz-hue/vibe-shield scan
🛡️  vibe-shield v1.0.0 · security scan
target  /you/vibe-shield

🏆 GRADE A+ — 100/100

  21 files  ·  172 KiB  ·  236 files/s  ·  89 ms  ·  48 rules

  Nothing to fix. Keep the shield up. 🛡️

$ npx github:avivgerz-hue/vibe-shield audit-skills
🏆 GRADE A+ — 100/100

  1 file  ·  6 KiB  ·  14 files/s  ·  69 ms  ·  12 rules

  Nothing to fix. Keep the shield up. 🛡️

The detector catalogue is the one place that must contain the exact vulnerable
shapes and vendor key formats the rules match on — exactly like gitleaks and
semgrep. Those files are listed explicitly in .vibe-shieldignore
with a comment explaining why, instead of weakening a rule.

🔇 Suppressing a finding (legitimately)

Inline, with a rule id and a reason — the reason is required by review culture even though the parser does not enforce it:

// vibe-shield-disable-next-line VSB-AI-001 -- path comes from a closed enum
exec(`convert ${KNOWN_FORMATS[format]} out.png`);

// vibe-shield-disable-line VSB-AUTH-008
// vibe-shield-disable VSB-AI-014
// vibe-shield-enable
// vibe-shield-disable-file VSB-DB-004 -- generated edge schema

Suppressed findings are counted and reported in the scorecard, never silently dropped. Whole-path exclusions belong in .vibe-shieldignore (gitignore syntax) and should be reserved for generated code.

⚙️ How it works

 discover ──▶ project context ──▶ rule gate ──▶ detect ──▶ suppress ──▶ score ──▶ report
   │              │                  │           │
   │              │                  │           └─ 60 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

Design constraints, in priority order:

1. Fast. One readdir walk, one read per file, one comment-masking pass, and a cheap gate before any rule body runs. A 400-file project scans in ~200 ms; a typical Next.js app in under 100 ms. No AST, no parser, no dependency.
2. Honest. Every finding carries the exact snippet the developer wrote. Nothing is inferred from a filename alone, and every suppression is counted, not hidden.
3. Composable. scanProject() for the CLI, runRulesOnFile() for the auditor, scoreFindings() for anything that produces findings. The whole API is exported from vibe-shield.

Zero runtime dependencies. No network calls, no telemetry, no language server, no native binaries. npx github:avivgerz-hue/vibe-shield scan works offline and in an air-gapped CI runner.

📖 CLI reference

vibe-shield scan [paths...]         Scan the project (default: `.`)
vibe-shield audit-skills [paths...] Audit agent skills, rules, AGENTS.md and MCP config
vibe-shield init                    Install the Agent Skill, AGENTS.md, .mcp.json and CI gate
vibe-shield mcp                     Serve the MCP tools over stdio
vibe-shield rules                   List every detection rule
vibe-shield explain <RULE_ID>       Full documentation for one rule
vibe-shield version | help

init takes --target <dir>, --agent claude / cursor / generic / all, --no-workflow,
--force and --yes.

🧩 Programmatic API

import { scanProject, formatSarif, buildPatchPrompt, auditSkills } from 'vibe-shield';

const result = await scanProject({ rootDir: process.cwd(), cache: true });

console.log(result.score.score, result.score.grade);  // 0 'F'
console.log(result.findings[0].ruleId);               // 'VSB-AUTH-001'
console.log(result.findings[0].cwe.id);               // 'CWE-306'

process.stdout.write(formatSarif(result));            // SARIF 2.1.0
process.stdout.write(buildPatchPrompt(result));       // agent-ready fix list

const agentReport = await auditSkills(process.cwd()); // VSB-AGENT-* surface

❓ FAQ

Does it replace a real SAST tool?
No. It replaces the absence of one. vibe-shield is a fast, zero-dependency gate you can put in front of every agent-written commit today. Pair it with a deeper scanner (CodeQL, Semgrep) if you have one; the rules overlap far less than you would expect, because these are agent-specific shapes.

Will it flag my secure code?
The secure fixture (tests/fixtures/secure/) is a real Next.js + Supabase + Stripe app with auth, RLS, sanitisation, rate limiting and webhook verification — it scores 100/100 and the suite asserts zero findings on it. Each rule has guard clauses for the legitimate patterns: import "server-only" suppresses the service-role rules, Prisma tagged templates suppress the SQLi rule, DOMPurify suppresses the XSS rule, auth.uid() policies suppress the RLS rules.

Does it send my code anywhere?
No. There is no network code in the runtime at all — the package has zero dependencies and makes no outbound requests.

Why not an AST?
Because a 1.5 MB minified bundle, a Vue SFC, a PHP legacy file and a SQL migration all need to be scanned with the same tool, and a parser handles exactly one of those. The rules use structural brace matching plus a comment-masker that preserves offsets, which is enough for the shapes that matter and roughly two orders of magnitude faster.

Why "vibe"?
Because the code was written by vibe and reviewed by nobody. This is the reviewer.

🛠 Development

git clone https://github.com/avivgerz-hue/vibe-shield
cd vibe-shield
npm ci
npm run typecheck   # tsc --noEmit (strict, noUnusedLocals)
npm test            # 224 Vitest tests
npm run build       # tsc + postbuild (shebang, chmod, CJS marker)
npm run verify      # typecheck + test + build + self-scan + self-audit

See CONTRIBUTING.md for the rule-authoring guide, and
SECURITY.md for the threat model and disclosure policy.

📋 Requirements

• Node.js ≥ 18.17 (uses node: builtins only — no polyfills, no native modules)
• Any OS: Linux, macOS, Windows
• No config file required; package.json is optional

📄 License

MIT © VibeFoundry — use it, fork it, ship it.

Part of the VibeFoundry Agent Suite

Three tools for the same problem: agents move fast, and something has to keep the output honest.

npx github:avivgerz-hue/vibe-shield init   # security gate