Deepsec

DeepSec Dev3000 Runbook

Use this skill to turn the manual DeepSec workflow into a repeatable dev3000 run against the current Vercel project checkout.

Operating Policy

• Work from the real project checkout at /workspace/repo.
• Do not write AI credentials into .deepsec/.env.local or any tracked file. The dev3000 runtime passes AI Gateway credentials through the process environment.
• Default dev3000 runs are a bounded first pass. Do not run an unbounded process or revalidate command unless the user explicitly asks for a full DeepSec scan in run-specific instructions.
• Keep generated scan state in the locations DeepSec already gitignores. Commit only the durable setup/context files and human-readable findings report.
• Treat DeepSec as a coding agent with shell access. Do not run it on untrusted source inputs.

Default Flow

1. Inspect the project shape:

• Read README.md if present.
• Read AGENTS.md or CLAUDE.md if present.
• Skim representative files for auth, middleware, request handlers, data access, billing, webhooks, and security-sensitive boundaries.

2. Initialize DeepSec if needed:

• If .deepsec/ is absent, run npx --yes deepsec@latest init.
• If .deepsec/ already exists, do not force overwrite it.

3. Install DeepSec workspace dependencies:

• Run corepack pnpm install from .deepsec/.
• Ensure the Claude Agent SDK native binary that DeepSec actually uses is available. Do not run a Claude Code postinstall; DeepSec uses @anthropic-ai/claude-agent-sdk.
• If corepack pnpm is unavailable, run pnpm install only after confirming pnpm exists.

4. Fill the generated project context:

• Read .deepsec/node_modules/deepsec/SKILL.md.
• Read .deepsec/data/<id>/SETUP.md.
• Replace .deepsec/data/<id>/INFO.md with concise project-specific context.
• Keep INFO.md to roughly 50-100 lines.
• Use 3-5 examples per section. Name local primitives such as auth helpers, middleware, database clients, webhook handlers, and privileged APIs.
• Do not include line numbers, generic CWE lists, or broad framework summaries.

5. Run the scan:

• Run corepack pnpm deepsec scan from .deepsec/.

6. Run bounded AI processing:

• Default command: corepack pnpm deepsec process --limit 25 --concurrency 2 --batch-size 3.
• If the candidate set is below the limit, state that all discovered candidates were processed.
• If the user explicitly requested a full run, use the requested limit/concurrency or omit --limit.
• If the process command fails, stop and report the failure. Do not generate a manual fallback report from regex candidates.

7. Generate the findings report:

• Run corepack pnpm deepsec export --format md-dir --out ./findings.
• If there are no findings, create .deepsec/findings/README.md summarizing that this bounded pass found no findings and include the exact commands that were run.

8. Summarize the run:

• Include commands run, project id, limit/concurrency, and whether the report contains findings.
• Do not include a "Next Steps - Full Scan" section by default.
• Only include a follow-up scan section if DeepSec reports unprocessed candidates or the user explicitly asked about deeper coverage. Label it "Optional Deeper Follow-Up" and explain exactly how it differs from the completed run.

Validation

• Prefer DeepSec's own command output, corepack pnpm deepsec status, and generated finding files as validation.
• Do not start a dev server or browser unless the user explicitly asks for visual/runtime verification.
• Before finishing, check git diff --stat and make sure no secrets, node_modules, .env.local, or raw scan state are staged by accident.