deepsec-vulnerability-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

deepsec Vulnerability Scanner

deepsec 漏洞扫描器

Skill by ara.so — Daily 2026 Skills collection.

deepsec

is an agent-powered vulnerability scanner that uses coding agents (Claude, Codex) at maximum thinking levels to surface hard-to-find security issues in large codebases. It uses regex matchers to find candidate sites, then AI to deeply investigate each one, producing actionable findings with severity ratings.

由ara.so开发的技能——Daily 2026技能合集。

deepsec

是一款基于Agent的漏洞扫描器，它借助编码Agent（Claude、Codex）以最高思考级别来发现大型代码库中难以察觉的安全问题。它使用正则表达式匹配器查找候选目标，再通过AI深入调查每个目标，生成带有严重程度评级的可操作检测结果。

Installation

安装

Navigate to the root of the repo you want to scan:

bash

npx deepsec init       # creates .deepsec/ directory with project scaffolding
cd .deepsec
pnpm install           # installs deepsec from npm

After init, bootstrap the installation by prompting your coding agent:

Read
.deepsec/node_modules/deepsec/SKILL.md
to understand the tool. Then read
.deepsec/data/<id>/SETUP.md
and follow it: skim this repo's README, any AGENTS.md/CLAUDE.md, and a handful of representative code files, then replace each section of
.deepsec/data/<id>/INFO.md
. Keep it SHORT — target 50–100 lines total.

导航到你想要扫描的代码库根目录：

bash

npx deepsec init       # 创建包含项目脚手架的.deepsec/目录
cd .deepsec
pnpm install           # 从npm安装deepsec

初始化完成后，通过提示你的编码Agent来完成安装引导：

阅读
.deepsec/node_modules/deepsec/SKILL.md
以了解该工具。然后阅读
.deepsec/data/<id>/SETUP.md
并按照说明操作：浏览此代码库的README、任何AGENTS.md/CLAUDE.md，以及一些具有代表性的代码文件，然后替换
.deepsec/data/<id>/INFO.md
的每个部分。内容要简短——目标总长度为50–100行。

AI Provider Setup

AI提供商设置

Vercel AI Gateway (recommended for large scans)

Vercel AI Gateway（大型扫描推荐）

bash

export AI_GATEWAY_API_KEY=vck_...

One key covers both Claude and Codex. Get a key from the Vercel dashboard.

bash

export AI_GATEWAY_API_KEY=vck_...

一个密钥可同时用于Claude和Codex。从Vercel控制台获取密钥。

Direct provider keys (bypasses gateway)

直接使用提供商密钥（绕过网关）

bash

undefined

bash

undefined

Anthropic

export ANTHROPIC_AUTH_TOKEN=sk-ant-... export ANTHROPIC_BASE_URL=https://api.anthropic.com

OpenAI

export OPENAI_API_KEY=sk-... export OPENAI_BASE_URL=https://api.openai.com/v1


Explicit values always win over `AI_GATEWAY_API_KEY` expansion.

export OPENAI_API_KEY=sk-... export OPENAI_BASE_URL=https://api.openai.com/v1


显式设置的值始终优先于`AI_GATEWAY_API_KEY`的扩展值。

Core Workflow

核心工作流程

Run these commands from inside

.deepsec/

bash

undefined

在

.deepsec/

目录内运行以下命令：

bash

undefined

Step 1: Find candidate sites with regex matchers (fast, no AI)

步骤1：使用正则表达式匹配器查找候选目标（快速，无需AI）

pnpm deepsec scan

Step 2: AI investigation — emits findings + recommendations

步骤2：AI调查——输出检测结果及建议

pnpm deepsec process

Step 3: Optional — re-check findings, cuts false positive rate

步骤3：可选——重新检查检测结果，降低误报率

pnpm deepsec revalidate

Step 4: Export findings

步骤4：导出检测结果

pnpm deepsec export --format md-dir --out ./findings

undefined

pnpm deepsec export --format md-dir --out ./findings

undefined

Full Command Reference

完整命令参考

