AI 原生安全渗透测试指挥中心
由 LLM 和 12 款集成安全扫描器驱动的智能侦察自动化平台。
功能 ·
截图 ·
快速开始 ·
架构 ·
技术栈 ·
贡献
## 什么是 SHADOWPULSE？
SHADOWPULSE 将大语言模型的智能与久经沙场的安全工具相结合，打造出一个自主的渗透测试助手。只需将其指向一个目标，它就能枚举子域名、扫描端口、探测 Web 服务并发现漏洞——这一切既可以通过 AI 驱动的聊天界面完成，也可以通过确定性的侦察 pipeline 来实现。
**两种运行模式：**
| | 聊天模式 | 侦察模式 |
|---|---|---|
| **工作原理** | 会话式 AI 代理通过工具调用编排扫描 | 具有持续监控的确定性多阶段 pipeline |
| **最适用于** | 探索性测试、临时查询、针对性深入分析 | 系统化的攻击面映射、计划性监控 |
| **输出** | 通过 WebSocket 流式传输的实时发现 | 具有变更检测的结构化清单 |
## 功能
**AI 驱动的侦察**
- 通过 LiteLLM 支持，使用 Claude 或 GPT-4 驱动的会话式聊天界面
- LLM 通过工具调用循环自主编排 12 款扫描器
- 通过 WebSocket 提供流式响应和实时扫描更新
**确定性侦察 Pipeline**
- 多阶段 pipeline：Subfinder → DNS → Nmap → httpx → Nuclei
- 可配置的扫描参数（最大主机数、目标、超时时间）
- 运行取消和进度跟踪
- 选项卡式仪表板：概览、资产浏览器、服务浏览器和图表视图
**持续监控与变更检测**
- 跨多次侦察运行跟踪资产
- 检测新资产、新服务、确认的下线状态以及未解决的变更
- 验证作业用于确认资产是否真正离线
**资产清单 (ReconGraph)**
- 发现的子域名、IP、URL 和主机，并附带首次/最后一次看到的时间戳
- 服务枚举，跟踪端口、协议、产品和版本
- 资产之间的关系映射（DNS 解析、重定向）
- 可过滤的资产和服务浏览器，支持搜索、类型/状态过滤以及可展开的详情行
- 单次运行的变更查看器：新发现、待验证、确认下线、未解决项目
**作业队列与调度**
- 基于数据库的作业队列 — 无需 Redis
- 计划性的定期扫描，具有可配置的时间间隔以及启用/禁用切换
- 调度管理：通过 UI 和 API 创建、更新和删除计划任务
- 使用 PostgreSQL `SKIP LOCKED` 实现并发 worker 执行
**安全加固**
- 作用域强制校验：根据允许的域名、CIDR 和 URL 前缀验证每个扫描目标
- 并发限制：对同时进行的作业设置全局和单目标上限（可通过环境变量或单目标作用域进行配置）
- 保留策略：自动清理旧的原始扫描输出和已完成的运行记录
- 审计跟踪：`run_events` 表记录 pipeline 启动、扫描执行、作业生命周期和用户操作
- 会话持久化：聊天会话通过 localStorage 在页面导航和浏览器刷新后依然存在
**12 款集成的安全扫描器**
| 类别 | 工具 |
|---|---|
| 子域名枚举 | Subfinder, dnsx |
| 端口扫描 | Nmap |
| Web 探测 | httpx, Katana (爬虫), ffuf (模糊测试工具) |
| 漏洞扫描 | Nuclei, Nikto, testssl.sh |
| 自定义扫描器 | API 安全, OWASP Top 10 |
## 截图
指挥中心 — 聊天模式
侦察模式 — 目标仪表板
发现面板
## 快速开始
### 前置条件
- [Docker](https://docs.docker.com/get-docker/) & Docker Compose
- 来自 [Anthropic](https://console.anthropic.com/) 或 [OpenAI](https://platform.openai.com/) 的 API 密钥
### 一条命令启动
```
# 克隆仓库
git clone https://github.com/your-org/shadowpulse.git
cd shadowpulse
# 配置环境
cp .env.example .env
# 编辑 .env 并添加你的 API key(s)
# 启动所有服务
make docker-up
```
就这样。打开 [http://localhost:3000](http://localhost:3000) 即可开始扫描。
```
SHADOWPULSE is running:
Frontend: http://localhost:3000
Backend: http://localhost:8000
API Docs: http://localhost:8000/docs
Logs: make docker-logs
Stop: make docker-down
```
### 本地开发
```
# 安装依赖
make install
# 启动数据库
make db-up
# 运行 backend + frontend（独立终端，或同时运行）
make dev
```
环境变量参考
| 变量 | 描述 | 默认值 |
|---|---|---|
| `LLM_MODEL` | LLM 模型标识符 | `claude-sonnet-4-5-20250929` |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | — |
| `OPENAI_API_KEY` | OpenAI API 密钥 | — |
| `BACKEND_HOST` | 后端绑定地址 | `0.0.0.0` |
| `BACKEND_PORT` | 后端端口 | `8000` |
| `NEXT_PUBLIC_API_URL` | 前端 → 后端 URL | `http://localhost:8000` |
| `NEXT_PUBLIC_WS_URL` | 前端 → WebSocket URL | `ws://localhost:8000` |
| `TOOLS_CONTAINER` | Docker 工具容器名称 | `shadowpulse-tools` |
| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql+asyncpg://...` |
| `MAX_CONCURRENT_JOBS_GLOBAL` | 最大并发作业数（所有目标） | `5` |
| `MAX_CONCURRENT_JOBS_PER_TARGET` | 单个目标的最大并发作业数 | `2` |
| `RETENTION_RAW_OUTPUT_DAYS` | 保留原始扫描输出的天数 | `30` |
| `RETENTION_COMPLETED_RUNS_DAYS` | 保留已完成运行的天数 | `90` |
## 架构
```
┌─────────────────────────────────────────────────────┐
│ Frontend (Next.js) │
│ Chat UI · Recon Dashboard · Graph │
└──────────────┬──────────────────┬───────────────────┘
│ REST/HTTP │ WebSocket
▼ ▼
┌─────────────────────────────────────────────────────┐
│ Backend (FastAPI) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ AI Agent │ │ Recon │ │ Job Queue │ │
│ │ Orchestrator│ │ Pipeline │ │ & Scheduler│ │
│ └──────┬──────┘ └──────┬───────┘ └─────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┘ │ │
│ ▼ │ │
│ ┌──────────────────────────┐ │ │
│ │ Scanner Interface │◄─────────────┘ │
│ │ (12 security scanners) │ │
│ └────────────┬─────────────┘ │
└───────────────┼─────────────────────────────────────┘
│ Docker exec
▼
┌─────────────────────────────────────────────────────┐
│ Tools Container (Alpine) │
│ subfinder · nmap · httpx · nuclei · nikto · ffuf │
│ katana · dnsx · testssl · dig · nslookup │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ PostgreSQL 16 │
│ targets · assets · services · edges · findings │
│ runs · scans · jobs · schedules · sessions │
│ run_events │
└─────────────────────────────────────────────────────┘
```
### 数据流
1. **聊天模式**：用户消息 → LLM 决定调用哪个扫描器 → 扫描器在工具容器中运行 → 结果被解析为发现项 → 通过流式传输返回给 UI
2. **侦察模式**：触发 pipeline → 各阶段按顺序执行（subfinder → DNS → nmap → httpx → nuclei） → 资产/服务被录入清单 → 针对前几次运行检测变更
## 技术栈
| 层级 | 技术 |
|---|---|
| **前端** | Next.js 14, React 18, TypeScript, Tailwind CSS, Cytoscape.js |
| **后端** | FastAPI, SQLAlchemy 2.0 (异步), Alembic, LiteLLM, Pydantic v2 |
| **数据库** | 通过 asyncpg 连接 PostgreSQL 16 |
| **实时通信** | 使用 WebSockets 进行实时扫描更新和聊天流式传输 |
| **AI/LLM** | 通过 LiteLLM 抽象层使用 Claude (Anthropic) 或 GPT-4 (OpenAI) |
| **安全工具** | Subfinder, Nmap, httpx, Nuclei, Nikto, Katana, ffuf, dnsx, testssl.sh |
| **基础设施** | Docker Compose, 多架构 (ARM64 + x86_64) |
## 项目结构
```
shadowpulse/
├── backend/
│ ├── main.py # FastAPI application entry point
│ ├── config.py # Environment & settings
│ ├── database.py # SQLAlchemy models
│ ├── agent/ # LLM orchestrator, tools, prompts
│ ├── scanners/ # 12 scanner implementations
│ ├── pipeline/ # Deterministic recon pipeline
│ ├── recongraph/ # Asset inventory & normalization
│ ├── routers/ # API endpoints
│ ├── jobqueue/ # DB-backed job queue
│ ├── scheduler/ # Recurring scan scheduler
│ ├── worker/ # Job execution worker
│ ├── websocket/ # WebSocket connection manager
│ └── alembic/ # Database migrations
├── frontend/
│ ├── app/ # Next.js pages & routing
│ ├── components/ # React components (chat, findings, recon)
│ ├── lib/ # API client & TypeScript types
│ └── hooks/ # Custom React hooks
├── docker/ # Dockerfiles (backend, frontend, tools)
├── docker-compose.yml # Multi-service orchestration
├── Makefile # Development commands
└── .env.example # Environment template
```
## API 概览
SHADOWPULSE 提供了一个 REST API，并在 `/docs` 路径下提供了交互式的 Swagger 文档。
端点
| 方法 | 端点 | 描述 |
|---|---|---|
| `POST` | `/api/targets` | 创建新目标 |
| `GET` | `/api/targets` | 列出所有目标 |
| `GET` | `/api/targets/{id}` | 获取目标详情 |
| `POST` | `/api/targets/{id}/pipeline` | 启动侦察 pipeline 运行 |
| `GET` | `/api/targets/{id}/assets` | 列出发现的资产 |
| `GET` | `/api/targets/{id}/services` | 列出发现的服务 |
| `GET` | `/api/targets/{id}/edges` | 列出资产关系 |
| `GET` | `/api/targets/{id}/changes` | 获取变更检测结果 |
| `GET` | `/api/targets/{id}/events` | 列出审计跟踪事件 |
| `POST` | `/api/targets/{id}/schedules` | 创建定期扫描计划 |
| `PATCH` | `/api/schedules/{id}` | 更新计划任务 |
| `DELETE` | `/api/schedules/{id}` | 删除计划任务 |
| `POST` | `/api/sessions` | 创建聊天会话 |
| `POST` | `/api/sessions/{id}/chat` | 发送聊天消息 |
| `WS` | `/ws/{session_id}` | 用于实时更新的 WebSocket |
## Makefile 命令
| 命令 | 描述 |
|---|---|
| `make docker-up` | 构建并启动所有服务 |
| `make docker-down` | 停止所有服务 |
| `make docker-logs` | 持续查看所有服务的日志 |
| `make install` | 在本地安装后端和前端依赖 |
| `make dev` | 以开发模式启动后端和前端 |
| `make dev-backend` | 启动后端并开启热重载 |
| `make dev-frontend` | 启动 Next.js 开发服务器 |
| `make db-up` | 仅启动 PostgreSQL |
| `make db-psql` | 打开 psql shell |
| `make db-reset` | 销毁并重建数据库 |
| `make tools-build` | 构建安全工具容器 |
| `make tools-shell` | 进入工具容器的 shell |
## 路线图
- [x] 基于 PostgreSQL 的目标优先数据模型
- [x] 12 款集成的安全扫描器
- [x] 具备 LLM 工具调用编排能力的 AI 聊天模式
- [x] 确定性侦察 pipeline（subfinder → DNS → nmap → httpx → nuclei）
- [x] 带有变更检测的资产清单
- [x] 基于数据库的作业队列和调度器
- [x] 完整的侦察模式 UI（资产清单浏览器、变更查看器、调度管理）
- [x] 作用域强制校验和速率限制
- [x] 审计跟踪和保留策略
- [x] 跨页面导航的会话持久化
- [ ] 多用户身份验证
- [ ] 导出报告（PDF、JSON、CSV）
- [ ] 用于自定义扫描器的插件系统
- [ ] 用于计划性安全检查的 CI/CD 集成
## 免责声明
SHADOWPULSE 仅供**授权的安全测试**使用。在扫描任何目标之前，请务必确保您已获得明确的书面许可。未经授权的扫描是非法且不道德的。对于滥用此工具的行为，作者不承担任何责任。
## 许可证
本项目基于 MIT 许可证授权 — 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
由 Good Security 团队使用咖啡因和 Claude 构建。