deepsec-docs

• build.mjs
• package.json
• src/__tests__/agent-config.test.ts
• src/__tests__/agent-defaults.test.ts
• src/__tests__/credential-brokering.test.ts
• src/__tests__/ensure-connected-workspace.test.ts
• src/__tests__/env-file.test.ts
• src/__tests__/file-sources.test.ts
• src/__tests__/formatters.test.ts
• src/__tests__/merge-records.test.ts
• src/__tests__/metrics.test.ts
• src/__tests__/model-picker.test.ts
• src/__tests__/model-route.test.ts
• src/__tests__/network-policy.test.ts
• src/__tests__/output-cap.test.ts
• src/__tests__/pr-comment.test.ts
• src/__tests__/preflight.test.ts
• src/__tests__/resolve-agent-type.test.ts
• src/__tests__/resolve-project-id.test.ts
• src/__tests__/sandbox-tools.test.ts
• src/__tests__/setup-coordinator.test.ts
• src/__tests__/setup-coverage.test.ts
• src/__tests__/setup-fingerprint.test.ts
• src/__tests__/setup-generated-matchers.test.ts
• src/__tests__/setup-install.test.ts
• src/__tests__/setup-interaction.test.ts
• src/__tests__/setup-lock.test.ts
• src/__tests__/setup-options.test.ts
• src/__tests__/setup-output.test.ts
• src/__tests__/setup-persisted-route.test.ts
• src/__tests__/setup-plan.test.ts
• src/__tests__/setup-project-name.test.ts
• src/__tests__/setup-protocol.test.ts
• src/__tests__/setup-reporter.test.ts
• src/__tests__/setup-repository-analysis.test.ts
• src/__tests__/setup-state.test.ts
• src/__tests__/setup-tui.test.ts
• src/__tests__/setup-workspace-config.test.ts
• src/__tests__/tarball.test.ts
• src/__tests__/vercel-link.test.ts
• src/agent-config.ts
• src/agent-defaults.ts
• src/atomic-file.ts
• src/auth/ensure-connected-workspace.ts
• src/auth/model-picker.ts
• src/auth/model-route-prompt.ts
• src/auth/model-route.ts
• src/auth/vercel-link.ts
• src/cli.ts
• src/commands/enrich.ts
• src/commands/export.ts
• src/commands/init-project.ts
• src/commands/init.ts
• src/commands/metrics.ts
• src/commands/process.ts
• src/commands/report.ts
• src/commands/revalidate.ts
• src/commands/sandbox-all.ts
• src/commands/sandbox-process.ts
• src/commands/scan.ts
• src/commands/setup.ts
• src/commands/status.ts
• src/commands/triage.ts
• src/config.ts
• src/data-commit.ts
• src/env-file.ts
• src/file-sources.ts
• src/formatters.ts
• src/load-config.ts
• src/output-cap.ts
• src/pr-comment.ts
• src/preflight.ts
• src/quota-message.ts
• src/require-dir.ts
• src/resolve-agent-type.ts
• src/resolve-project-id.ts
• src/sandbox/download.ts
• src/sandbox/merge-records.ts
• src/sandbox/orchestrator.ts
• src/sandbox/partitioner.ts
• src/sandbox/request-proxy.mjs
• src/sandbox/setup.ts
• src/sandbox/shutdown.ts
• src/sandbox/state.ts
• src/sandbox/types.ts
• src/sandbox/upload.ts
• src/setup/coordinator.ts
• src/setup/coverage.ts
• src/setup/fingerprint.ts
• src/setup/generated-matchers.ts
• src/setup/install.ts
• src/setup/interaction.ts
• src/setup/lock.ts
• src/setup/options.ts
• src/setup/output.ts
• src/setup/persisted-route.ts
• src/setup/plan.ts
• src/setup/project-name.ts
• src/setup/protocol.ts
• src/setup/reporter.ts

SKILL.md

---
name: deepsec-docs
description: Use deepsec (an AI-powered vulnerability scanner) — one-shot initialization, resumable setup, project/model credentials, scans, generated or hand-authored matchers, and plugins. Activates when the user asks how to initialize, scan, configure, resume, or extend deepsec.
---

# deepsec

`deepsec` is an AI-powered vulnerability scanner. The one-shot initializer
installs this skill at `.deepsec/node_modules/deepsec/SKILL.md`. From inside
the isolated workspace the same path is `node_modules/deepsec/SKILL.md`. In a
Deepsec source clone, use the repository's `docs/` directory instead.

When the user asks how to use, configure, or extend deepsec, read the
relevant doc before answering — the docs are the source of truth, not
your training data.

## Where the docs are

From the target repository, `.deepsec/node_modules/deepsec/dist/docs/`; from
inside `.deepsec`, `node_modules/deepsec/dist/docs/`; or from a Deepsec source
clone, `<deepsec-clone>/docs/`:

- `getting-started.md` — one-shot initialization and resume walkthrough
- `configuration.md` — full `deepsec.config.ts` reference
- `plugins.md` — plugin slots (matchers, notifiers, ownership, people, executor)
- `writing-matchers.md` — generated declarative vs hand-authored matchers
- `models.md` — model selection, defaults, refusals, future models
- `vercel-setup.md` — exact project link, Sandbox scope, Gateway/BYOK/custom routes
- `architecture.md` — pipeline internals
- `data-layout.md` — `data/` schemas (FileRecord, RunMeta, …)
- `faq.md` — cost, model choice, sandbox mode, FP rate

## How to answer common questions

- **"How do I install/init deepsec?"** → `getting-started.md`; default to `npx deepsec init`, not a manual install/scan recipe.
- **"Setup stopped; how do I resume?"** → `getting-started.md` + `data-layout.md`; re-run init or `deepsec setup`.
- **"How do I run another scan?"** → `getting-started.md` after noting the first scan/process already ran during setup.
- **"What goes in `deepsec.config.ts`?"** → `configuration.md` + `samples/webapp/deepsec.config.ts`.
- **"Why did setup generate a matcher?"** → `writing-matchers.md` + the project's `generated-matchers.ts`.
- **"How do I add a richer matcher?"** → `writing-matchers.md` + `samples/webapp/matchers/*.ts`.
- **"How do I write a plugin?"** → `plugins.md` + `samples/webapp/deepsec.config.ts` (inline plugin pattern).
- **"What does deepsec actually do?"** → `architecture.md`.
- **"What's in `data/<id>/files/foo.json`?"** → `data-layout.md`.
- **"Which model / agent should I use?"** → `models.md`.
- **"How do project linking, Sandbox, or my own credentials work?"** → `vercel-setup.md`.

Read the doc before paraphrasing. The CLI flag set, defaults, and
plugin-contract field names change — quote the doc, don't recall.

## Agent-native initialization

When you are asked to initialize Deepsec from a non-TTY agent session, first
inspect the read-only plan:

```bash
npx deepsec init --plan --output json
```

Then run the requested policy, normally:

```bash
npx deepsec init --yes --model-profile value --output jsonl
```

Parse every output line as JSON. On `needs_input`, show the supplied message
and actions to the user rather than inventing remediation. In particular,
`VERCEL_AUTH_REQUIRED` normally asks the user to run `npx vercel login`; after
they do, follow the returned link action from inside `.deepsec`. Use
`npx vercel link` when the user needs to choose, or the returned parameterized
`--yes --team <team-slug> --project <project-name>` form for a known existing
project. Then rerun the same Deepsec command. Exit code 2 means input is needed
and exit code 3 means a requested cost/duration boundary stopped the resumable
run. Never expose credential values, bypass `--yes`, or launch an interactive
login yourself.