Command	What it does
`scan`	Regex matcher pass — fast, no AI cost
`process`	AI deep-investigation of candidates
`triage`	Lightweight P0/P1/P2 classification (cheaper model)
`revalidate`	Re-check findings; checks git history for fixes
`enrich`	Add git committer info + ownership data
`report`	Markdown + JSON summary for one project
`export`	Per-finding JSON or directory of markdown files
`metrics`	Cross-project counts: severities, vulns by type, TPs
`status`	Snapshot of the project mirror
`sandbox <cmd>`	Run any command on Vercel Sandbox microVMs

命令	功能
`scan`	正则表达式匹配器扫描——速度快，无AI成本
`process`	对候选目标进行AI深度调查
`triage`	轻量级P0/P1/P2分类（使用低成本模型）
`revalidate`	重新检查检测结果；查看Git历史记录中的修复情况
`enrich`	添加Git提交者信息及归属数据
`report`	单个项目的Markdown + JSON汇总报告
`export`	按检测结果导出JSON或Markdown文件目录
`metrics`	跨项目统计：严重程度、漏洞类型、真实阳性数量
`status`	项目镜像的快照状态
`sandbox <cmd>`	在Vercel Sandbox微虚拟机上运行任意命令

Configuration

配置

Create

deepsec.config.ts

in your

.deepsec/

directory:

typescript

import { defineConfig } from 'deepsec';

export default defineConfig({
  projects: [
    {
      id: 'my-app',
      root: '../',          // path to repo root, relative to .deepsec/
      name: 'My Application',
    }
  ],
  // Model selection — defaults to highest capability
  model: {
    scan: 'claude-opus-4',
    triage: 'claude-haiku-4',
  },
  // Concurrency for local processing
  concurrency: 4,
});

See

docs/configuration.md

for the full

deepsec.config.ts

reference.

在

.deepsec/

目录中创建

deepsec.config.ts

：

typescript

import { defineConfig } from 'deepsec';

export default defineConfig({
  projects: [
    {
      id: 'my-app',
      root: '../',          // 相对于.deepsec/的代码库根目录路径
      name: 'My Application',
    }
  ],
  // 模型选择——默认使用最高性能模型
  model: {
    scan: 'claude-opus-4',
    triage: 'claude-haiku-4',
  },
  // 本地处理的并发数
  concurrency: 4,
});

完整的

deepsec.config.ts

参考请查看

docs/configuration.md

。

Writing Custom Matchers

编写自定义匹配器

Matchers are regex patterns that identify candidate code sites for AI investigation. Prompt your coding agent with the writing-matchers doc to grow your matcher set:

Read
docs/writing-matchers.md
and add matchers for [specific concern] in our codebase.

Example matcher file structure:

typescript

// .deepsec/matchers/auth.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'jwt-none-alg',
  description: 'JWT algorithm set to none or not verified',
  severity: 'critical',
  pattern: /jwt\.verify\s*\(|algorithm['":\s]+['"]none['"]/gi,
  fileGlobs: ['**/*.ts', '**/*.js'],
  // Context lines to include around match
  contextLines: 10,
});

typescript

// .deepsec/matchers/sql.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'raw-sql-interpolation',
  description: 'String interpolation directly into SQL queries',
  severity: 'high',
  pattern: /`\s*SELECT|INSERT|UPDATE|DELETE.*\$\{/gi,
  fileGlobs: ['**/*.ts', '**/*.js', '**/*.py'],
  contextLines: 15,
  // Provide project-specific context to the AI investigator
  hint: 'Check if user-controlled input reaches query construction. Our ORM is Prisma; raw queries use prisma.$queryRaw.',
});

匹配器是用于识别AI调查候选代码位置的正则表达式模式。提示你的编码Agent阅读编写匹配器文档来扩展匹配器集合：

阅读
docs/writing-matchers.md
并为我们代码库中的[特定关注点]添加匹配器。

示例匹配器文件结构：

typescript

// .deepsec/matchers/auth.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'jwt-none-alg',
  description: 'JWT算法设置为none或未验证',
  severity: 'critical',
  pattern: /jwt\.verify\s*\(|algorithm['":\s]+['"]none['"]/gi,
  fileGlobs: ['**/*.ts', '**/*.js'],
  // 匹配结果周围包含的上下文行数
  contextLines: 10,
});

typescript

// .deepsec/matchers/sql.ts
import { defineMatcher } from 'deepsec';

export default defineMatcher({
  id: 'raw-sql-interpolation',
  description: '直接将字符串插值到SQL查询中',
  severity: 'high',
  pattern: /`\s*SELECT|INSERT|UPDATE|DELETE.*\$\{/gi,
  fileGlobs: ['**/*.ts', '**/*.js', '**/*.py'],
  contextLines: 15,
  // 为AI调查人员提供项目特定上下文
  hint: '检查用户可控输入是否到达查询构建环节。我们的ORM是Prisma；原生查询使用prisma.$queryRaw。',
});

