npx deepsec init       # creates .deepsec/ directory with project scaffolding
cd .deepsec
pnpm install           # installs deepsec from npm

export AI_GATEWAY_API_KEY=vck_...

# Anthropic
export ANTHROPIC_AUTH_TOKEN=sk-ant-...
export ANTHROPIC_BASE_URL=https://api.anthropic.com

# OpenAI
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1

# Step 1: Find candidate sites with regex matchers (fast, no AI)
pnpm deepsec scan

# Step 2: AI investigation — emits findings + recommendations
pnpm deepsec process

# Step 3: Optional — re-check findings, cuts false positive rate
pnpm deepsec revalidate

# Step 4: Export findings
pnpm deepsec export --format md-dir --out ./findings

import { defineConfig } from 'deepsec';

export default defineConfig({
  projects: [
    {
      id: 'my-app',
      root: '../',          // path to repo root, relative to .deepsec/
      name: 'My Application',
    }
  ],
  // Model selection — defaults to highest capability
  model: {
    scan: 'claude-opus-4',
    triage: 'claude-haiku-4',
  },
  // Concurrency for local processing
  concurrency: 4,
});

// .deepsec/matchers/auth.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'jwt-none-alg',
  description: 'JWT algorithm set to none or not verified',
  severity: 'critical',
  pattern: /jwt\.verify\s*\(|algorithm['":\s]+['"]none['"]/gi,
  fileGlobs: ['**/*.ts', '**/*.js'],
  // Context lines to include around match
  contextLines: 10,
});

// .deepsec/matchers/sql.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'raw-sql-interpolation',
  description: 'String interpolation directly into SQL queries',
  severity: 'high',
  pattern: /`\s*SELECT|INSERT|UPDATE|DELETE.*\$\{/gi,
  fileGlobs: ['**/*.ts', '**/*.js', '**/*.py'],
  contextLines: 15,
  // Provide project-specific context to the AI investigator
  hint: 'Check if user-controlled input reaches query construction. Our ORM is Prisma; raw queries use prisma.$queryRaw.',
});

## Auth
- JWT issued by `lib/auth/jwt.ts` → `signToken()` / `verifyToken()`
- Session middleware: `middleware/session.ts` wraps all `/api/*` routes
- RBAC: `lib/permissions.ts` → `can(user, action, resource)`

## Data Access
- ORM: Prisma via `lib/db.ts` singleton
- Raw queries only in `lib/db/raw.ts` — uses tagged template `sql\`\``
- User input reaches DB through `services/` layer only

## External Inputs
- Webhooks: `app/api/webhooks/` — bodies parsed before signature check in v1 routes
- File uploads: `app/api/upload/` → stored in S3, filenames sanitized by `lib/storage.ts`

## Known Sensitive Areas
- `lib/crypto.ts` — key derivation, do not flag standard bcrypt usage as vuln
- `app/admin/` — intentionally privileged, verify RBAC not auth bypass

# Process using 10 sandboxes, 4 concurrent per sandbox
pnpm deepsec sandbox process \
  --project-id my-app \
  --sandboxes 10 \
  --concurrency 4

# Full distributed pipeline
pnpm deepsec sandbox scan --project-id my-app --sandboxes 5
pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4
pnpm deepsec sandbox revalidate --project-id my-app --sandboxes 5

export VERCEL_ACCESS_TOKEN=your_token_here
export VERCEL_TEAM_ID=team_xxx

# Directory of markdown files (one per finding)
pnpm deepsec export --format md-dir --out ./findings

# Single JSON file with all findings
pnpm deepsec export --format json --out ./findings.json

# Per-finding JSON files
pnpm deepsec export --format json-dir --out ./findings-json

# Summary report for a project
pnpm deepsec report --project-id my-app

# Cross-project metrics
pnpm deepsec metrics

# Current pipeline status
pnpm deepsec status

# If process is interrupted, just re-run — it picks up where it left off
pnpm deepsec process

# Force re-process specific files
pnpm deepsec process --force --file src/auth/login.ts

// .deepsec/plugins/jira-ownership.ts
import { definePlugin } from 'deepsec';

export default definePlugin({
  name: 'jira-ownership',
  hooks: {
    // Called during `enrich` — add owner metadata to findings
    async enrichFinding(finding) {
      const owner = await fetchJiraTeamForPath(finding.file);
      return {
        ...finding,
        metadata: { ...finding.metadata, team: owner },
      };
    },
  },
});

import { defineConfig } from 'deepsec';
import jiraOwnership from './plugins/jira-ownership';

export default defineConfig({
  plugins: [jiraOwnership],
  projects: [{ id: 'my-app', root: '../' }],
});

data/<id>/
  SETUP.md          # one-time agent bootstrap instructions
  INFO.md           # project context injected into every scan batch
  scan/             # FileRecord JSON from matcher pass
  findings/         # AI-produced findings (one JSON per finding)
  revalidated/      # findings after revalidation pass
  run-meta.json     # pipeline state, timestamps, model used

pnpm deepsec scan --include 'src/api/**' --include 'src/auth/**'

pnpm deepsec process --min-severity high

pnpm deepsec process
pnpm deepsec triage          # classify P0/P1/P2 cheaply
pnpm deepsec revalidate --min-priority P0  # only revalidate critical

pnpm deepsec enrich          # adds committer info from git log