SARA8933326H/agent-surface-mapping
GitHub: SARA8933326H/agent-surface-mapping
一个开源的授权攻击面发现工具，通过 Playwright 爬取结合被动安全检测，将网站资产和风险映射到 OWASP/CWE，并提供交互式仪表板和多格式报告。
Stars: 0 | Forks: 0
# 攻击面发现原型
[](https://github.com/SARA8933326H/agent-surface-mapping/actions/workflows/ci.yml)
一个免费、开源的攻击面发现原型，它能够爬取授权网站，提取页面、表单、端点和资产，通过启发式算法和可选的本地 LLM 对功能进行分类，并将发现映射到 OWASP Top 10 / CWE 风险。它还使用对爬取数据的被动分析以及少量安全、只读的 HTTP 探测来检测常见漏洞——缺失的安全标头、不安全的 Cookie、暴露的敏感文件、CORS 配置错误、过时的 JavaScript 库等。最终结果是一个精美、交互式的仪表板，包含攻击面图表、可下载的报告和技术栈检测。
**重要提示：** 此工具绝不会生成漏洞利用载荷、尝试绕过、暴力破解、注入 SQL 或对输入进行模糊测试。漏洞检查是被动的，或者对目标源使用受限的只读请求（GET/OPTIONS/TRACE）。仅扫描您获得授权测试的系统。
## 架构
```
attack-surface-prototype/
├── backend/ NestJS API + Prisma + BullMQ worker
├── frontend/ Next.js dashboard (React Flow + Recharts)
├── shared/ TypeScript DTOs and contracts
├── crawler/ Playwright-based crawler
├── classifier/ Heuristic + optional LLM risk mapper
├── knowledge-base/ Local JSON OWASP/CWE mappings
├── reports/ Markdown, JSON, and PDF generators
└── docker/ Dockerfiles
```
- **Monorepo：** pnpm workspaces
- **Queue：** 由 Redis 支持的 BullMQ
- **Database：** 通过 Prisma 实现的 PostgreSQL
- **Crawler：** 带有 JS 渲染、robots/sitemap 解析和 SPA 支持的 Playwright Chromium
- **AI：** 可选的本地 Ollama、Gemma、Qwen、Llama、DeepSeek 或 Gemini Free API —— 该系统在没有 AI 的情况下使用启发式规则也能正常工作。
## 前置条件
- Node.js 20+
- pnpm 9+（`corepack enable` 或 `npm install -g pnpm`）
- PostgreSQL 15+（或 Docker）
- Redis 7+（或 Docker）
- Playwright 浏览器：`pnpm --filter @surface/crawler exec playwright install chromium`
- 可选：用于本地 LLM 摘要的 Ollama
## 快速开始（本地）
1. **安装依赖**
pnpm install
2. **设置环境变量**
cp .env.example .env
# 使用您本地的 PostgreSQL 和 Redis URL 编辑 .env
3. **运行数据库迁移**
pnpm db:migrate
4. **启动后端 API**
pnpm start:backend
5. **启动 worker**（在另一个终端中）
pnpm start:worker
6. **启动前端**（在另一个终端中）
pnpm start:frontend
打开 [http://localhost:3000](http://localhost:3000) 并开始发现。
## 快速开始（Docker Compose）
```
pnpm install # or skip if you want Docker to install
docker-compose up --build
```
这会启动 PostgreSQL、Redis、后端 API、worker 和前端，访问地址为：
- 前端：[http://localhost:3000](http://localhost:3000)
- 后端 API：[http://localhost:3001](http://localhost:3001)
- API 文档：[http://localhost:3001/api/docs](http://localhost:3001/api/docs)（在 `NODE_ENV=production` 时禁用）
## 生产环境（HTTPS + 托管 Postgres/Redis）
使用 `docker-compose.prod.yml`。它会移除本地的 postgres/redis 容器，需要为您的托管服务提供 `DATABASE_URL`/`REDIS_URL`，并在前面放置一个 Caddy 反向代理，通过自动获取的 Let's Encrypt 证书来终止 HTTPS。迁移在后端启动时通过 `prisma migrate deploy` 运行 —— 永远不会在生产环境中使用 `migrate dev`。
```
# .env 文件与 docker-compose.prod.yml 位于同一目录下：
# DATABASE_URL=postgresql://user:pass@your-managed-pg:5432/surface
# REDIS_URL=rediss://your-managed-redis:6379
# DOMAIN=surface.example.com
# API_DOMAIN=api.surface.example.com
# CORS_ORIGIN=https://surface.example.com
docker compose -f docker-compose.prod.yml up --build -d
```
`DOMAIN` 和 `API_DOMAIN` 的 DNS 都必须解析到开放了 80/443 端口的主机，以便 Caddy 可以签发证书。设置 `TRUST_PROXY=true`（已在生产环境 compose 文件中设置），以便速率限制根据真实的客户端 IP 进行限制。
## API 安全性
- **API key：** 在后端设置 `API_KEY`（在生产环境 compose 文件中必需），并且每个请求必须通过 `X-API-Key` 标头（或下载链接使用 `?key=`）发送它。前端在使用 `NEXT_PUBLIC_API_KEY` 构建时会自动发送它。这是一个共享的部署密钥 —— 任何可以打开仪表板的人都能看到它，因此请将仪表板的访问权限视为信任边界。当未设置 `API_KEY` 时（本地开发的默认设置），身份验证将被禁用。`/health` 始终是公开的。
- **SSRF 防护：** 默认情况下，API 会拒绝私有、环回、链路本地或保留 IP 的扫描目标 —— 包括 DNS 解析为此类 IP 的目标（这会阻止像 `169.254.169.254` 这样的云元数据端点）。仅在本地开发时设置 `ALLOW_PRIVATE_TARGETS=true`。注意：验证在创建扫描时进行；在爬取过程中更改记录的 DNS 重绑定攻击不在防范范围内。
## 扩展 Worker
Worker 是无状态的，可以进行水平扩展；爬取任务会通过指数退避进行重试（`QUEUE_ATTEMPTS`、`QUEUE_BACKOFF_DELAY`），每个 worker 会运行 `WORKER_CONCURRENCY` 个并发任务（默认为 2）。
```
docker compose up -d --scale worker=4
```
或在任意一个 compose 文件中设置 `WORKER_REPLICAS`（默认为 2）。
## 测试与 CI
```
pnpm test # backend Jest suite: unit tests for vulnerability checks and the
# SSRF target validator, plus an integration test that runs the
# active probes against live fixture servers
```
GitHub Actions（`.github/workflows/ci.yml`）会在每次推送到 `master`/`dev` 分支以及每个针对 `master` 的 PR 时构建所有包、进行类型检查、运行测试套件并构建前端。
## 工作原理
1. 用户输入一个已授权的 URL。
2. 后端将爬取任务放入 BullMQ 队列。
3. worker 启动 Playwright，探索应用程序，并提取页面、表单、端点、资产、Cookie、标头和屏幕截图。
4. 启发式分类会识别身份验证、管理面板、仪表板、搜索、CRUD、上传、下载、API、GraphQL 和隐藏页面。
5. 本地的 JSON 知识库将每个发现的功能映射到 OWASP Top 10 和 CWE 风险。
6. 漏洞检测会对爬取的数据运行被动检查（安全标头、版本泄露、混合内容、过时的库、表单弱点、JWT 分析）以及可选的只读探测（敏感路径和备份文件、HTTP 方法、CORS、Cookie 标志、HTTPS 强制执行、TLS 版本/证书过期、目录列出、GraphQL 自省），从而生成带有修复指导且基于证据的发现结果。
7. 可选的本地 LLM 可以针对相同的数据库总结现有的发现；它绝不会凭空捏造新的漏洞。
8. 后端构建一个由节点（页面、表单、端点、脚本、身份验证、管理面板、对象）和边（导航、API 调用、表单操作、导入、关系）组成的内部图表。
9. 前端显示交互式图表、表格、统计信息、风险、检测到的漏洞、屏幕截图和报告。
## 定期扫描与差异对比
在创建扫描时传入 `recurringIntervalMin`（或在仪表板中使用“每 N 分钟重复一次”字段），worker 会在每个间隔时间过去后自动将该目标重新加入队列（最短 15 分钟，如果同一 URL 的扫描仍在进行中则会跳过）。每个扫描详情页面都有一个 **Changes**（更改）选项卡（`GET /scans/:id/diff`），用于将其与同一 URL 的上一次已完成扫描进行比较：新增/移除的页面和端点，以及新增和已修复的漏洞。
## API 端点
| Method | Path | Description |
| ------ | ----------------------------- | ---------------------------------- |
| POST | `/scans` | 创建并将新扫描加入队列 |
| GET | `/scans` | 列出所有扫描 |
| GET | `/scans/:id` | 获取完整的扫描详情 |
| GET | `/scans/:id/stats` | 获取扫描统计信息 |
| POST | `/reports/scans/:id/:format` | 生成 PDF、Markdown 或 JSON |
| GET | `/reports/:id/download` | 下载已生成的报告 |
| GET | `/health` | 健康检查 |
## 报告
报告以三种格式生成：
- **PDF：** 通过 Playwright 从生成的 HTML 报告渲染
- **Markdown：** 包含 OWASP/CWE 映射的易读摘要
- **JSON：** 完整的机器可读扫描输出
生成的报告会本地存储在 `./reports-output`（或在 Docker 中存储于 `/app/reports-output`）。
## 可选的本地 AI
要启用 LLM 摘要，请设置环境变量并确保 Ollama 正在运行且已拉取模型：
```
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=gemma:2b
ollama pull gemma:2b
```
只会要求 LLM 将现有的启发式分类映射到本地知识库中已知的 OWASP/CWE 风险。它不会凭空捏造漏洞。
## 项目结构与决策
- **独立的 crawler/classifier/reports 包：** 保持每个关注点相互隔离且可重用，并让后端专注于 HTTP/queue 的编排。
- **BullMQ worker：** 长时间的爬取异步运行，因此 API 保持响应，用户可以轮询扫描状态。
- **共享 DTOs：** 单个 `@surface/shared` 包提供了后端和前端之间的契约，防止类型漂移。
- **纯 JSON 知识库：** 可审计、可编辑，且无需外部服务。它通过将 AI 限制在这些已知的映射中，确保 AI 永远不会凭空捏造漏洞。
- **React Flow：** 图表以 JSON 节点/边的形式持久化，并在仪表板中交互式渲染。
## 许可证
MIT —— 可免费使用、修改和扩展。
标签：AI风险缓解, BullMQ, NestJS, Playwright, 安全合规审计, 实时处理, 密码管理, 搜索引擎查询, 测试用例, 特征检测, 自动化攻击, 请求拦截