VibeCheck Docs

VibeCheck Documentation

The first AI Enforcement Security tool. Proves whether AI-written code actually enforces the security it claims.

Quick Start

Install globally

npm install -g @quantracode/vibecheck

Or use without installing

npx @quantracode/vibecheck scan --fail-on off

Scan with output file

npx @quantracode/vibecheck scan --out vibecheck-scan.json

View results in browser

npx @quantracode/vibecheck view

100% Local Verification

All analysis runs on your machine. Your source code never leaves your environment. No cloud uploads, no telemetry, no phone-home.

CLI Reference

Scan Command Options

Option	Description	Default
-t, --target <path>	Target directory to scan	Current directory
-o, --out <path>	Output file path	vibecheck-artifacts/vibecheck-scan.json
-f, --format <format>	Output format: json, sarif, or both	json
--repo-name <name>	Override repository name	Auto-detected
--fail-on <threshold>	Exit non-zero if findings >= threshold (critical\|high\|medium\|low\|off)	high
-e, --exclude <glob>	Glob pattern to exclude (repeatable)	See defaults
--include-tests	Include test files in scan	false
--emit-intent-map	Include route map and coverage metrics	false

View Command Options

Option	Description	Default
-p, --port <port>	Port to run the viewer on	3000
-a, --artifact <path>	Path to artifact file to open	Auto-detected
--no-open	Don't automatically open the browser	Opens browser
--update	Force update the viewer to latest version	-
--clear-cache	Clear the cached viewer and exit	-

Example Commands

Scan with SARIF output for CI

vibecheck scan --format sarif --out results.sarif

Scan and fail CI on medium+ findings

vibecheck scan --fail-on medium

Scan with intent map and coverage metrics

vibecheck scan --emit-intent-map --out scan.json

View results interactively

vibecheck view -a scan.json

Output Formats

JSON

Default format with full artifact data including findings, evidence, metrics, and proof traces.

vibecheck scan --format json

SARIF

Standard format for GitHub Code Scanning, Azure DevOps, and other security tools.

vibecheck scan --format sarif

Scanner Reference

VibeCheck includes 30+ enforcement verification scanners across these categories:

Auth & Authorization

VC-AUTH-001High/Critical

Unprotected State-Changing API Route

Detects Next.js API route handlers (POST, PUT, PATCH, DELETE) that perform database operations without authentication checks.

VC-MW-001High

Middleware Matcher Gap

Detects Next.js middleware that doesn't cover API routes, potentially leaving them unprotected.

VC-AUTH-010Critical

Auth-by-UI with Server Gap

Detects client-side auth checks without corresponding server-side protection.

Input Validation

VC-VAL-001Medium

Validation Defined But Output Ignored

Detects cases where validation libraries (Zod, Yup, Joi) are called but the validated result is not used.

VC-VAL-002Medium

Client-Side Only Validation

Detects validation in frontend components but missing in API routes.

Network Security

VC-NET-001High

SSRF-Prone Fetch

Detects fetch/axios calls where the URL is derived from user input without validation.

VC-NET-002High

Open Redirect

Detects server-side redirects where user-controlled input determines the destination.

VC-NET-003High

Over-permissive CORS with Credentials

Detects CORS configurations that combine origin: '*' with credentials: true.

VC-NET-004Low

Missing Request Timeout

Detects fetch/axios calls without timeout in API route handlers.

Secrets & Config

VC-CONFIG-001Low

Undocumented Environment Variable

Detects process.env.VAR references that aren't documented in .env.example.

VC-CONFIG-002Critical

Insecure Default Secret Fallback

Detects hardcoded fallback values for security-critical environment variables.

VC-PRIV-003Medium

Debug Flags in Production

Detects debug: true or dev: true in config files without NODE_ENV guards.

Privacy & Data

VC-PRIV-001High

Sensitive Data Logged

Detects logging statements that include sensitive variable names like password, token, apiKey.

VC-PRIV-002Medium/High

Over-broad API Response

Detects Prisma queries returning full models without select restrictions.

Cryptography

VC-CRYPTO-001High

