---

Quick Start in 3 Minutes

Don't want to read the long doc? Click here → docs/QUICKSTART.zh-CN.md (Chinese version)

Download deepsec-tui-windows.exe from the Release → double-click → type /shield scan 你的项目 → see vulnerabilities in 2 seconds. Not sure how to use it? The repo ships with a deliberately vulnerable sample file demo/unsafe-ai-sample.ts — scan it to see it in action.

---

---

What is DeepSec?

DeepSec is an AI security platform evolved from VibeGuard, unifying Shield (AI code security audit) and Spear (authorized penetration testing engine) into a single CLI, one TUI terminal workbench, and a suite of IDE plugins.

┌──────────────────────────────────────────────────────────┐
│                      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)  │
   └───────────┘                  └────────────┘

Shield — Code Security Audit

Three-layer detection: regex to LLM:

Layer	Detects	Speed	Principle
L1	Hallucinated packages, hardcoded secrets, insecure configs, AI error patterns	< 50ms	Regex + entropy analysis + seed catalog
L2	SQL injection, XSS, SSRF, path traversal, command injection	< 2s	Tree-sitter WASM AST analysis
L3	Semantic vulnerabilities like missing auth/rate-limiting/validation	< 5s	LLM (DeepSeek/Claude/OpenAI/Ollama) + local heuristic fallback

Spear — Authorized Penetration Testing

End-to-end automated pentest engine migrated from VulnClaw:

• Recon → Explore → Fact → Reflect → Report → PoC fully automated pipeline
• 40+ built-in skill packs (nmap, dirsearch, subfinder, nuclei, sqlmap, ffuf, httpx, feroxbuster)
• 5 roles (pentester, redteam, auditor, blueteam, ctf_player)
• Signed Scope authorization, time-boxed + audit logs
• Attack chain visualization, multi-format reports (Markdown / SARIF / JSON / HTML)

TUI — Terminal Workbench

Security workbench built on Rust + ratatui, with interaction design inspired by DeepSeek-TUI:

• Three-panel layout: workspace sidebar · session log · vulnerability inspector
• Plan / Agent / YOLO mode switching
• Slash command system + command history replay
• Side-Git snapshots (create/restore code state anytime)
• Session persistence (Ctrl+S save / Ctrl+R restore)

---

Quick Start

Want to be up and running in 3 minutes? See docs/QUICKSTART.zh-CN.md (Chinese) or docs/QUICKSTART.md (English) — includes the fastest "download-and-go" path.

Installation

# 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

No-compile path for beginners: just download deepsec-tui-windows.exe / deepsec-tui-linux / deepsec-0.2.0-py3-none-any.whl from Releases — no build environment needed.

Shield Scan

# 扫描项目（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 .

Spear Penetration Testing

# 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

TUI Terminal Workbench

# 启动终端工作台
deepsec tui

# 或直接运行 Rust 原生二进制
./tui/target/debug/deepsec-tui-native

Built-in TUI slash commands:

Command	Description
/shield scan	Run a Shield scan
/spear run	Run Spear pentest (requires whitelist authorization)
/spear recon	Run the recon phase
/scope add <target>	Add target to the authorized whitelist
/scope remove <target>	Remove target from the whitelist
/scope list	View the current whitelist
/report	Generate a report
/plan	Switch to Plan mode
/agent	Switch to Agent mode
/yolo	Switch to YOLO mode (fully automatic)
/clear	Clear the session
/help	Help

TUI Walkthrough: Add Whitelist Entry and Launch a Pentest

DeepSec TUI has built-in authorized whitelist management — no need to manually edit scope.json or deal with HMAC signing keys.

1. Launch the TUI

deepsec tui

2. Add a target to the whitelist

In the TUI command line (the > prompt at the bottom), type:

/scope add https://your-authorized-domain.com

• Targets are normalized (scheme+host lowercased, trailing / stripped) and deduplicated, matching the backend authorization rules.
• If --file is not specified, it defaults to the absolute path resolved by the most recent /spear run --authorized <file>; if Spear has not been run yet, it falls back to ~/.deepsec/targets/scope.json.
• View the current whitelist: /scope list
• Remove a target: /scope remove https://your-authorized-domain.com