INFO.md: Project Context for AI

INFO.md：AI所需的项目上下文

The

INFO.md

file is injected into every scan batch. Keep it 50–100 lines:

markdown

undefined

INFO.md

文件会注入到每个扫描批次中。内容保持在50–100行：

markdown

undefined

Auth

认证

JWT issued by
```
lib/auth/jwt.ts
```
→
```
signToken()
```
/
```
verifyToken()
```
Session middleware:
```
middleware/session.ts
```
wraps all
```
/api/*
```
routes

RBAC:

lib/permissions.ts

→

can(user, action, resource)

JWT由
```
lib/auth/jwt.ts
```
生成 →
```
signToken()
```
/
```
verifyToken()
```
会话中间件：
```
middleware/session.ts
```
包裹所有
```
/api/*
```
路由

基于角色的访问控制（RBAC）：

lib/permissions.ts

→

can(user, action, resource)

Data Access

数据访问

ORM: Prisma via
```
lib/db.ts
```
singleton
Raw queries only in
```
lib/db/raw.ts
```
— uses tagged template
```
sql\
```
``
User input reaches DB through
```
services/
```
layer only

ORM：通过
```
lib/db.ts
```
单例使用Prisma
仅在
```
lib/db/raw.ts
```
中使用原生查询——使用标记模板
```
sql\
```
``
用户输入仅通过
```
services/
```
层到达数据库

External Inputs

外部输入

Webhooks:
```
app/api/webhooks/
```
— bodies parsed before signature check in v1 routes
File uploads:
```
app/api/upload/
```
→ stored in S3, filenames sanitized by
```
lib/storage.ts
```

Webhooks：
```
app/api/webhooks/
```
—— v1路由中签名验证前会解析请求体
文件上传：
```
app/api/upload/
```
→ 存储在S3中，文件名由
```
lib/storage.ts
```
清理

Known Sensitive Areas

已知敏感区域

```
lib/crypto.ts
```
— key derivation, do not flag standard bcrypt usage as vuln
```
app/admin/
```
— intentionally privileged, verify RBAC not auth bypass

undefined

```
lib/crypto.ts
```
—— 密钥派生，请勿将标准bcrypt使用标记为漏洞
```
app/admin/
```
—— 有意设置为特权区域，验证RBAC是否存在认证绕过

undefined

Distributed Execution (Vercel Sandbox)

分布式执行（Vercel Sandbox）

Fan work across microVMs for large monorepos:

bash

undefined

将工作分散到微虚拟机上处理大型单体代码库：

bash

undefined

Process using 10 sandboxes, 4 concurrent per sandbox

使用10个沙箱，每个沙箱并发4个任务进行处理

pnpm deepsec sandbox process
--project-id my-app
--sandboxes 10
--concurrency 4


```bash

pnpm deepsec sandbox process
--project-id my-app
--sandboxes 10
--concurrency 4


```bash

Full distributed pipeline

完整分布式流程

pnpm deepsec sandbox scan --project-id my-app --sandboxes 5 pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4 pnpm deepsec sandbox revalidate --project-id my-app --sandboxes 5


Requires a Vercel account. The local working tree is tarballed and uploaded (`.git` excluded). Supports both OIDC tokens (local) and access tokens (CI).

For CI environments:

```bash
export VERCEL_ACCESS_TOKEN=your_token_here
export VERCEL_TEAM_ID=team_xxx


需要Vercel账户。本地工作树会被打包并上传（排除`.git`目录）。支持OIDC令牌（本地）和访问令牌（CI）。

对于CI环境：

```bash
export VERCEL_ACCESS_TOKEN=your_token_here
export VERCEL_TEAM_ID=team_xxx

Export Formats

导出格式

bash

undefined

bash

undefined

Directory of markdown files (one per finding)

Markdown文件目录（每个检测结果对应一个文件）

pnpm deepsec export --format md-dir --out ./findings

