Security Scan Workflow
On-demand Security and Review Skills security scans investigate a designated repo with explicit cost approval, verified findings, and post-scan documentation.
Kevin must invoke explicitly: "Run the security-scan automation against <repo>." This workflow is manual-only because full deepsec processing can be expensive and high-impact. Source: automations/security-scan.md, 2026-05-31
Routing
Use this workflow for a full repo security scan. Use ordinary code review for small diffs, Code Bugfix Workflow for recent author-owned regressions, and postmortem pages only after a verified issue or material lesson exists.
Cost gate
Full Opus/GPT max-effort scans can run from tens to thousands of dollars. Always calibrate first and get Kevin's explicit approval for projected total cost before full processing.
pnpm deepsec process --limit 50 --concurrency 5
Do not convert this workflow into a cron. The cost gate is part of the safety model, not a polite suggestion wearing a tiny hat.
Inputs
- Target repo path.
- Budget or explicit permission to ask for one.
- Backend choice: Claude/Opus default or Codex/GPT when configured.
- deepsec config and prior
.deepsec/state if present. - Brin verdict for public or external repos.
Runbook
- Verify repo, credentials, Node/pnpm, and backend access.
- Run Brin on untrusted external repos and block suspicious or dangerous verdicts.
- Initialize
.deepsec/only if needed. - Fill or refresh
INFO.mdfrom repo-specific architecture and conventions. - Run regex scan and report candidate count.
- Calibrate with a limited AI process run, compute projected total cost, and pause for approval.
- After approval, process the remaining candidates.
- Run triage, revalidation, enrichment, export, and metrics.
- Manually verify every Critical and High finding before presenting it.
- Write output and update wiki pages only for verified durable findings or reusable patterns.
Output
- Findings under
<target>/.deepsec/findings/. - JSON and markdown exports from deepsec.
outputs/<YYYY-MM-DD>/security-scan/<agent>.md.wiki/log.mdscan entry with cost, backend, scanned files, candidates, and verified finding counts.- Postmortem or Security and Review Skills tool updates only when warranted.
Validation
Every Critical or High item must include file:line, bug class, data flow, reachability, and suggested fix. Medium items can be grouped by class. Revalidated false positives should be reported as discarded, not silently omitted.
Failure Handling
Stop the workflow when budget approval is missing, credentials are unavailable, Brin blocks the repo, deepsec cannot export, or Critical/High findings cannot be manually verified. Partial scan state is acceptable if the output says where it stopped and how to resume.
Run Contract
This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.
Timeline
- 2026-07-01 | Expanded into a full manual-only security scan runbook with cost gate, inputs, runbook, output, validation, and failure handling. Source: User request, 2026-07-01
- 2026-05-31 | Workflow page created from security-scan automation (manual-only, cost-aware). Source: automations/security-scan.md, 2026-05-31