@quantracode/vibecheck 0.2.2 → 0.3.0

package/README.md

@@ -1,903 +1,903 @@
-# @quantracode/vibecheck
-
-A deterministic, local-only security scanner for modern web applications. Designed to catch common security issues in Next.js, Express, and other Node.js projects with high precision and low false positives.
-
-## Quickstart (No Install)
-
-Run VibeCheck instantly without installation:
-
-```bash
-# Using npx
-npx @quantracode/vibecheck scan --fail-on off --out vibecheck-scan.json
-
-# Using pnpm dlx
-pnpm dlx @quantracode/vibecheck scan --fail-on off --out vibecheck-scan.json
-```
-
-### Scan Another Folder
-
-```bash
-npx @quantracode/vibecheck scan --target ../my-other-app --out scan.json
-```
-
-## Installation
-
-```bash
-npm install -g @quantracode/vibecheck
-# or
-pnpm add -g @quantracode/vibecheck
-```
-
-## Usage
-
-```bash
-# Scan current directory
-vibecheck scan
-
-# Scan specific directory with output file
-vibecheck scan ./my-project --out ./reports/scan.json
-
-# Use --target as alternative to positional argument
-vibecheck scan --target ./my-project
-
-# Output in SARIF format (for GitHub Code Scanning)
-vibecheck scan --format sarif
-
-# Output both JSON and SARIF
-vibecheck scan --format both
-
-# Fail CI if medium or higher findings
-vibecheck scan --fail-on medium
-
-# Disable fail threshold (always exit 0)
-vibecheck scan --fail-on off
-
-# Exclude specific directories
-vibecheck scan -e "**/legacy/**" -e "**/vendor/**"
-
-# Include test files in scan (excluded by default)
-vibecheck scan --include-tests
-
-# Generate intent map with coverage metrics
-vibecheck scan --emit-intent-map
-
-# Explain a scan report
-vibecheck explain ./scan.json
-
-# Start the web viewer
-vibecheck view
-
-# Open viewer with specific artifact
-vibecheck view -a ./scan.json
-```
-
-## View Command
-
-The `view` command starts a local web viewer to explore scan results interactively.
-
-```bash
-# Start viewer (auto-detects artifacts in current directory)
-vibecheck view
-
-# Specify artifact file explicitly
-vibecheck view -a ./vibecheck-scan.json
-vibecheck view --artifact ./scan-results.json
-
-# Use a different port
-vibecheck view --port 8080
-
-# Don't auto-open browser
-vibecheck view --no-open
-
-# Force update the viewer to latest version
-vibecheck view --update
-
-# Clear cached viewer files
-vibecheck view --clear-cache
-```
-
-### 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 | - |
-
-### How It Works
-
-1. **Auto-download**: The viewer is automatically downloaded from npm on first run and cached in `~/.vibecheck/viewer/`
-2. **Auto-detect artifacts**: Looks for scan artifacts in common locations:
-   - `vibecheck-artifacts/artifact.json`
-   - `vibecheck-artifact.json`
-   - `.vibecheck/artifact.json`
-   - `scan-results.json`
-3. **Auto-load**: When an artifact is detected, it's automatically loaded into the viewer
-4. **Local-only**: The viewer runs entirely on your machine with no external connections
-
-### Workflow Example
-
-```bash
-# 1. Run a scan
-vibecheck scan --out vibecheck-artifacts/artifact.json
-
-# 2. View results (artifact auto-detected)
-vibecheck view
-
-# Browser opens to http://localhost:3000 with results loaded
-```
-
-### Command Line Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-t, --target <path>` | Target directory to scan | Current directory |
-| `-o, --out <path>` | Output file or directory | `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 with non-zero if findings >= threshold | `high` |
-| `-e, --exclude <glob>` | Glob pattern to exclude (repeatable) | See below |
-| `--include-tests` | Include test files in scan | `false` |
-| `--emit-intent-map` | Include route map and coverage metrics | `false` |
-| `--changed` | Only scan changed files (not implemented) | `false` |
-
-### Default Excludes
-
-The following patterns are excluded by default:
-
-**Core excludes (always applied):**
-- `node_modules`, `dist`, `.git`, `build`, `.next`, `coverage`
-- `.turbo`, `.cache`, `out`, `.vercel`, `.netlify`
-
-**Test excludes (skipped with `--include-tests`):**
-- `__tests__/**`, `*.test.*`, `*.spec.*`
-- `test/`, `tests/`, `fixtures/`, `__mocks__/`, `__fixtures__/`
-- `cypress/`, `e2e/`, `*.stories.*`
-
-## Scanner Packs
-
-VibeCheck organizes security rules into modular scanner packs. Each pack focuses on a specific security domain.
-
-### Auth Pack
-
-Rules for authentication and authorization issues.
-
-#### VC-AUTH-001: Unprotected State-Changing API Route
-
-**Severity:** High / Critical
-**Category:** auth
-
-Detects Next.js App Router API route handlers (POST, PUT, PATCH, DELETE) that perform database operations without authentication checks.
-
-**What it looks for:**
-- Route handlers in `app/**/route.ts` files
-- Handlers that use Prisma, Drizzle, or other database operations
-- Missing calls to `getServerSession`, `auth()`, or similar auth checks
-
-**Example (vulnerable):**
-```typescript
-// app/api/users/route.ts
-export async function POST(request: Request) {
-  const body = await request.json();
-  await prisma.user.create({ data: body }); // No auth check!
-  return Response.json({ success: true });
-}
-```
-
-**Example (safe):**
-```typescript
-// app/api/users/route.ts
-export async function POST(request: Request) {
-  const session = await getServerSession();
-  if (!session) {
-    return Response.json({ error: "Unauthorized" }, { status: 401 });
-  }
-  const body = await request.json();
-  await prisma.user.create({ data: body });
-  return Response.json({ success: true });
-}
-```
-
----
-
-#### VC-MW-001: Middleware Matcher Gap
-
-**Severity:** High
-**Category:** middleware
-
-Detects Next.js middleware that doesn't cover API routes, potentially leaving them unprotected.
-
-**What it looks for:**
-- `middleware.ts` files with `config.matcher` exports
-- Matchers that exclude `/api` routes
-- Projects using next-auth without middleware protection
-
-**Example (vulnerable):**
-```typescript
-// middleware.ts
-export const config = {
-  matcher: ['/dashboard/:path*'] // Missing /api routes!
-};
-```
-
-**Example (safe):**
-```typescript
-// middleware.ts
-export const config = {
-  matcher: ['/api/:path*', '/dashboard/:path*']
-};
-```
-
----
-
-### Validation Pack
-
-Rules for input validation issues.
-
-#### VC-VAL-001: Validation Defined But Output Ignored
-
-**Severity:** Medium
-**Category:** validation
-
-Detects cases where validation libraries (Zod, Yup, Joi) are called but the validated result is not used.
-
-**What it looks for:**
-- Calls to `.parse()`, `.validate()`, `.parseAsync()`, etc.
-- Result not assigned to a variable
-- Raw `request.body` or `req.body` used after validation
-
-**Example (vulnerable):**
-```typescript
-const schema = z.object({ name: z.string() });
-schema.parse(body); // Result ignored!
-await prisma.user.create({ data: body }); // Uses unvalidated body
-```
-
-**Example (safe):**
-```typescript
-const schema = z.object({ name: z.string() });
-const validated = schema.parse(body);
-await prisma.user.create({ data: validated });
-```
-
----
-
-### Privacy Pack
-
-Rules for data privacy and logging issues.
-
-#### VC-PRIV-001: Sensitive Data Logged
-
-**Severity:** High
-**Category:** privacy
-
-Detects logging statements that include sensitive variable names.
-
-**What it looks for:**
-- `console.log`, `console.info`, `console.debug`, `logger.info`, etc.
-- Variables containing: password, secret, token, apiKey, creditCard, ssn, etc.
-
-**Example (vulnerable):**
-```typescript
-console.log("User login:", { email, password }); // Logs password!
-```
-
-**Example (safe):**
-```typescript
-console.log("User login:", { email, timestamp: Date.now() });
-```
-
----
-
-### Config Pack
-
-Rules for configuration and secrets management issues.
-
-#### VC-CONFIG-001: Undocumented Environment Variable
-
-**Severity:** Low
-**Category:** config
-
-Detects `process.env.VAR` references that aren't documented in `.env.example`.
-
----
-
-#### VC-CONFIG-002: Insecure Default Secret Fallback
-
-**Severity:** Critical
-**Category:** secrets
-
-Detects hardcoded fallback values for security-critical environment variables.
-
-**What it looks for:**
-- `process.env.VAR || "fallback"` patterns
-- Variables named: SECRET, KEY, TOKEN, PASSWORD, etc.
-- Hardcoded string fallbacks
-
-**Example (vulnerable):**
-```typescript
-const jwtSecret = process.env.JWT_SECRET || "development-secret";
-```
-
-**Example (safe):**
-```typescript
-const jwtSecret = process.env.JWT_SECRET;
-if (!jwtSecret) throw new Error("JWT_SECRET is required");
-```
-
----
-
-### Network Pack
-
-Rules for network security issues.
-
-#### VC-NET-001: SSRF-Prone Fetch
-
-**Severity:** High
-**Category:** network
-
-Detects fetch/axios calls where the URL is derived from user input without validation.
-
-**What it looks for:**
-- `fetch()` or `axios.get()` calls
-- URL constructed from request parameters, query strings, or body
-- No URL validation or allowlist checks
-
-**Example (vulnerable):**
-```typescript
-export async function GET(request: Request) {
-  const { searchParams } = new URL(request.url);
-  const url = searchParams.get("url");
-  const response = await fetch(url); // SSRF risk!
-  return Response.json(await response.json());
-}
-```
-
-**Example (safe):**
-```typescript
-const ALLOWED_HOSTS = ["api.example.com", "cdn.example.com"];
-
-export async function GET(request: Request) {
-  const { searchParams } = new URL(request.url);
-  const url = searchParams.get("url");
-  const parsed = new URL(url);
-  if (!ALLOWED_HOSTS.includes(parsed.hostname)) {
-    return Response.json({ error: "Invalid host" }, { status: 400 });
-  }
-  const response = await fetch(url);
-  return Response.json(await response.json());
-}
-```
-
----
-
-### Hallucinations Pack
-
-Rules for detecting security libraries that are imported but not properly used.
-
-#### VC-HALL-001: Security Library Imported But Not Used
-
-**Severity:** Medium
-**Category:** middleware
-
-Detects security libraries (helmet, cors, csurf, etc.) that are imported but the import is never used.
-
-**What it looks for:**
-- Imports from security packages: helmet, cors, csurf, express-rate-limit, hpp, etc.
-- Import identifier not referenced after the import statement
-
-**Example (vulnerable):**
-```typescript
-import helmet from "helmet"; // Imported but never used!
-import cors from "cors";
-
-const app = express();
-app.use(cors());
-// Missing: app.use(helmet());
-```
-
----
-
-#### VC-HALL-002: NextAuth Imported But Not Enforced
-
-**Severity:** High
-**Category:** auth
-
-Detects next-auth imported but `getServerSession` never called, suggesting auth is configured but not enforced.
-
-**What it looks for:**
-- Imports from `next-auth` or `next-auth/next`
-- No calls to `getServerSession` anywhere in the file
-
----
-
-## Phase 2 Rules
-
-### Network Pack (Extended)
-
-#### VC-NET-002: Open Redirect
-
-**Severity:** High
-**Category:** network
-
-Detects server-side redirects where user-controlled input determines the destination.
-
-**Two-signal requirement:** Must identify user-controlled source AND redirect call uses that value.
-
-**Example (vulnerable):**
-```typescript
-export async function GET(request: Request) {
-  const { searchParams } = new URL(request.url);
-  const next = searchParams.get("next");
-  return NextResponse.redirect(next!); // Open redirect!
-}
-```
-
----
-
-#### VC-NET-003: Over-permissive CORS with Credentials
-
-**Severity:** High
-**Category:** network
-
-Detects CORS configurations that combine `origin: "*"` with `credentials: true`.
-
-**Example (vulnerable):**
-```typescript
-cors({ origin: "*", credentials: true }) // Dangerous combination!
-```
-
----
-
-#### VC-NET-004: Missing Request Timeout
-
-**Severity:** Low
-**Category:** network
-
-Detects fetch/axios calls without timeout in API route handlers.
-
-**Example (vulnerable):**
-```typescript
-const response = await fetch("https://external-api.com/data"); // No timeout!
-```
-
----
-
-### Middleware Pack
-
-#### VC-RATE-001: Missing Rate Limiting
-
-**Severity:** Medium
-**Category:** middleware
-**Confidence:** 0.65
-
-Detects unauthenticated state-changing endpoints without rate limiting.
-
-**What it looks for:**
-- POST/PUT/PATCH/DELETE handlers without auth checks
-- Handlers with database writes or sensitive operations
-- No rate limiting signals in handler or middleware
-
----
-
-### Validation Pack (Extended)
-
-#### VC-VAL-002: Client-Side Only Validation
-
-**Severity:** Medium
-**Category:** validation
-
-Detects validation in frontend components but missing in API routes.
-
----
-
-### Privacy Pack (Extended)
-
-#### VC-PRIV-002: Over-broad API Response
-
-**Severity:** Medium/High
-**Category:** privacy
-
-Detects Prisma queries returning full models without `select` restrictions.
-
-**Example (vulnerable):**
-```typescript
-const users = await prisma.user.findMany(); // Returns password hash!
-return Response.json(users);
-```
-
-**Example (safe):**
-```typescript
-const users = await prisma.user.findMany({
-  select: { id: true, name: true, email: true }
-});
-return Response.json(users);
-```
-
----
-
-#### VC-PRIV-003: Debug Flags in Production
-
-**Severity:** Medium
-**Category:** config
-
-Detects `debug: true` or `dev: true` in config files without NODE_ENV guards.
-
----
-
-### Crypto Pack
-
-#### VC-CRYPTO-001: Math.random for Tokens
-
-**Severity:** High
-**Category:** crypto
-
-Detects Math.random used to generate tokens, keys, or session IDs.
-
-**Example (vulnerable):**
-```typescript
-const token = Math.random().toString(36).substring(2); // Predictable!
-```
-
-**Example (safe):**
-```typescript
-const token = crypto.randomBytes(32).toString('hex');
-```
-
----
-
-#### VC-CRYPTO-002: JWT Decode Without Verify
-
-**Severity:** Critical
-**Category:** crypto
-
-Detects jwt.decode() used without jwt.verify() in the same file.
-
-**Example (vulnerable):**
-```typescript
-const payload = jwt.decode(token); // Signature not verified!
-```
-
-**Example (safe):**
-```typescript
-const payload = jwt.verify(token, secret); // Signature verified
-```
-
----
-
-#### VC-CRYPTO-003: Weak Password Hashing
-
-**Severity:** High
-**Category:** crypto
-
-Detects MD5/SHA1 for passwords or bcrypt with saltRounds < 10.
-
-**Example (vulnerable):**
-```typescript
-crypto.createHash('md5').update(password).digest('hex'); // Weak!
-bcrypt.hash(password, 5); // Too few rounds!
-```
-
----
-
-### Uploads Pack
-
-#### VC-UP-001: File Upload Without Constraints
-
-**Severity:** High
-**Category:** uploads
-
-Detects file uploads without size or type validation.
-
-**Example (vulnerable):**
-```typescript
-const file = formData.get('file') as File;
-// No size or type check before processing
-```
-
----
-
-#### VC-UP-002: Upload to Public Path
-
-**Severity:** High
-**Category:** uploads
-
-Detects uploaded files written to public directories.
-
-**Example (vulnerable):**
-```typescript
-fs.writeFileSync(`public/uploads/${filename}`, buffer); // Publicly accessible!
-```
-
----
-
-## Phase 3: Hallucination Detection Engine
-
-Advanced cross-file analysis for detecting security intent vs implementation gaps.
-
-### Intent Command
-
-Generate a security intent map baseline for your codebase:
-
-```bash
-# Generate intent map
-vibecheck intent ./my-project --out intent-map.json
-
-# Include intent map in scan output
-vibecheck scan ./my-project --emit-intent-map
-```
-
-### Hallucinations Pack (Phase 3)
-
-#### VC-HALL-010: Comment Claims Protection But Unproven
-
-**Severity:** Medium
-**Category:** hallucinations
-**Confidence:** 0.75
-
-Detects comments that claim security protection but the implementation doesn't prove it.
-
-**Example (vulnerable):**
-```typescript
-// This route is protected by authentication middleware
-export async function POST(request: Request) {
-  // No auth check here, and middleware doesn't cover /api routes
-  await prisma.user.create({ data: body });
-}
-```
-
----
-
-#### VC-HALL-011: Middleware Assumed But Not Matching
-
-**Severity:** High
-**Category:** hallucinations
-**Confidence:** 0.70
-
-Detects routes that expect middleware protection but are not covered by matcher patterns.
-
-**Example (vulnerable):**
-```typescript
-// middleware.ts
-export const config = {
-  matcher: ['/dashboard/:path*'], // Missing /api routes!
-};
-
-// app/api/users/route.ts
-// Auth handled by middleware (but middleware doesn't cover this!)
-export async function DELETE(request: Request) {
-  await prisma.user.delete({ where: { id } });
-}
-```
-
----
-
-#### VC-HALL-012: Validation Claimed But Missing/Ignored
-
-**Severity:** Medium
-**Category:** hallucinations
-**Confidence:** 0.80
-
-Detects validation that is claimed but not properly implemented or used.
-
-**Example (vulnerable):**
-```typescript
-const schema = z.object({ name: z.string() });
-schema.parse(body); // Result ignored!
-await prisma.user.create({ data: body }); // Uses raw body
-```
-
----
-
-#### VC-AUTH-010: Auth-by-UI with Server Gap
-
-**Severity:** Critical
-**Category:** auth
-**Confidence:** 0.85
-
-Detects client-side auth checks without corresponding server-side protection.
-
-**Example (vulnerable):**
-```tsx
-// Client component
-const { session } = useSession();
-if (session) {
-  // Only render if logged in
-  await fetch('/api/users', { method: 'DELETE' }); // Server has no auth!
-}
-```
-
----
-
-### Coverage Metrics
-
-With `--emit-intent-map`, the scan artifact includes coverage metrics:
-
-- **authCoverage**: Percentage of state-changing routes with proven auth
-- **validationCoverage**: Percentage of routes with request bodies that have validation
-- **middlewareCoverage**: Percentage of routes covered by middleware matchers
-
-### Intent Map Structure
-
-```json
-{
-  "routeMap": [
-    {
-      "routeId": "abc123",
-      "method": "POST",
-      "path": "/api/users",
-      "file": "app/api/users/route.ts",
-      "startLine": 10,
-      "endLine": 25
-    }
-  ],
-  "middlewareMap": [
-    {
-      "file": "middleware.ts",
-      "matchers": ["/api/:path*"],
-      "protectsApi": true,
-      "startLine": 15
-    }
-  ],
-  "intentMap": [
-    {
-      "intentId": "def456",
-      "type": "AUTH_ENFORCED",
-      "scope": "route",
-      "source": "comment",
-      "textEvidence": "// Protected by auth"
-    }
-  ],
-  "proofTraces": {
-    "abc123": {
-      "routeId": "abc123",
-      "authProven": true,
-      "validationProven": false,
-      "middlewareCovered": true,
-      "steps": [...]
-    }
-  },
-  "coverage": {
-    "authCoverage": 0.85,
-    "validationCoverage": 0.60,
-    "middlewareCoverage": 1.0
-  }
-}
-```
-
----
-
-## Output Formats
-
-VibeCheck supports two output formats: JSON and SARIF.
-
-### JSON Format
-
-The default format, defined by `@vibecheck/schema`:
-
-```json
-{
-  "artifactVersion": "0.1",
-  "generatedAt": "2024-01-15T10:30:00.000Z",
-  "tool": {
-    "name": "vibecheck",
-    "version": "1.0.0"
-  },
-  "summary": {
-    "totalFindings": 2,
-    "bySeverity": { "critical": 0, "high": 1, "medium": 1, "low": 0, "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",
-      "description": "...",
-      "evidence": [
-        {
-          "file": "app/api/users/route.ts",
-          "startLine": 25,
-          "endLine": 30,
-          "snippet": "...",
-          "label": "Unprotected route handler"
-        }
-      ],
-      "remediation": {
-        "recommendedFix": "Add authentication middleware"
-      },
-      "fingerprint": "sha256:..."
-    }
-  ],
-  "metrics": {
-    "filesScanned": 50,
-    "linesOfCode": 5000,
-    "scanDurationMs": 1234
-  }
-}
-```
-
-### SARIF Format
-
-[SARIF (Static Analysis Results Interchange Format)](https://sarifweb.azurewebsites.net/) is an OASIS standard for static analysis tools. Use `--format sarif` to generate SARIF 2.1.0 output, compatible with:
-
-- **GitHub Code Scanning** - Upload via `github/codeql-action/upload-sarif`
-- **Azure DevOps** - Native SARIF support in security reports
-- **VS Code** - SARIF Viewer extension
-- **Other tools** - Any SARIF 2.1.0 compatible viewer
-
-```bash
-# Generate SARIF for GitHub Code Scanning
-vibecheck scan --format sarif --out results.sarif
-
-# Upload to GitHub (in CI workflow)
-- uses: github/codeql-action/upload-sarif@v2
-  with:
-    sarif_file: results.sarif
-```
-
-## Architecture
-
-```
-packages/cli/src/
-├── commands/
-│   ├── scan.ts         # Main scan orchestrator
-│   └── explain.ts      # Report viewer
-├── scanners/
-│   ├── types.ts        # ScanContext, types
-│   ├── helpers/
-│   │   ├── ast-helpers.ts      # ts-morph utilities
-│   │   └── context-builder.ts  # ScanContext factory
-│   ├── auth/
-│   │   ├── unprotected-api-route.ts  # VC-AUTH-001
-│   │   └── middleware-gap.ts         # VC-MW-001
-│   ├── validation/
-│   │   └── ignored-validation.ts     # VC-VAL-001
-│   ├── privacy/
-│   │   └── sensitive-logging.ts      # VC-PRIV-001
-│   ├── config/
-│   │   ├── undocumented-env.ts       # VC-CONFIG-001
-│   │   └── insecure-defaults.ts      # VC-CONFIG-002
-│   ├── network/
-│   │   └── ssrf-prone-fetch.ts       # VC-NET-001
-│   └── hallucinations/
-│       └── unused-security-imports.ts # VC-HALL-001, VC-HALL-002
-└── index.ts
-```
-
-## Design Principles
-
-1. **Deterministic** - No LLM calls, results are reproducible
-2. **Local-only** - All analysis runs on your machine
-3. **Low false positives** - Precision over recall
-4. **Framework-aware** - Built for Next.js, Express patterns
-5. **Schema-compliant** - Output conforms to `@vibecheck/schema`
-
-## Adding New Scanners
-
-Each scanner must:
-
-1. Accept a `ScanContext` with repo info and AST helpers
-2. Return `Finding[]` conforming to the schema
-3. Generate deterministic fingerprints for deduplication
-4. Include clear evidence with file locations
-
-```typescript
-import { type ScanContext } from "../types.js";
-import { type Finding } from "@vibecheck/schema";
-
-export async function scanMyRule(ctx: ScanContext): Promise<Finding[]> {
-  const findings: Finding[] = [];
-  // ... detection logic
-  return findings;
-}
-```
-
-## License
-
-MIT
+# @quantracode/vibecheck
+
+A deterministic, local-only security scanner for modern web applications. Designed to catch common security issues in Next.js, Express, and other Node.js projects with high precision and low false positives.
+
+## Quickstart (No Install)
+
+Run VibeCheck instantly without installation:
+
+```bash
+# Using npx
+npx @quantracode/vibecheck scan --fail-on off --out vibecheck-scan.json
+
+# Using pnpm dlx
+pnpm dlx @quantracode/vibecheck scan --fail-on off --out vibecheck-scan.json
+```
+
+### Scan Another Folder
+
+```bash
+npx @quantracode/vibecheck scan --target ../my-other-app --out scan.json
+```
+
+## Installation
+
+```bash
+npm install -g @quantracode/vibecheck
+# or
+pnpm add -g @quantracode/vibecheck
+```
+
+## Usage
+
+```bash
+# Scan current directory
+vibecheck scan
+
+# Scan specific directory with output file
+vibecheck scan ./my-project --out ./reports/scan.json
+
+# Use --target as alternative to positional argument
+vibecheck scan --target ./my-project
+
+# Output in SARIF format (for GitHub Code Scanning)
+vibecheck scan --format sarif
+
+# Output both JSON and SARIF
+vibecheck scan --format both
+
+# Fail CI if medium or higher findings
+vibecheck scan --fail-on medium
+
+# Disable fail threshold (always exit 0)
+vibecheck scan --fail-on off
+
+# Exclude specific directories
+vibecheck scan -e "**/legacy/**" -e "**/vendor/**"
+
+# Include test files in scan (excluded by default)
+vibecheck scan --include-tests
+
+# Generate intent map with coverage metrics
+vibecheck scan --emit-intent-map
+
+# Explain a scan report
+vibecheck explain ./scan.json
+
+# Start the web viewer
+vibecheck view
+
+# Open viewer with specific artifact
+vibecheck view -a ./scan.json
+```
+
+## View Command
+
+The `view` command starts a local web viewer to explore scan results interactively.
+
+```bash
+# Start viewer (auto-detects artifacts in current directory)
+vibecheck view
+
+# Specify artifact file explicitly
+vibecheck view -a ./vibecheck-scan.json
+vibecheck view --artifact ./scan-results.json
+
+# Use a different port
+vibecheck view --port 8080
+
+# Don't auto-open browser
+vibecheck view --no-open
+
+# Force update the viewer to latest version
+vibecheck view --update
+
+# Clear cached viewer files
+vibecheck view --clear-cache
+```
+
+### 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 | - |
+
+### How It Works
+
+1. **Auto-download**: The viewer is automatically downloaded from npm on first run and cached in `~/.vibecheck/viewer/`
+2. **Auto-detect artifacts**: Looks for scan artifacts in common locations:
+   - `vibecheck-artifacts/artifact.json`
+   - `vibecheck-artifact.json`
+   - `.vibecheck/artifact.json`
+   - `scan-results.json`
+3. **Auto-load**: When an artifact is detected, it's automatically loaded into the viewer
+4. **Local-only**: The viewer runs entirely on your machine with no external connections
+
+### Workflow Example
+
+```bash
+# 1. Run a scan
+vibecheck scan --out vibecheck-artifacts/artifact.json
+
+# 2. View results (artifact auto-detected)
+vibecheck view
+
+# Browser opens to http://localhost:3000 with results loaded
+```
+
+### Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --target <path>` | Target directory to scan | Current directory |
+| `-o, --out <path>` | Output file or directory | `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 with non-zero if findings >= threshold | `high` |
+| `-e, --exclude <glob>` | Glob pattern to exclude (repeatable) | See below |
+| `--include-tests` | Include test files in scan | `false` |
+| `--emit-intent-map` | Include route map and coverage metrics | `false` |
+| `--changed` | Only scan changed files (not implemented) | `false` |
+
+### Default Excludes
+
+The following patterns are excluded by default:
+
+**Core excludes (always applied):**
+- `node_modules`, `dist`, `.git`, `build`, `.next`, `coverage`
+- `.turbo`, `.cache`, `out`, `.vercel`, `.netlify`
+
+**Test excludes (skipped with `--include-tests`):**
+- `__tests__/**`, `*.test.*`, `*.spec.*`
+- `test/`, `tests/`, `fixtures/`, `__mocks__/`, `__fixtures__/`
+- `cypress/`, `e2e/`, `*.stories.*`
+
+## Scanner Packs
+
+VibeCheck organizes security rules into modular scanner packs. Each pack focuses on a specific security domain.
+
+### Auth Pack
+
+Rules for authentication and authorization issues.
+
+#### VC-AUTH-001: Unprotected State-Changing API Route
+
+**Severity:** High / Critical
+**Category:** auth
+
+Detects Next.js App Router API route handlers (POST, PUT, PATCH, DELETE) that perform database operations without authentication checks.
+
+**What it looks for:**
+- Route handlers in `app/**/route.ts` files
+- Handlers that use Prisma, Drizzle, or other database operations
+- Missing calls to `getServerSession`, `auth()`, or similar auth checks
+
+**Example (vulnerable):**
+```typescript
+// app/api/users/route.ts
+export async function POST(request: Request) {
+  const body = await request.json();
+  await prisma.user.create({ data: body }); // No auth check!
+  return Response.json({ success: true });
+}
+```
+
+**Example (safe):**
+```typescript
+// app/api/users/route.ts
+export async function POST(request: Request) {
+  const session = await getServerSession();
+  if (!session) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const body = await request.json();
+  await prisma.user.create({ data: body });
+  return Response.json({ success: true });
+}
+```
+
+---
+
+#### VC-MW-001: Middleware Matcher Gap
+
+**Severity:** High
+**Category:** middleware
+
+Detects Next.js middleware that doesn't cover API routes, potentially leaving them unprotected.
+
+**What it looks for:**
+- `middleware.ts` files with `config.matcher` exports
+- Matchers that exclude `/api` routes
+- Projects using next-auth without middleware protection
+
+**Example (vulnerable):**
+```typescript
+// middleware.ts
+export const config = {
+  matcher: ['/dashboard/:path*'] // Missing /api routes!
+};
+```
+
+**Example (safe):**
+```typescript
+// middleware.ts
+export const config = {
+  matcher: ['/api/:path*', '/dashboard/:path*']
+};
+```
+
+---
+
+### Validation Pack
+
+Rules for input validation issues.
+
+#### VC-VAL-001: Validation Defined But Output Ignored
+
+**Severity:** Medium
+**Category:** validation
+
+Detects cases where validation libraries (Zod, Yup, Joi) are called but the validated result is not used.
+
+**What it looks for:**
+- Calls to `.parse()`, `.validate()`, `.parseAsync()`, etc.
+- Result not assigned to a variable
+- Raw `request.body` or `req.body` used after validation
+
+**Example (vulnerable):**
+```typescript
+const schema = z.object({ name: z.string() });
+schema.parse(body); // Result ignored!
+await prisma.user.create({ data: body }); // Uses unvalidated body
+```
+
+**Example (safe):**
+```typescript
+const schema = z.object({ name: z.string() });
+const validated = schema.parse(body);
+await prisma.user.create({ data: validated });
+```
+
+---
+
+### Privacy Pack
+
+Rules for data privacy and logging issues.
+
+#### VC-PRIV-001: Sensitive Data Logged
+
+**Severity:** High
+**Category:** privacy
+
+Detects logging statements that include sensitive variable names.
+
+**What it looks for:**
+- `console.log`, `console.info`, `console.debug`, `logger.info`, etc.
+- Variables containing: password, secret, token, apiKey, creditCard, ssn, etc.
+
+**Example (vulnerable):**
+```typescript
+console.log("User login:", { email, password }); // Logs password!
+```
+
+**Example (safe):**
+```typescript
+console.log("User login:", { email, timestamp: Date.now() });
+```
+
+---
+
+### Config Pack
+
+Rules for configuration and secrets management issues.
+
+#### VC-CONFIG-001: Undocumented Environment Variable
+
+**Severity:** Low
+**Category:** config
+
+Detects `process.env.VAR` references that aren't documented in `.env.example`.
+
+---
+
+#### VC-CONFIG-002: Insecure Default Secret Fallback
+
+**Severity:** Critical
+**Category:** secrets
+
+Detects hardcoded fallback values for security-critical environment variables.
+
+**What it looks for:**
+- `process.env.VAR || "fallback"` patterns
+- Variables named: SECRET, KEY, TOKEN, PASSWORD, etc.
+- Hardcoded string fallbacks
+
+**Example (vulnerable):**
+```typescript
+const jwtSecret = process.env.JWT_SECRET || "development-secret";
+```
+
+**Example (safe):**
+```typescript
+const jwtSecret = process.env.JWT_SECRET;
+if (!jwtSecret) throw new Error("JWT_SECRET is required");
+```
+
+---
+
+### Network Pack
+
+Rules for network security issues.
+
+#### VC-NET-001: SSRF-Prone Fetch
+
+**Severity:** High
+**Category:** network
+
+Detects fetch/axios calls where the URL is derived from user input without validation.
+
+**What it looks for:**
+- `fetch()` or `axios.get()` calls
+- URL constructed from request parameters, query strings, or body
+- No URL validation or allowlist checks
+
+**Example (vulnerable):**
+```typescript
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const url = searchParams.get("url");
+  const response = await fetch(url); // SSRF risk!
+  return Response.json(await response.json());
+}
+```
+
+**Example (safe):**
+```typescript
+const ALLOWED_HOSTS = ["api.example.com", "cdn.example.com"];
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const url = searchParams.get("url");
+  const parsed = new URL(url);
+  if (!ALLOWED_HOSTS.includes(parsed.hostname)) {
+    return Response.json({ error: "Invalid host" }, { status: 400 });
+  }
+  const response = await fetch(url);
+  return Response.json(await response.json());
+}
+```
+
+---
+
+### Hallucinations Pack
+
+Rules for detecting security libraries that are imported but not properly used.
+
+#### VC-HALL-001: Security Library Imported But Not Used
+
+**Severity:** Medium
+**Category:** middleware
+
+Detects security libraries (helmet, cors, csurf, etc.) that are imported but the import is never used.
+
+**What it looks for:**
+- Imports from security packages: helmet, cors, csurf, express-rate-limit, hpp, etc.
+- Import identifier not referenced after the import statement
+
+**Example (vulnerable):**
+```typescript
+import helmet from "helmet"; // Imported but never used!
+import cors from "cors";
+
+const app = express();
+app.use(cors());
+// Missing: app.use(helmet());
+```
+
+---
+
+#### VC-HALL-002: NextAuth Imported But Not Enforced
+
+**Severity:** High
+**Category:** auth
+
+Detects next-auth imported but `getServerSession` never called, suggesting auth is configured but not enforced.
+
+**What it looks for:**
+- Imports from `next-auth` or `next-auth/next`
+- No calls to `getServerSession` anywhere in the file
+
+---
+
+## Phase 2 Rules
+
+### Network Pack (Extended)
+
+#### VC-NET-002: Open Redirect
+
+**Severity:** High
+**Category:** network
+
+Detects server-side redirects where user-controlled input determines the destination.
+
+**Two-signal requirement:** Must identify user-controlled source AND redirect call uses that value.
+
+**Example (vulnerable):**
+```typescript
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const next = searchParams.get("next");
+  return NextResponse.redirect(next!); // Open redirect!
+}
+```
+
+---
+
+#### VC-NET-003: Over-permissive CORS with Credentials
+
+**Severity:** High
+**Category:** network
+
+Detects CORS configurations that combine `origin: "*"` with `credentials: true`.
+
+**Example (vulnerable):**
+```typescript
+cors({ origin: "*", credentials: true }) // Dangerous combination!
+```
+
+---
+
+#### VC-NET-004: Missing Request Timeout
+
+**Severity:** Low
+**Category:** network
+
+Detects fetch/axios calls without timeout in API route handlers.
+
+**Example (vulnerable):**
+```typescript
+const response = await fetch("https://external-api.com/data"); // No timeout!
+```
+
+---
+
+### Middleware Pack
+
+#### VC-RATE-001: Missing Rate Limiting
+
+**Severity:** Medium
+**Category:** middleware
+**Confidence:** 0.65
+
+Detects unauthenticated state-changing endpoints without rate limiting.
+
+**What it looks for:**
+- POST/PUT/PATCH/DELETE handlers without auth checks
+- Handlers with database writes or sensitive operations
+- No rate limiting signals in handler or middleware
+
+---
+
+### Validation Pack (Extended)
+
+#### VC-VAL-002: Client-Side Only Validation
+
+**Severity:** Medium
+**Category:** validation
+
+Detects validation in frontend components but missing in API routes.
+
+---
+
+### Privacy Pack (Extended)
+
+#### VC-PRIV-002: Over-broad API Response
+
+**Severity:** Medium/High
+**Category:** privacy
+
+Detects Prisma queries returning full models without `select` restrictions.
+
+**Example (vulnerable):**
+```typescript
+const users = await prisma.user.findMany(); // Returns password hash!
+return Response.json(users);
+```
+
+**Example (safe):**
+```typescript
+const users = await prisma.user.findMany({
+  select: { id: true, name: true, email: true }
+});
+return Response.json(users);
+```
+
+---
+
+#### VC-PRIV-003: Debug Flags in Production
+
+**Severity:** Medium
+**Category:** config
+
+Detects `debug: true` or `dev: true` in config files without NODE_ENV guards.
+
+---
+
+### Crypto Pack
+
+#### VC-CRYPTO-001: Math.random for Tokens
+
+**Severity:** High
+**Category:** crypto
+
+Detects Math.random used to generate tokens, keys, or session IDs.
+
+**Example (vulnerable):**
+```typescript
+const token = Math.random().toString(36).substring(2); // Predictable!
+```
+
+**Example (safe):**
+```typescript
+const token = crypto.randomBytes(32).toString('hex');
+```
+
+---
+
+#### VC-CRYPTO-002: JWT Decode Without Verify
+
+**Severity:** Critical
+**Category:** crypto
+
+Detects jwt.decode() used without jwt.verify() in the same file.
+
+**Example (vulnerable):**
+```typescript
+const payload = jwt.decode(token); // Signature not verified!
+```
+
+**Example (safe):**
+```typescript
+const payload = jwt.verify(token, secret); // Signature verified
+```
+
+---
+
+#### VC-CRYPTO-003: Weak Password Hashing
+
+**Severity:** High
+**Category:** crypto
+
+Detects MD5/SHA1 for passwords or bcrypt with saltRounds < 10.
+
+**Example (vulnerable):**
+```typescript
+crypto.createHash('md5').update(password).digest('hex'); // Weak!
+bcrypt.hash(password, 5); // Too few rounds!
+```
+
+---
+
+### Uploads Pack
+
+#### VC-UP-001: File Upload Without Constraints
+
+**Severity:** High
+**Category:** uploads
+
+Detects file uploads without size or type validation.
+
+**Example (vulnerable):**
+```typescript
+const file = formData.get('file') as File;
+// No size or type check before processing
+```
+
+---
+
+#### VC-UP-002: Upload to Public Path
+
+**Severity:** High
+**Category:** uploads
+
+Detects uploaded files written to public directories.
+
+**Example (vulnerable):**
+```typescript
+fs.writeFileSync(`public/uploads/${filename}`, buffer); // Publicly accessible!
+```
+
+---
+
+## Phase 3: Hallucination Detection Engine
+
+Advanced cross-file analysis for detecting security intent vs implementation gaps.
+
+### Intent Command
+
+Generate a security intent map baseline for your codebase:
+
+```bash
+# Generate intent map
+vibecheck intent ./my-project --out intent-map.json
+
+# Include intent map in scan output
+vibecheck scan ./my-project --emit-intent-map
+```
+
+### Hallucinations Pack (Phase 3)
+
+#### VC-HALL-010: Comment Claims Protection But Unproven
+
+**Severity:** Medium
+**Category:** hallucinations
+**Confidence:** 0.75
+
+Detects comments that claim security protection but the implementation doesn't prove it.
+
+**Example (vulnerable):**
+```typescript
+// This route is protected by authentication middleware
+export async function POST(request: Request) {
+  // No auth check here, and middleware doesn't cover /api routes
+  await prisma.user.create({ data: body });
+}
+```
+
+---
+
+#### VC-HALL-011: Middleware Assumed But Not Matching
+
+**Severity:** High
+**Category:** hallucinations
+**Confidence:** 0.70
+
+Detects routes that expect middleware protection but are not covered by matcher patterns.
+
+**Example (vulnerable):**
+```typescript
+// middleware.ts
+export const config = {
+  matcher: ['/dashboard/:path*'], // Missing /api routes!
+};
+
+// app/api/users/route.ts
+// Auth handled by middleware (but middleware doesn't cover this!)
+export async function DELETE(request: Request) {
+  await prisma.user.delete({ where: { id } });
+}
+```
+
+---
+
+#### VC-HALL-012: Validation Claimed But Missing/Ignored
+
+**Severity:** Medium
+**Category:** hallucinations
+**Confidence:** 0.80
+
+Detects validation that is claimed but not properly implemented or used.
+
+**Example (vulnerable):**
+```typescript
+const schema = z.object({ name: z.string() });
+schema.parse(body); // Result ignored!
+await prisma.user.create({ data: body }); // Uses raw body
+```
+
+---
+
+#### VC-AUTH-010: Auth-by-UI with Server Gap
+
+**Severity:** Critical
+**Category:** auth
+**Confidence:** 0.85
+
+Detects client-side auth checks without corresponding server-side protection.
+
+**Example (vulnerable):**
+```tsx
+// Client component
+const { session } = useSession();
+if (session) {
+  // Only render if logged in
+  await fetch('/api/users', { method: 'DELETE' }); // Server has no auth!
+}
+```
+
+---
+
+### Coverage Metrics
+
+With `--emit-intent-map`, the scan artifact includes coverage metrics:
+
+- **authCoverage**: Percentage of state-changing routes with proven auth
+- **validationCoverage**: Percentage of routes with request bodies that have validation
+- **middlewareCoverage**: Percentage of routes covered by middleware matchers
+
+### Intent Map Structure
+
+```json
+{
+  "routeMap": [
+    {
+      "routeId": "abc123",
+      "method": "POST",
+      "path": "/api/users",
+      "file": "app/api/users/route.ts",
+      "startLine": 10,
+      "endLine": 25
+    }
+  ],
+  "middlewareMap": [
+    {
+      "file": "middleware.ts",
+      "matchers": ["/api/:path*"],
+      "protectsApi": true,
+      "startLine": 15
+    }
+  ],
+  "intentMap": [
+    {
+      "intentId": "def456",
+      "type": "AUTH_ENFORCED",
+      "scope": "route",
+      "source": "comment",
+      "textEvidence": "// Protected by auth"
+    }
+  ],
+  "proofTraces": {
+    "abc123": {
+      "routeId": "abc123",
+      "authProven": true,
+      "validationProven": false,
+      "middlewareCovered": true,
+      "steps": [...]
+    }
+  },
+  "coverage": {
+    "authCoverage": 0.85,
+    "validationCoverage": 0.60,
+    "middlewareCoverage": 1.0
+  }
+}
+```
+
+---
+
+## Output Formats
+
+VibeCheck supports two output formats: JSON and SARIF.
+
+### JSON Format
+
+The default format, defined by `@vibecheck/schema`:
+
+```json
+{
+  "artifactVersion": "0.1",
+  "generatedAt": "2024-01-15T10:30:00.000Z",
+  "tool": {
+    "name": "vibecheck",
+    "version": "1.0.0"
+  },
+  "summary": {
+    "totalFindings": 2,
+    "bySeverity": { "critical": 0, "high": 1, "medium": 1, "low": 0, "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",
+      "description": "...",
+      "evidence": [
+        {
+          "file": "app/api/users/route.ts",
+          "startLine": 25,
+          "endLine": 30,
+          "snippet": "...",
+          "label": "Unprotected route handler"
+        }
+      ],
+      "remediation": {
+        "recommendedFix": "Add authentication middleware"
+      },
+      "fingerprint": "sha256:..."
+    }
+  ],
+  "metrics": {
+    "filesScanned": 50,
+    "linesOfCode": 5000,
+    "scanDurationMs": 1234
+  }
+}
+```
+
+### SARIF Format
+
+[SARIF (Static Analysis Results Interchange Format)](https://sarifweb.azurewebsites.net/) is an OASIS standard for static analysis tools. Use `--format sarif` to generate SARIF 2.1.0 output, compatible with:
+
+- **GitHub Code Scanning** - Upload via `github/codeql-action/upload-sarif`
+- **Azure DevOps** - Native SARIF support in security reports
+- **VS Code** - SARIF Viewer extension
+- **Other tools** - Any SARIF 2.1.0 compatible viewer
+
+```bash
+# Generate SARIF for GitHub Code Scanning
+vibecheck scan --format sarif --out results.sarif
+
+# Upload to GitHub (in CI workflow)
+- uses: github/codeql-action/upload-sarif@v2
+  with:
+    sarif_file: results.sarif
+```
+
+## Architecture
+
+```
+packages/cli/src/
+├── commands/
+│   ├── scan.ts         # Main scan orchestrator
+│   └── explain.ts      # Report viewer
+├── scanners/
+│   ├── types.ts        # ScanContext, types
+│   ├── helpers/
+│   │   ├── ast-helpers.ts      # ts-morph utilities
+│   │   └── context-builder.ts  # ScanContext factory
+│   ├── auth/
+│   │   ├── unprotected-api-route.ts  # VC-AUTH-001
+│   │   └── middleware-gap.ts         # VC-MW-001
+│   ├── validation/
+│   │   └── ignored-validation.ts     # VC-VAL-001
+│   ├── privacy/
+│   │   └── sensitive-logging.ts      # VC-PRIV-001
+│   ├── config/
+│   │   ├── undocumented-env.ts       # VC-CONFIG-001
+│   │   └── insecure-defaults.ts      # VC-CONFIG-002
+│   ├── network/
+│   │   └── ssrf-prone-fetch.ts       # VC-NET-001
+│   └── hallucinations/
+│       └── unused-security-imports.ts # VC-HALL-001, VC-HALL-002
+└── index.ts
+```
+
+## Design Principles
+
+1. **Deterministic** - No LLM calls, results are reproducible
+2. **Local-only** - All analysis runs on your machine
+3. **Low false positives** - Precision over recall
+4. **Framework-aware** - Built for Next.js, Express patterns
+5. **Schema-compliant** - Output conforms to `@vibecheck/schema`
+
+## Adding New Scanners
+
+Each scanner must:
+
+1. Accept a `ScanContext` with repo info and AST helpers
+2. Return `Finding[]` conforming to the schema
+3. Generate deterministic fingerprints for deduplication
+4. Include clear evidence with file locations
+
+```typescript
+import { type ScanContext } from "../types.js";
+import { type Finding } from "@vibecheck/schema";
+
+export async function scanMyRule(ctx: ScanContext): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  // ... detection logic
+  return findings;
+}
+```
+
+## License
+
+MIT