Single JSON file with all findings

包含所有检测结果的单个JSON文件

pnpm deepsec export --format json --out ./findings.json

Per-finding JSON files

按检测结果导出JSON文件

pnpm deepsec export --format json-dir --out ./findings-json

undefined

pnpm deepsec export --format json-dir --out ./findings-json

undefined

Viewing Results

查看结果

bash

undefined

bash

undefined

Summary report for a project

单个项目的汇总报告

pnpm deepsec report --project-id my-app

Cross-project metrics

跨项目统计数据

pnpm deepsec metrics

Current pipeline status

当前流程状态

pnpm deepsec status

undefined

pnpm deepsec status

undefined

Idempotency and Resuming

幂等性与续跑

Commands are idempotent — safe to interrupt and restart:

bash

undefined

命令具有幂等性——中断后重启是安全的：

bash

undefined

If process is interrupted, just re-run — it picks up where it left off

如果处理过程中断，只需重新运行——它会从中断处继续

pnpm deepsec process

Force re-process specific files

强制重新处理特定文件

pnpm deepsec process --force --file src/auth/login.ts

undefined

pnpm deepsec process --force --file src/auth/login.ts

undefined

Plugin Authoring

插件开发

typescript

// .deepsec/plugins/jira-ownership.ts
import { definePlugin } from 'deepsec';

export default definePlugin({
  name: 'jira-ownership',
  hooks: {
    // Called during `enrich` — add owner metadata to findings
    async enrichFinding(finding) {
      const owner = await fetchJiraTeamForPath(finding.file);
      return {
        ...finding,
        metadata: { ...finding.metadata, team: owner },
      };
    },
  },
});

deepsec.config.ts

typescript

import { defineConfig } from 'deepsec';
import jiraOwnership from './plugins/jira-ownership';

export default defineConfig({
  plugins: [jiraOwnership],
  projects: [{ id: 'my-app', root: '../' }],
});

typescript

// .deepsec/plugins/jira-ownership.ts
import { definePlugin } from 'deepsec';

export default definePlugin({
  name: 'jira-ownership',
  hooks: {
    // 在`enrich`阶段调用——为检测结果添加所有者元数据
    async enrichFinding(finding) {
      const owner = await fetchJiraTeamForPath(finding.file);
      return {
        ...finding,
        metadata: { ...finding.metadata, team: owner },
      };
    },
  },
});

在

deepsec.config.ts

中注册：

typescript

import { defineConfig } from 'deepsec';
import jiraOwnership from './plugins/jira-ownership';

export default defineConfig({
  plugins: [jiraOwnership],
  projects: [{ id: 'my-app', root: '../' }],
});

Data Layout

数据布局

Key paths inside

.deepsec/data/<project-id>/

data/<id>/
  SETUP.md          # one-time agent bootstrap instructions
  INFO.md           # project context injected into every scan batch
  scan/             # FileRecord JSON from matcher pass
  findings/         # AI-produced findings (one JSON per finding)
  revalidated/      # findings after revalidation pass
  run-meta.json     # pipeline state, timestamps, model used

.deepsec/data/<project-id>/

内的关键路径：

data/<id>/
  SETUP.md          # 一次性Agent引导说明
  INFO.md           # 注入到每个扫描批次的项目上下文
  scan/             # 匹配器扫描生成的FileRecord JSON
  findings/         # AI生成的检测结果（每个结果对应一个JSON文件）
  revalidated/      # 重新验证后的检测结果
  run-meta.json     # 流程状态、时间戳、使用的模型

Common Patterns

常用模式

Scan a specific directory only

仅扫描特定目录

bash

pnpm deepsec scan --include 'src/api/**' --include 'src/auth/**'

bash

pnpm deepsec scan --include 'src/api/**' --include 'src/auth/**'

Focus on high-severity only during process

处理时仅关注高严重程度

bash

pnpm deepsec process --min-severity high

bash

pnpm deepsec process --min-severity high

Triage first to prioritize expensive revalidation

先分类以优先处理昂贵的重新验证

bash

pnpm deepsec process
pnpm deepsec triage          # classify P0/P1/P2 cheaply
pnpm deepsec revalidate --min-priority P0  # only revalidate critical

bash

