---

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: use the user-named backend, configured defaultAgent, or a choice within delegated scope; ask only when a material choice remains unresolved.
• 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. Resolve the selected credential mode and backend. Check its required environment configuration or an existing claude / codex subscription login, without echoing secrets. A valid subscription session does not require an API-key environment variable. Resolve only missing configuration before AI calls.
5. Resolve backend, scope, and spend from existing instructions and configuration under ../_shared/core/execution-policy.md. Before paid or custom-scope work, record the actual approved, limited, or declined action using resources/decision-records.md. A configured backend does not authorize additional spend; ask only for a material missing choice or new authorization.

Transitions

• If .deepsec/ is missing and intent involves scanning → run bunx deepsec init (or npx deepsec init) and follow the printed prompt to populate INFO.md before any AI pass.
• If INFO.md is empty or template-shaped → write it (50-100 lines, project-specific, 3-5 examples per section, no line numbers, no generic CWE enumeration).
• If repo is > 500 files and no calibration has run → run a calibration pass first (deepsec docs recommend --limit 50 --concurrency 5) and report cost extrapolation before the full pass.
• If a process / revalidate run halts on quota → leave file locks intact, surface the exact remediation URL, re-run the same command after top-up.
• If the agent reports a refusal (refused: true) → never silently drop; document the affected files and either retry with the other backend or add the path to config.json:ignorePaths only if reproducible.
• If the user wants a CI gate → emit the two-job pattern (PR-code job has no pull-requests: write, comment job has no PR code).
• If the user wants more matcher coverage → run the matcher-authoring workflow against data/<id>/files/ and the parent repo's entry points.

Failure and recovery

| Failure | Recovery | |---------|----------| | Missing AI credentials for --agent claude / codex | Check the selected mode per resources/config.md: environment configuration for key/OIDC/direct modes, or CLI login for subscription mode. Do not require .env.local credentials for a valid subscription session. | | 401 Unauthorized from gateway | OIDC: re-run vercel env pull (12 h expiry). API key: regenerate. Confirm .env.local is in the cwd deepsec runs from. | | Stopped: AI Gateway credits exhausted | Top up via the printed URL; re-run the same command, files already done are skipped. | | Stopped: Claude Pro/Max subscription exhausted | Switch to AI Gateway; subscriptions don't carry full scans. | | Persistent refusal on a single file (>5% of batches) | Add the path to data/<id>/config.json:ignorePaths, or run that file alone with --batch-size 1. | | FP rate too high on HIGH+ | Run revalidate --min-severity HIGH; tighten INFO.md's threat model and FP notes; bias matchers to precise. | | noisy matcher wedges scanner on a 100k-file repo | Tighten filePatterns to language- or directory-anchored globs. | | Sandbox auth fails | OIDC: re-run vercel env pull. Access-token mode: verify VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. | | Full pass exceeds existing scope or spend authorization | Report the calibrated estimate and preserve completed free/limited work. Resolve only the missing authorization; record the actual approved, limited, or declined pass before executing it. |

Exit

• Success: planned passes ran, findings exist with verdicts (or no findings produced), files written are listed, residual cost / followups are explicit.
• Partial success: some passes blocked on credentials/quota/refusal; the blocker, the safe-resume command, and the recommended next step are reported.
• Failure: nothing destructive happened, the user has the exact next command to unblock the work.

Logical Operations

Tools and instruments

• Package manager: bun / bunx (preferred), pnpm, npm, yarn are interchangeable.
• CLI commands: deepsec init, init-project, scan, process, process --diff, triage, revalidate, enrich, report, export, metrics, status, sandbox <cmd>.
• Diff sources for PR mode: --diff <ref|range>, --diff-staged, --diff-working, --files <csv>, --files-from <path> (or - for stdin).
• Inspection: jq over data/<id>/files/**/*.json for ad-hoc severity / TP queries.
• Credentials: AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL, OPENAI_API_KEY / OPENAI_BASE_URL, claude login, codex login.
• Resource files under resources/ for setup, scanning, PR review, matchers, triage, config, load on demand.

Canonical workflow path

1. Bootstrap (one time per repo):

   cd <target-repo>
   bunx deepsec init
   cd .deepsec
   bun install
   # Edit .env.local: set AI_GATEWAY_API_KEY=vck_… (or VERCEL_OIDC_TOKEN via `vercel env pull`)
   

   Then prompt the coding agent (this skill) to read .deepsec/node_modules/deepsec/SKILL.md and .deepsec/data/<id>/SETUP.md, skim README / AGENTS.md / CLAUDE.md and a handful of representative files, and replace each section of data/<id>/INFO.md (50-100 lines, 3-5 examples per section, no line numbers, no generic CWE rehash).
2. Calibrate before any full pass. First record the selected authorized calibration scope using resources/decision-records.md; --limit bounds files, not dollar spend. The deepsec docs (getting-started.md, vercel-setup.md, faq.md) recommend --limit 50 --concurrency 5 as the calibration starting point.

   bunx deepsec scan
   bunx deepsec status
   bunx deepsec process --limit 50 --concurrency 5
   

   Read the run cost and extrapolate to the full repo using resources/scanning.md. Reuse existing authorization covering the backend, scope, and estimated spend. Record the actual scope decision before calibration and again before an expanded pass; resolve only missing authorization. If the user names different --limit / --concurrency values, use theirs.
3. Full investigation, triage, revalidate, export:

   bunx deepsec process --concurrency 5
   bunx deepsec triage --severity HIGH
   bunx deepsec revalidate --min-severity HIGH
   

   Record and verify every triaged finding's actual verdict using resources/decision-records.md before filtering or suppression, including findings that will not be surfaced. Then export: ``