/oma-deepsec

name: oma-deepsec
description: Set up and run Deepsec vulnerability scans, triage, and CI gates.
  Use for Deepsec work or an explicitly requested agent-powered vulnerability
  scan.

Deepsec: Agent-Powered Vulnerability Scanner Driver

Scheduling

Goal

Operate Vercel's `deepsec` security scanner inside a target repository safely and cost-consciously: bootstrap the `.deepsec/` workspace, write a tight `INFO.md`, run the right scan/process/triage/revalidate/export sequence, gate PRs in CI via `process --diff`, and grow project-specific matchers, surfacing real, revalidated findings without runaway spend.

Intent signature

• User mentions `deepsec`, "deep security scan", `bunx deepsec`, `pnpm deepsec`, `npx deepsec`.
• User asks an agent to scan a repository for vulnerabilities, security issues, or CVEs and the project has (or should have) a `.deepsec/` directory.
• User asks how to add a deepsec PR / CI security gate, or about `process --diff`, `--diff-staged`, `--diff-working`, `--files-from`, `--comment-out`.
• User mentions deepsec artefacts: `INFO.md`, `SETUP.md`, `data/<id>/files/`, `FileRecord`, `RunMeta`, `revalidation`, `triage`, custom matchers, `MatcherPlugin`, `noiseTier`, `priorityPaths`.
• User asks about deepsec configuration: `deepsec.config.ts`, `defaultAgent`, `AI_GATEWAY_API_KEY`, `VERCEL_OIDC_TOKEN`, AI Gateway, Vercel Sandbox, `--agent codex`, `--agent claude`.
• User asks how to lower deepsec cost, cut false-positive rate, or interpret severity / triage / revalidation verdicts.

When to use

• First-time deepsec install in a repo (`init`, `INFO.md` write, first calibration scan).
• Running a full or scoped scan and processing findings.
• Setting up a per-PR CI gate with `process --diff` and `--comment-out`.
• Writing a project-specific matcher to cover entry points the default set misses.
• Triaging a backlog of findings (severity bucketing, FP cuts via `revalidate`, exporting to issue tracker).
• Diagnosing deepsec failures: missing credentials, AI Gateway quota stops, refusals, sandbox auth.

When NOT to use

• Generic OWASP / lint-style review without deepsec → use `oma-qa`.
• Generic CVE / dependency advisories → use `oma-qa` or `oma-search`.
• Architecting a brand-new SAST pipeline that is not deepsec → use `oma-architecture`.
• Writing or auditing application code itself → route to `oma-backend` / `oma-frontend` / `oma-mobile`.
• Cloud / IAM / Terraform hardening → use `oma-tf-infra` (deepsec only scans the IaC; remediation lives there).
• Pure reasoning about a finding's fix in product code → use `oma-debug` once deepsec has produced the finding.

Expected inputs

• `target_repo_root`: absolute path of the codebase to scan (parent of `.deepsec/`).
• `intent`: one of `setup` | `scan` | `pr-review` | `matchers` | `triage` | `config` | `troubleshoot`.
• `credential_mode`: `ai-gateway-key` | `vercel-oidc` | `direct-anthropic` | `direct-openai` | `subscription`.
• `agent_choice`: `codex` (upstream default; model `gpt-5.5`) or `claude` (model `claude-opus-4-8`). Asked once before the first paid call if not already provided.
• `severity_floor`: lowest severity worth surfacing (typically `HIGH`).
• Optional: existing `.deepsec/data/<id>/`, `deepsec.config.ts`, custom matchers, CI provider.

Expected outputs

• A working `.deepsec/` workspace registered against the target repo.
• A populated `data/<id>/INFO.md` (50-100 lines, project-specific, no line numbers).
• One or more completed `scan` → `process` (→ `triage`/`revalidate`) runs with reproducible cost notes.
• For PR mode: a CI workflow file using `process --diff <base>` with two-job split (no PR-write in PR-code job).
• For matchers: new `.deepsec/matchers/<slug>.ts` files wired through the inline plugin in `deepsec.config.ts`.
• A findings export (`md-dir` and/or `json`) plus a short summary of top severities and FP-rate notes.
• Explicit, dollar-and-time-bounded plan before any pass that may cost more than ~$25.

Dependencies

• Node.js **22+**, plus a package manager: `bun` / `bunx` (preferred in this monorepo), `pnpm`, `npm`, or `yarn`.
• A working AI credential: `AI_GATEWAY_API_KEY=vck_…`, or `VERCEL_OIDC_TOKEN`, or direct `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL`, or a logged-in `claude` / `codex` CLI subscription.
• Git (history is consulted by `revalidate` and `--diff` modes).
• Optional: Vercel Sandbox auth for `deepsec sandbox …` distributed runs.
• Reference resources under `resources/` (loaded only when the scenario requires them).

Control-flow features

• Branches by `intent` (setup vs scan vs pr-review vs matchers vs triage vs config vs troubleshoot).
• Branches by repo size (calibrate with `--limit 50` before any large pass).
• Branches by credential source (gateway key, OIDC, direct, subscription).
• Stops on quota / credit exhaustion and resumes the same command after top-up.
• Refuses to launch an unbounded `process` when no calibration has been done and the repo is large.
• Reads codebase, writes `.deepsec/` files and CI configs, runs long-lived AI processes.

Structural Flow

Entry

1. Confirm whether `.deepsec/` already exists; if yes, treat the run as **incremental**, never re-init. 2. Resolve `intent` from the user prompt; if ambiguous (e.g. "scan this repo"), default to `setup` then `scan` (calibration mode). 3. Estimate scale: count source files (rough `rg --files | wc -l` excluding `node_modules`, `.git`, `dist`) to forecast cost before any AI pass. 4. Check for an AI credential in `.env.local` or shell env; if none, route to credential setup before any `process` / `revalidate` / `triage` call. 5. **Confirm agent choice with the user before the first paid call.** If `agent_choice` is not already in the prompt and `deepsec.config.ts` does not pin a `defaultAgent`, ask whether to run `codex` (`gpt-5.5`, the upstream default; runs in a strict sandbox, cheaper, grep-heavy) or `claude` (`claude-opus-4-8`; strongest reasoning, most expensive). T