不想看长文档？点这里 →
docs/QUICKSTART.zh-CN.md（中文版）下载 Release 里的
deepsec-tui-windows.exe→ 双击 → 输入/shield scan 你的项目→ 2 秒看到漏洞。 不会用？仓库自带故意写满漏洞的示例文件demo/unsafe-ai-sample.ts，扫它就能看到效果。
DeepSec TUI 终端工作台
deepsec-tui.mp4
— Shield 扫描、Spear 渗透、实时动画
DeepSec 是由 VibeGuard 进化而来的 AI 安全平台，将 Shield（AI 代码安全审计）与 Spear（授权渗透测试引擎）统一到一套 CLI、一个 TUI 终端工作台和一组 IDE 插件中。
┌──────────────────────────────────────────────────────────┐
│ DeepSec Platform │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Shield │ │ Spear │ │ TUI │ │ MCP │ │
│ │ Code │ │ Pentest │ │ Terminal │ │ Server │ │
│ │ Audit │ │ Engine │ │ Workbench│ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴──────────────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ Unified Config │ │
│ │ ~/.deepsec/ │ │
│ │ config.yaml │ │
│ └───────────────────────┘ │
└──────────────────────────────────────────────────────────┘
│ │
┌─────┴─────┐ ┌─────┴──────┐
│ VSCode │ │ JetBrains │
│ Plugin │ │ Plugin │
│ (TS/LSP) │ │ (Kotlin) │
└───────────┘ └────────────┘
从实时正则到 LLM 语义分析的三层检测架构：
| 层 | 检测内容 | 速度 | 原理 |
|---|---|---|---|
| L1 | 幻觉包、硬编码密钥、不安全配置、AI 错误模式 | < 50ms | 正则 + 熵分析 + 种子目录 |
| L2 | SQL 注入、XSS、SSRF、路径穿越、命令注入 | < 2s | Tree-sitter WASM AST 分析 |
| L3 | 缺失认证/限流/校验等语义漏洞 | < 5s | LLM（DeepSeek/Claude/OpenAI/Ollama）+ 本地启发式兜底 |
从 VulnClaw 迁移而来的端到端自动化渗透引擎：
- Recon → Explore → Fact → Reflect → Report → PoC 全流程自动化
- 40+ 内置技能包（nmap、dirsearch、subfinder、nuclei、sqlmap、ffuf、httpx、feroxbuster）
- 5 种角色（pentester、redteam、auditor、blueteam、ctf_player）
- 签名授权范围（Signed Scope），限时 + 审计日志
- 攻击链可视化，多格式报告（Markdown / SARIF / JSON / HTML）
基于 Rust + ratatui 构建的安全工作台，交互设计借鉴 DeepSeek-TUI：
- 三面板布局：工作区侧边栏 · 会话记录 · 漏洞检查器
- Plan / Agent / YOLO 模式切换
- 斜杠命令系统 + 命令历史回放
- Side-Git 快照（随时创建/恢复代码状态）
- 会话持久化（Ctrl+S 保存 / Ctrl+R 恢复）
想 3 分钟跑起来？直接看
docs/QUICKSTART.zh-CN.md（中文） 或docs/QUICKSTART.md（English）——含"下载即用"的最快路径。
# Python 核心 + CLI
pip install -e .
# Rust TUI（可选）
cargo build --manifest-path tui/Cargo.toml
# IDE 插件
# VSCode: 在项目根目录按 F5 启动 Extension Development Host
# JetBrains: cd jetbrains && ./gradlew buildPlugin新手免编译路径：直接去 Releases 下载
deepsec-tui-windows.exe/deepsec-tui-linux/deepsec-0.2.0-py3-none-any.whl，不用装任何编译环境。
# 扫描项目（L1 + L2，离线）
deepsec shield scan ./src
# 开启 L3 语义分析（需要 LLM API Key）
DEEPSEEK_API_KEY=... deepsec shield scan ./src --layer l3
# 输出 SARIF 报告
deepsec shield scan . --format sarif --output deepsec.sarif
# 流式输出（供 TUI 消费）
deepsec shield scan . --stream
# Agent 配置审计
deepsec shield agent-audit ./agent-config
# 供应链安全检查
deepsec shield supply-chain check .# 1. （可选）维护授权白名单 — 推荐通过 TUI /scope 命令
# 或手动编辑 ~/.deepsec/targets/scope.json 的 targets 字段
# 如需强签名校验：export DEEPSEC_SCOPE_SIGNING_KEY=... && deepsec scope sign ./scope.json
# 2. 运行渗透测试（目标必须在白名单内）
deepsec spear run https://authorized-target.example --authorized ./scope.json
# 3. 仅侦察阶段
deepsec spear recon https://authorized-target.example --authorized ./scope.json
# 4. 列出角色和工具
deepsec spear roles
deepsec spear tools --role pentester# 启动终端工作台
deepsec tui
# 或直接运行 Rust 原生二进制
./tui/target/debug/deepsec-tui-native内置 TUI 斜杠命令：
| 命令 | 说明 |
|---|---|
/shield scan |
运行 Shield 扫描 |
/spear run |
运行 Spear 渗透（需白名单授权） |
/spear recon |
运行侦察阶段 |
/scope add <target> |
将目标加入授权白名单 |
/scope remove <target> |
从白名单移除目标 |
/scope list |
查看当前白名单 |
/report |
生成报告 |
/plan |
切换到 Plan 模式 |
/agent |
切换到 Agent 模式 |
/yolo |
切换到 YOLO 模式（全自动） |
/clear |
清空会话 |
/help |
帮助 |
DeepSec TUI 内置授权白名单管理 — 无需手动编辑 scope.json 或处理 HMAC 签名密钥。
1. 启动 TUI
deepsec tui2. 将目标加入白名单
在 TUI 命令行（底部 > 提示符）输入：
/scope add https://your-authorized-domain.com
- 目标会被规范化（scheme+host 转小写、去尾部
/）并去重，与后端授权匹配规则一致。 - 未指定
--file时，默认取最近一次/spear run --authorized <file>解析出的绝对路径；若尚未运行过 spear，则回退到~/.deepsec/targets/scope.json。 - 查看当前白名单：
/scope list - 移除目标：
/scope remove https://your-authorized-domain.com
3. 启动渗透测试
/spear run https://your-authorized-domain.com --authorized ~/.deepsec/targets/scope.json
然后：
- 按
Tab在 Plan / Agent / YOLO 执行模式间切换（YOLO 为全自动，无需逐步确认）。 - Plan 模式只读，无法直接武装 Spear — 需先切到 Agent 或 YOLO。
- 按
Y确认授权校验并启动；按Esc取消。 - 运行中按
Ctrl+C可中止当前任务（TUI 保持打开）；空闲时按Ctrl+C退出 TUI。
4. 安全边界
- 白名单之外的目标一律拒绝（
target ... is not present in the scope manifest）。 - 私有/回环/非公网地址仍被阻止，防止打到内网。
- 白名单只接受你拥有或已书面授权的资产；任何不在
targets里的第三方生产域名都无法被攻击。
# 创建快照
deepsec snapshot create . --mode shield --description "before-refactor"
# 列出快照
deepsec snapshot list .
# 恢复快照
deepsec restore <snapshot-id>| 实时诊断 | 悬停查看详情 |
 |
 |