3. Launch the penetration test

/spear run https://your-authorized-domain.com --authorized ~/.deepsec/targets/scope.json

Then:

• Press Tab to cycle between Plan / Agent / YOLO execution modes (YOLO is fully automatic, no step-by-step confirmation needed).
• Plan mode is read-only and cannot arm Spear directly — switch to Agent or YOLO first.
• Press Y to confirm the authorization check and start; press Esc to cancel.
• While running, press Ctrl+C to abort the current task (TUI stays open); when idle, press Ctrl+C to exit the TUI.

4. Safety boundaries

• Targets outside the whitelist are always rejected (target ... is not present in the scope manifest).
• Private/loopback/non-public addresses are still blocked, preventing attacks against internal networks.
• The whitelist only accepts assets you own or have written authorization for; any third-party production domain not in targets cannot be attacked.

Side-Git Snapshots

# 创建快照
deepsec snapshot create . --mode shield --description "before-refactor"

# 列出快照
deepsec snapshot list .

# 恢复快照
deepsec restore <snapshot-id>

---

Screenshots

---

Architecture

DeepSec is a polyglot project:

Component	Language	Files	LOC	Purpose
Python core	Python 3.10+	153	43,500+	Shield scanner, Spear engine, CLI, MCP Server, role/tool system
IDE plugins	TypeScript	53	21,000+	VSCode extension, LSP Server, Tree-sitter SAST
TUI	Rust	22	2,470+	ratatui terminal workbench
Rust LSP	Rust	5	7,800+	Native L1 LSP preview

Project Structure

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/                    # 使用指南

---

Config

DeepSec uses a unified YAML config file ~/.deepsec/config.yaml:

deepsec config init      # 初始化配置
deepsec config show      # 查看配置
deepsec config set llm.provider deepseek  # 设置配置项

LLM Configuration

DeepSec supports 13+ LLM providers:

Provider	Base URL	Default Model
DeepSeek	api.deepseek.com/v1	deepseek-chat
Anthropic Claude	api.anthropic.com/v1	claude-sonnet-5
OpenAI	api.openai.com/v1	gpt-4o
Zhipu GLM	open.bigmodel.cn/api/paas/v4	glm-4.7
Kimi (Moonshot)	api.moonshot.cn/v1	kimi-k2.6
Tongyi Qwen	dashscope.aliyuncs.com/compatible-mode/v1	qwen3-max
SiliconFlow	api.siliconflow.cn/v1	deepseek-ai/DeepSeek-V4-Flash
Doubao (ByteDance)	ark.cn-beijing.volces.com/api/v3	Doubao-Seed-2.0-Pro
Baichuan	api.baichuan-ai.com/v1	Baichuan4-Turbo
MiniMax	api.minimaxi.com/v1	MiniMax-M3
StepFun	api.stepfun.com/v1	step-3.5-flash
SenseTime	api.sensenova.cn/v1	SenseNova-6.7-Flash-Lite
01.AI	api.lingyiwanwu.com/v1	yi-lightning
Custom	Custom	Custom

# 设置 API Key
deepsec config set llm.provider deepseek
deepsec config set llm.api_key "sk-xxx"

# 或通过环境变量
export DEEPSEC_LLM_API_KEY="sk-xxx"

Spear Authorization

Spear uses an authorized whitelist as its core gate: only targets explicitly listed in the targets array of scope.json can be attacked; everything else is rejected.

Signing is now optional: earlier versions required an HMAC-SHA256 signature of scope.json using DEEPSEC_SCOPE_SIGNING_KEY. This has been relaxed — the signature / signer fields are retained but ignored; authorization only checks the targets whitelist (an optional time window, if set, is still validated). In other words, you no longer need to export the key, re-sign, or restart the TUI — just manage the whitelist directly with the TUI's /scope commands (see "TUI Walkthrough" above).

