oma-deepsec

What it does

Drives Vercel's deepsec agent-powered vulnerability scanner end-to-end in a target repository. It bootstraps the .deepsec/ workspace, writes a project-specific INFO.md, runs a sequence of passes (scan, process, triage, revalidate, export) with cost awareness, gates PRs in CI via process --diff, and supports creating project-specific matchers and triaging findings. It is activated when the user mentions deepsec, asks to scan a repo for vulnerabilities, runs into pnpm deepsec / bunx deepsec commands, or asks about INFO.md / matchers / process --diff / revalidate, even if the tool name isn’t spoken.

How it works

• Entry checks for an existing .deepsec/ workspace; if present, treats the run as incremental. If not, it can initialize with bunx deepsec init.
• It resolves the user intent (setup vs scan vs pr-review vs matchers vs triage vs config) and estimates scale via repo file count to forecast cost.
• It ensures credentials exist (AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, or other supported credential modes) before proceeding.
• It prompts to choose an agent backend (codex or claude) for the first paid call, unless a choice is already pinned or provided by the user.
• It writes or updates data/<id>/INFO.md (50-100 lines) with project-specific sections and examples.
• It executes a calibrated sequence of passes (scan, process with optional --limit/--concurrency, then triage / revalidate / export) and surfaces cost notes.
• In PR mode, it scaffolds a two-job CI pattern using process --diff <base> and a separate comment-out job, wiring the PR gate behavior.
• It supports authoring or wiring project-specific matchers via .deepsec/matchers/<slug>.ts and updates the inline plugin in deepsec.config.ts; it can validate hit rate via bunx deepsec scan --matchers <slug>.
• It includes a verify/finalize stage that reports RunMeta, severity counts, cost, FP rate, and follow-up steps.

When to use it

• On first-time installation of deepsec in a repo (init, INFO.md write).
• When running a full or scoped scan and processing findings.
• To set up a per-PR CI gate with process --diff and optional comment-out workflow.
• To write a project-specific matcher for gaps not covered by defaults.
• To triage a backlog of findings (severity bucketing, FP cuts via revalidate, exporting findings).
• To diagnose deepsec failures (credential issues, quota stops, refusals).

What it can touch

• Commands and files: bunx deepsec init, bunx deepsec scan, bunx deepsec process, bunx deepsec triage, bunx deepsec revalidate, bunx deepsec export, and related options as described. It writes to and reads from .deepsec/ including data/<id>/INFO.md, data/<id>/files/, runs/, and config files, and writes .deepsec/matchers/<slug>.ts and deepsec.config.ts modifications for matchers.

Caveats

• Deepsec scans are costly; a full scan can cost hundreds to tens of thousands of dollars. The skill exists to help manage expectations and budgeting. It requires credentials and configuration; failures may occur due to missing AI credentials, quota limits, or subscription constraints. It emphasizes explicit cost forecasts and user confirmation before expensive passes.