Math.random for Tokens

Detects Math.random used to generate tokens, keys, or session IDs.

VC-CRYPTO-002Critical

JWT Decode Without Verify

Detects jwt.decode() used without jwt.verify() in the same file.

VC-CRYPTO-003High

Weak Password Hashing

Detects MD5/SHA1 for passwords or bcrypt with saltRounds < 10.

File Uploads

VC-UP-001High

File Upload Without Constraints

Detects file uploads without size or type validation.

VC-UP-002High

Upload to Public Path

Detects uploaded files written to public directories.

Middleware

VC-RATE-001Medium

Missing Rate Limiting

Detects unauthenticated state-changing endpoints without rate limiting.

AI Hallucinations

VC-HALL-001Medium

Security Library Imported But Not Used

Detects security libraries (helmet, cors, csurf, etc.) that are imported but never used.

VC-HALL-010Medium

Comment Claims Protection But Unproven

Detects comments that claim security protection but the implementation doesn't prove it.

VC-HALL-011High

Middleware Assumed But Not Matching

Detects routes that expect middleware protection but are not covered by matcher patterns.

VC-HALL-012Medium

Validation Claimed But Missing/Ignored

Detects validation that is claimed but not properly implemented or used.

Supply Chain

VC-SC-001Medium

Unpinned Dependencies

Detects dependencies using version ranges that could introduce breaking changes.

VC-SC-002High

Suspicious Postinstall Scripts

Detects packages with postinstall scripts that could execute malicious code.

VC-SC-003Low

Deprecated Packages

Detects dependencies that have been deprecated by their maintainers.

Abuse & Compute

VC-ABUSE-001High

Unbounded AI API Calls

Detects AI/LLM API calls without request limits or cost controls.

VC-ABUSE-002Medium

Missing Cost Controls

Detects expensive operations (AI, external APIs) without budget limits.

CI/CD Integration

GitHub Actions Example

name: Security Scan

on: [push, pull_request]

jobs:
  vibecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run VibeCheck
        run: npx @quantracode/vibecheck scan --format sarif --out results.sarif --fail-on high

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Policy Evaluation (Pro Feature)

Compare scans against baselines for regression detection:

# Evaluate against startup profile
npx @quantracode/vibecheck evaluate \
  --artifact vibecheck-scan.json \
  --profile startup \
  --out policy-report.json

# Compare against baseline (regression detection)
npx @quantracode/vibecheck evaluate \
  --artifact vibecheck-scan.json \
  --baseline main-branch-scan.json \
  --profile enterprise

Artifact Format

VibeCheck generates structured JSON artifacts (version 0.3):

{
  "artifactVersion": "0.3",
  "generatedAt": "2024-01-15T10:30:00.000Z",
  "tool": { "name": "vibecheck", "version": "0.3.2" },
  "summary": {
    "totalFindings": 5,
    "bySeverity": { "critical": 1, "high": 2, "medium": 1, "low": 1, "info": 0 },
    "byCategory": { "auth": 1, "validation": 1, ... }
  },
  "findings": [
    {
      "id": "f-abc123",
      "severity": "high",
      "confidence": 0.85,
      "category": "auth",
      "ruleId": "VC-AUTH-001",
      "title": "Missing authentication on POST /api/users",
      "evidence": [...],
      "remediation": { "recommendedFix": "Add authentication middleware" }
    }
  ],
  "routeMap": { ... },
  "middlewareMap": { ... },
  "intentMap": { ... },
  "proofTraces": { ... },
  "metrics": {
    "filesScanned": 50,
    "linesOfCode": 5000,
    "scanDurationMs": 1234
  }
}

Design Principles

Deterministic

No LLM calls, results are reproducible

Local-only

All analysis runs on your machine

Low false positives

Precision over recall

Framework-aware

Built for Next.js, Express patterns

Enforcement-focused

Proves what's enforced, not just scanned

Schema-compliant

Output conforms to versioned schema

Ready to verify your code?

Install VibeCheck and start proving enforcement in minutes.

npm i -g @quantracode/vibecheck

View Pro Features