pnpm deepsec process
pnpm deepsec triage          # 低成本分类为P0/P1/P2
pnpm deepsec revalidate --min-priority P0  # 仅重新验证关键级结果

Add git blame context to findings

为检测结果添加Git blame上下文

bash

pnpm deepsec enrich          # adds committer info from git log

bash

pnpm deepsec enrich          # 从Git日志添加提交者信息

Troubleshooting

故障排除

Scan finds nothing: Check that matchers cover your file extensions. Add custom matchers for project-specific patterns (e.g., internal auth helpers, custom ORMs).

High false positive rate: Run

revalidate

— it re-checks findings and checks git history. Also improve

INFO.md

with project-specific context so the AI understands your conventions.

AI model refusals: Some models refuse certain security content. See

docs/models.md

for refusal handling and alternative model configuration.

Cost is too high: Use

triage

before

process

to filter candidates. Use

--include

flags to focus on high-risk directories. Switch to a cheaper model for initial passes via

deepsec.config.ts

Interrupted scan: Just re-run the same command. All commands are idempotent and resume from where they stopped.

Prompt injection concern: Run on Vercel Sandbox — API keys are injected outside the sandbox and cannot be exfiltrated. Worker sandboxes have limited network egress.

扫描无结果： 检查匹配器是否覆盖你的文件扩展名。为项目特定模式添加自定义匹配器（例如内部认证助手、自定义ORM）。

高误报率： 运行

revalidate

——它会重新检查检测结果并查看Git历史记录。同时完善

INFO.md

中的项目特定上下文，让AI了解你的约定。

AI模型拒绝处理： 部分模型会拒绝处理某些安全内容。查看

docs/models.md

了解拒绝处理方法和替代模型配置。

成本过高： 在

process

前使用

triage

过滤候选目标。使用

--include

标志聚焦高风险目录。通过

deepsec.config.ts

在初始扫描时切换到更便宜的模型。

扫描中断： 只需重新运行相同命令。所有命令都具有幂等性，会从中断处继续。

提示注入风险： 在Vercel Sandbox上运行——API密钥在沙箱外部注入，无法被窃取。工作沙箱的网络出口受限。

Security Model

安全模型

Treat

deepsec

like a coding agent with full shell access. It's designed for trusted inputs (your source code). For untrusted inputs (vendored code, external deps), use Vercel Sandbox to limit exposure — API keys are injected outside sandbox scope and network egress is restricted to coding agent hosts.

将

deepsec

视为具有完整Shell访问权限的编码Agent。它设计用于可信输入（你的源代码）。对于不可信输入（第三方代码、外部依赖），使用Vercel Sandbox限制暴露——API密钥在沙箱范围外注入，网络出口仅允许访问编码Agent主机。

Cost Expectations

成本预期

Uses best models at maximum thinking levels
Large codebases can cost thousands to tens of thousands of dollars
Use
```
triage
```
(cheap model) →
```
revalidate
```
(targeted) to control costs
Distributed sandbox runs are billed per compute time on Vercel

使用最高性能模型并以最高思考级别运行
大型代码库的扫描成本可能达到数千至数万美元
使用
```
triage
```
（低成本模型）→
```
revalidate
```
（针对性验证）来控制成本
分布式沙箱运行会根据Vercel的计算时间计费

Key Files and Docs

关键文件与文档

File	Purpose
`docs/getting-started.md`	First-scan walkthrough
`docs/writing-matchers.md`	Prompt your agent to grow matchers
`docs/configuration.md`	Full `deepsec.config.ts` reference
`docs/models.md`	Model selection, defaults, refusals
`docs/vercel-setup.md`	AI Gateway + Sandbox keys
`docs/architecture.md`	Pipeline internals
`docs/faq.md`	Cost, FP rate, sandbox mode
`samples/webapp/`	Copy-paste starting points

文件	用途
`docs/getting-started.md`	首次扫描指南
`docs/writing-matchers.md`	提示Agent扩展匹配器的文档
`docs/configuration.md`	`deepsec.config.ts` 完整参考
`docs/models.md`	模型选择、默认设置、拒绝处理
`docs/vercel-setup.md`	AI Gateway + Sandbox密钥设置
`docs/architecture.md`	流程内部架构
`docs/faq.md`	成本、误报率、沙箱模式相关问题
`samples/webapp/`	可复制粘贴的起始模板