| Quick Fix 菜单 | Problems 面板 |
 |
 |
DeepSec 是一个多语言项目：
| 组件 | 语言 | 文件数 | 代码量 | 用途 |
|---|---|---|---|---|
| Python 核心 | Python 3.10+ | 153 | 43,500+ | Shield 扫描器、Spear 引擎、CLI、MCP Server、角色/工具系统 |
| IDE 插件 | TypeScript | 53 | 21,000+ | VSCode 扩展、LSP Server、Tree-sitter SAST |
| TUI | Rust | 22 | 2,470+ | ratatui 终端工作台 |
| Rust LSP | Rust | 5 | 7,800+ | 原生 L1 LSP 预览 |
deepsec/ # Python 核心
├── cli/ # Typer CLI 入口（shield/spear/snapshot/config/scope）
├── config/ # 统一 YAML 配置 + Pydantic schema
├── core/ # 配置适配器、LLM 客户端、授权、快照、角色
├── shield/ # L1/L2/L3 扫描器、供应链安全、去重、忽略规则
├── spear/ # 渗透引擎（agent/intel/skills/report/warstories）
├── roles/ # YAML 角色定义（pentester/redteam/auditor/blueteam/ctf_player）
├── tools/ # YAML 工具目录（nmap/dirsearch/nuclei/sqlmap/...）
├── mcp/ # MCP Server（lifecycle/registry/router/diagnostics）
├── report/ # 报告生成 + 攻击链可视化
├── kb/ # 知识库
├── plugins/ # 插件系统
└── traffic/ # 流量回放与归一化
src/ # TypeScript IDE 插件
├── extension.ts # VSCode 扩展入口
├── lspServer.ts # LSP Server（Node）
├── scanner.ts # L1/L2 扫描器
├── deepsecBridge.ts # Python 核心桥接
└── ...
tui/ # Rust TUI 终端工作台
├── src/
│ ├── app.rs # App 状态 + 命令分发
│ ├── events.rs # 键盘事件处理
│ ├── ui/ # 三面板布局（transcript/findings/layout）
│ ├── views/ # Skills Manager 侧边栏
│ ├── theme.rs # CodeWhale 深色主题
│ ├── sessions.rs # 会话持久化
│ └── skills/ # Skill 树目录
└── Cargo.toml
rust-lsp/ # Rust 原生 L1 LSP 预览
jetbrains/ # JetBrains 插件（Kotlin）
docs/ # 使用指南
DeepSec 使用统一的 YAML 配置文件 ~/.deepsec/config.yaml：
deepsec config init # 初始化配置
deepsec config show # 查看配置
deepsec config set llm.provider deepseek # 设置配置项DeepSec 支持 13+ 家 LLM 提供商：
| 提供商 | Base URL | 默认模型 |
|---|---|---|
| DeepSeek | api.deepseek.com/v1 |
deepseek-chat |
| Anthropic Claude | api.anthropic.com/v1 |
claude-sonnet-5 |
| OpenAI | api.openai.com/v1 |
gpt-4o |
| 智谱 GLM | open.bigmodel.cn/api/paas/v4 |
glm-4.7 |
| Kimi (Moonshot) | api.moonshot.cn/v1 |
kimi-k2.6 |
| 通义千问 | dashscope.aliyuncs.com/compatible-mode/v1 |
qwen3-max |
| SiliconFlow | api.siliconflow.cn/v1 |
deepseek-ai/DeepSeek-V4-Flash |
| 豆包 (ByteDance) | ark.cn-beijing.volces.com/api/v3 |
Doubao-Seed-2.0-Pro |
| 百川 | api.baichuan-ai.com/v1 |
Baichuan4-Turbo |
| MiniMax | api.minimaxi.com/v1 |
MiniMax-M3 |
| 阶跃星辰 | api.stepfun.com/v1 |
step-3.5-flash |
| 商汤 | api.sensenova.cn/v1 |
SenseNova-6.7-Flash-Lite |
| 零一万物 | api.lingyiwanwu.com/v1 |
yi-lightning |
| 自定义 | 自定义 | 自定义 |
# 设置 API Key
deepsec config set llm.provider deepseek
deepsec config set llm.api_key "sk-xxx"
# 或通过环境变量
export DEEPSEC_LLM_API_KEY="sk-xxx"Spear 以授权白名单为核心闸门：只有 scope.json 的 targets 数组中明确列出的目标才能被攻击，其余一律拒绝。
签名已改为可选：早期版本要求用
DEEPSEC_SCOPE_SIGNING_KEY对scope.json做 HMAC-SHA256 签名。现已放宽 —signature/signer字段保留但忽略，授权只校验targets白名单（可选时间窗口仍会校验）。也就是说，你不再需要export密钥、重新签名或重启 TUI，直接用 TUI 的/scope命令管理白名单即可（见上文"TUI 实操"）。
白名单文件格式（~/.deepsec/targets/scope.json）：
{
"version": 1,
"targets": ["https://your-authorized-domain.com"],
"valid_from": "2026-07-26T00:00:00Z",
"valid_until": "2026-08-25T00:00:00Z",
"prohibited_cidrs": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "127.0.0.0/8", "169.254.0.0/16"],
"signer": "UncleC",
"signature": "0000000000000000000000000000000000000000000000000000000000000000",
"signature_algorithm": "hmac-sha256"
}targets：允许渗透的目标列表。支持https://domain、domain、*.domain通配符和裸 IP/CIDR。匹配时自动去尾部/、转小写、对齐 scheme。prohibited_cidrs：默认阻止私有/回环/链路本地地址，防止打到内网。- 如需保留强校验，可手动执行
deepsec scope sign ./scope.json（需要DEEPSEC_SCOPE_SIGNING_KEY）；不签名不影响使用。
# （可选）手动签名
export DEEPSEC_SCOPE_SIGNING_KEY="your-secret"
deepsec scope sign ./scope.json
# 校验 scope 结构 / 时间窗口 / 可选签名
deepsec scope verify ./scope.jsonVSCode 扩展提供实时诊断、Quick Fix 和 Findings 侧边栏：
| 设置项 | 默认值 | 说明 |
|---|---|---|
deepsec.enabled |
true |
启用/禁用扫描 |
deepsec.scanOnChange |
true |
编辑时扫描 |
deepsec.scanOnSave |
true |
保存时扫描 |
deepsec.enableL2 |
true |
启用 L2 SAST |
deepsec.l2DebounceMs |
500 |
L2 防抖 |
deepsec.enableL3 |
false |
启用 L3 语义分析 |
deepsec.l3DebounceMs |
2000 |
L3 防抖 |
deepsec.llmProvider |
— | LLM 提供商 |
deepsec.deepsecPythonPath |
— | DeepSec Python 路径 |
deepsec.dedupWithExistingTools |
true |
与 SonarQube/Snyk/Semgrep/CodeQL 去重 |
Quick Fixes：
- 幻觉包 → 推荐替代包名
- 硬编码密钥 → 改为环境变量读取
yaml.load()→yaml.safe_load()- SQL f-string → 参数化查询
innerHTML→textContent- Debug/CORS/host 检查 → 机械修复
JetBrains 插件通过 LSP 协议复用 DeepSec 诊断能力，支持 JetBrains 2025.2+：
cd jetbrains
./gradlew buildPlugin
# 输出: build/distributions/deepsec-*.zip独立的 Rust 原生 L1 LSP Server，用于更低延迟的基础检测：
cargo run --manifest-path rust-lsp/Cargo.toml -- --stdio# Shield 命令
deepsec shield scan <path> [--layer all|l1|l2|l3] [--format text|json|sarif|markdown|html] [--stream]
deepsec shield agent-audit <path>
deepsec shield watch <path> [--interval 1.0]
deepsec shield supply-chain check <path> [--private-package pkg]
# Spear 命令
deepsec spear run <target> --authorized <scope.json> [--scope full|web|api|mobile] [--mode quick|standard|deep]
deepsec spear recon <target> --authorized <scope.json>
deepsec spear roles
deepsec spear tools [--role pentester]
# 快照命令
deepsec snapshot create <path> [--mode shield|spear] [--description "..."]
deepsec snapshot list <path>
# 配置命令
deepsec config init
deepsec config set <key> <value>
deepsec config show
# Scope 命令
deepsec scope sign <scope.json> # （可选）签名 scope，需要 DEEPSEC_SCOPE_SIGNING_KEY
deepsec scope verify <scope.json> # 校验 scope 结构 / 时间窗口 / 可选签名
# 其他
deepsec tui # 启动 TUI
deepsec chat # 交互式 Spear 工作台
deepsec tools # 列出所有工具
deepsec report <result.json> [--format markdown|json|sarif|html] [--chain]
deepsec restore <snapshot-id>| 角色 | 模式 | 说明 |
|---|---|---|
pentester |
standard | 标准渗透测试 |
redteam |
deep | 红队深度攻击 |
auditor |
standard | 安全审计（只读） |
blueteam |
quick | 蓝队快速验证 |
ctf_player |
quick | CTF 竞赛模式 |
| 工具 | 分类 | 安装检查 |
|---|---|---|
| nmap | 网络 | nmap --version |
| dirsearch | Web | dirsearch --version |
| subfinder | 侦察 | subfinder -version |
| httpx | Web | httpx -version |
| feroxbuster | Web | feroxbuster --version |
| ffuf | Web | ffuf -V |
| nuclei | Web | nuclei -version |
| sqlmap | Web | sqlmap --version |
可通过 deepsec/tools/*.yaml 添加自定义工具，通过 deepsec/roles/*.yaml 添加自定义角色。
DeepSec 内置 MCP（Model Context Protocol）Server，可被 Claude Desktop、Cursor 等 MCP 客户端调用：
from deepsec.mcp import MCPServer
server = MCPServer()
server.run()支持的工具包括 Shield 扫描、Spear 侦察、报告生成等。
# Python 测试
python -m pytest tests/deepsec/ -v
# TypeScript 测试
npm test
# Rust TUI 测试
cargo test --manifest-path tui/Cargo.toml
# Rust LSP 测试
cargo test --manifest-path rust-lsp/Cargo.toml当前状态：23 个 Python 测试通过 · 41 个 Rust TUI 测试通过 · TypeScript 干净
docker build -t deepsec:local .
docker run --rm -v "$PWD:/workspace" deepsec:local shield scan /workspacegit clone https://github.com/Unclecheng-li/DeepSec.git
cd DeepSec
# Python 开发环境
pip install -e .[dev]
# Node.js IDE 插件开发
nvm use # Node.js 22 LTS
npm install
npm run build
# Rust TUI 开发
cargo build --manifest-path tui/Cargo.toml- 报 Bug — Open an issue
- 提需求 — Start a discussion
- 提交 PR — Fork、功能分支、Pull Request
- 快速上手（中文） — 3 分钟跑起来
- Quick Start (English) — Get running in 3 minutes
- 架构 — 系统架构细节
- Shield 指南 — 代码审计指南
- Spear 指南 — 渗透测试指南
- Skill 开发 — 技能包开发
- 工具配置 — 工具配置
- DeepSeek 优化 — DeepSeek 模型优化
- 迁移设计 — VibeGuard 到 DeepSec 迁移设计
- TUI 开发文档 — TUI 开发指南
MIT © 2026 DeepSec contributors