Whitelist file format (~/.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: list of targets allowed for penetration testing. Supports https://domain, domain, *.domain wildcards, and bare IP/CIDR. Matching automatically strips trailing /, lowercases, and aligns the scheme.
• prohibited_cidrs: blocks private/loopback/link-local addresses by default, preventing attacks against internal networks.
• If you need to keep strict validation, you can manually run deepsec scope sign ./scope.json (requires DEEPSEC_SCOPE_SIGNING_KEY); skipping the signature does not affect usage.

# （可选）手动签名
export DEEPSEC_SCOPE_SIGNING_KEY="your-secret"
deepsec scope sign ./scope.json

# 校验 scope 结构 / 时间窗口 / 可选签名
deepsec scope verify ./scope.json

---

IDE Integration

VSCode

The VSCode extension provides real-time diagnostics, Quick Fixes, and a Findings sidebar:

Setting	Default	Description
deepsec.enabled	true	Enable/disable scanning
deepsec.scanOnChange	true	Scan on edit
deepsec.scanOnSave	true	Scan on save
deepsec.enableL2	true	Enable L2 SAST
deepsec.l2DebounceMs	500	L2 debounce
deepsec.enableL3	false	Enable L3 semantic analysis
deepsec.l3DebounceMs	2000	L3 debounce
deepsec.llmProvider	—	LLM provider
deepsec.deepsecPythonPath	—	DeepSec Python path
deepsec.dedupWithExistingTools	true	Deduplicate with SonarQube/Snyk/Semgrep/CodeQL

Quick Fixes:

• Hallucinated package → suggest alternative package name
• Hardcoded secret → switch to environment variable lookup
• yaml.load() → yaml.safe_load()
• SQL f-string → parameterized query
• innerHTML → textContent
• Debug/CORS/host check → mechanical fix

JetBrains

The JetBrains plugin reuses DeepSec diagnostics via the LSP protocol, supporting JetBrains 2025.2+:

cd jetbrains
./gradlew buildPlugin
# 输出: build/distributions/deepsec-*.zip

Rust LSP Preview

A standalone Rust-native L1 LSP Server for lower-latency basic detection:

cargo run --manifest-path rust-lsp/Cargo.toml -- --stdio

---

CLI Reference

# 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>

---

Roles & Tools

Built-in Roles

Role	Mode	Description
pentester	standard	Standard penetration testing
redteam	deep	Red team deep attack
auditor	standard	Security audit (read-only)
blueteam	quick	Blue team quick validation
ctf_player	quick	CTF competition mode

Built-in Tools

Tool	Category	Install Check
nmap	Network	nmap --version
dirsearch	Web	dirsearch --version
subfinder	Recon	subfinder -version
httpx	Web	httpx -version
feroxbuster	Web	feroxbuster --version
ffuf	Web	ffuf -V
nuclei	Web	nuclei -version
sqlmap	Web	sqlmap --version

Custom tools can be added via deepsec/tools/*.yaml, and custom roles via deepsec/roles/*.yaml.

---

MCP Server

DeepSec ships with a built-in MCP (Model Context Protocol) Server, callable from MCP clients such as Claude Desktop and Cursor:

from deepsec.mcp import MCPServer

server = MCPServer()
server.run()

Supported tools include Shield scanning, Spear recon, report generation, and more.

---

Testing

# 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

Current status: 23 Python tests passing · 41 Rust TUI tests passing · TypeScript clean

---

Docker

docker build -t deepsec:local .
docker run --rm -v "$PWD:/workspace" deepsec:local shield scan /workspace

---

Contributing

git 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

• Report a Bug — Open an issue
• Request a Feature — Start a discussion
• Submit a PR — Fork, feature branch, Pull Request

---

Docs

• Quick Start (Chinese) — up and running in 3 minutes
• Quick Start (English) — get running in 3 minutes
• Architecture — system architecture details
• Shield Guide — code audit guide
• Spear Guide — penetration testing guide
• Skill Development — skill pack development
• Tool Configuration — tool configuration
• DeepSeek Optimization — DeepSeek model optimization
• Migration Design — VibeGuard to DeepSec migration design
• TUI Developer Docs — TUI development guide

---

License

MIT © 2026 DeepSec contributors

---