Synapse

<p align="center"> <img src="assets/SynapseV2-Main.png" alt="Synapse Banner"> </p> <p align="center"> <img src="https://img.shields.io/badge/Status-Alpha-red" alt="状态：Alpha"> <img src="https://img.shields.io/badge/License-Apache--2.0-blue" alt="许可证：Apache 2.0"> <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+"> <img src="https://img.shields.io/badge/MCP-Native-purple" alt="MCP 原生"> <img src="https://img.shields.io/badge/Human--First-AI--Powered-success" alt="以人为本，AI 驱动"> </p> <p align="center"> <img src="https://img.shields.io/badge/Operational-Memory-red" alt="运行内存"> <img src="https://img.shields.io/badge/Adapter-Framework-blue" alt="适配器框架"> <img src="https://img.shields.io/badge/Evidence-Driven-orange" alt="证据驱动"> </p> Synapse 是一个本地、以工作区为中心的 MCP 框架，用于操作员控制的进攻性安全工作流。它维护参与状态，组织证据，跟踪授权范围，管理凭证引用，并通过受控的 MCP 适配器编排安全工具。 它为 AI 代理提供结构化的评估上下文，使它们能够在规范的目标、服务、端点、参数、观察结果、发现结果、证据和先前操作上进行推理，而不是在碎片化的工具输出上。 ## 仓库索引 从这里开始： - [快速入门](#快速入门)：安装 Python 环境，运行设置检查，并打印 MCP 客户端配置。 - [示例工作流](#示例工作流)：正常的先被动后主动的评估流程。 - [安全模型](#安全模型)：范围、审批、凭证、证据和清理的防护措施。 - [文档](#文档)：架构、操作、报告、适配器开发和 MCP 参考链接。 核心项目引用： - [架构](docs/Architecture.md)：运行时拓扑、数据流和边界决策。 - [实现地图](docs/Implementation-Map.md)：模块所有权、数据布局、工具表面和模式。 - [操作](docs/Operations.md)：环境设置、操作员程序、作业、凭证、清理和测试。 - [报告模型](docs/Reporting-Model.md)：内部操作员/高级报告视图和它们不应该暗示的内容。 - [Synapse MCP](MCPS/Synapse-MCP/README.md)：完整的工具列表和 MCP 组件注释。 代理指导： - [AGENTS.md](AGENTS.md)：Synapse 的持久运行策略，由 Codex 使用并由 Synapse MCP 提示暴露。 - [技能/](skills)：用于操作和开发 Synapse 的代理技能，按运行时分组 — [技能/claude/](skills/claude) (`synapse-ops`，`synapse-dev`) 和 [技能/codex/](skills/codex) (`operate-synapse`，`synapse-developing`)。参见 [技能/README.md](skills/README.md) 获取安装步骤。 ## 为什么存在 Synapse 安全评估会在 Burp 流量、终端输出、OSINT 服务、笔记、截图、报告和重复的手动决策中产生分散的数据。这种分散性使得 AI 辅助变得脆弱：代理可能会错过已经测试的内容，忘记范围，重复嘈杂的操作，或将原始工具输出视为确认的证据。 Synapse 为授权工作提供了一个本地的操作知识层。操作员仍然负责授权、验证、影响评估和最终报告；Synapse 保留上下文，规范化证据，并通过 MCP 工具和资源使先前的评估知识可用。 ## 什么是 Synapse - AI 辅助的进攻性安全的 MCP 框架。 - 用于授权评估的工作区和证据层。 - 用于选定的安全工具的受控编排层。 - 本地文件支持的上下文存储，代理可以查询。 - 可以随着操作员方法论演变的项目结构。 ## 不是什么 - 全自动的渗透测试代理。 - 一个漏洞扫描器本身。 - 专门工具的替代品，如 Burp Suite、Nmap、FFUF 或 SQLMap。 - 一个旨在在未经操作员批准的情况下运行主动或高影响操作的系统。 - 一个存储笔记、证据或报告中的秘密的地方。 ## 主要功能 ### 工作区和运行内存 - 具有每个目标规范化状态的参与级工作区：服务、端点、参数、观察结果、发现结果、操作和证据。 - 导入 Burp 转储、ffuf JSON、站点地图/爬虫 JSON、nmap XML、Shodan 摘要、Nuclei JSONL、适配器结果和操作员笔记 — 存储为原始证据、解析、规范化和去重每个目标。 - 紧凑的目标上下文（`workspace.prepare_target_context`），以便 AI 客户端从已知内容中规划，而不是重新推导。 - 操作员审查的发现生命周期：`candidate`、`confirmed`、`false_positive`、`accepted_risk`、`fixed`，具有证据链接和报告就绪导出。 ### 范围、批准和凭证安全 - 持久化授权范围（主机、模式、CIDR）在全局和工作区级别；主动适配器在全局文件之前验证工作区的所有权范围。 - 范围和执行批准是独立的门控；主动流量始终需要范围内验证加上 `confirm=true`，适配器记录一致的批准元数据。 - 范围凭证（`bearer`、`basic`、`cookie`、`header`，浏览器导出的 `session`）本地存储，权限为 `0600`，在每个响应中删除，凭证 ID 解析每个请求目标。浏览器身份验证配置文件（Playwright 或 Selenium Remote）处理 SSO、MFA 和设备批准流程。 - 证据事件在写入前会清理包含机密的字段和嵌入的字符串。 ### 被动智能 - 来自离线转储的类似 Burp 的站点地图和工作流图（JSON 加 Mermaid/SVG 流程图），无需发送流量。 - 丰富的请求/响应上下文提取：参数、JSON 字段路径、cookie 名称、授权方案、重定向、表单、API/JSON/GraphQL 信号、身份验证边界、状态更改方法和错误信号。 - 工作区指纹识别成结构化的技术组件，具有名称、版本、层、置信度和证据源。 - 外部边界库存：主机资产、Web 应用程序、技术矩阵、规范登录门户、受保护资源和请求感知审查候选。 - 被动候选分析器，用于 SQLi、XSS、SSRF、开放重定向、命令注入、SSTI、LFI/RFI、SSI、访问控制、CSRF、CORS、XXE、GraphQL、不安全反序列化、安全标头/cookie、JWT 和 TLS 姿势。 - 被动 OpenAPI/Swagger/Postman 规范导入，规范化文档化的端点、参数和身份验证方案，无需发送流量。 ### JavaScript 智能 - 从存储的工作区数据、批准的边界获取和静态分析（无 JavaScript 执行）中发现 JS 资产：API 端点、方法、API 基础、GraphQL 操作、WebSocket URL、存储键、身份验证/ CSRF 头名称和对象标识符。 - JS 推断的端点规范为 `derived`/`inferred` 记录，永不覆盖观察到的流量，加上 JS 丰富的应用程序地图作为 HTML、Markdown 或 JSON。 ### 受保护的主动适配器和后台作业 - 有限的主动爬取（包括身份验证的扩展 POST 表单映射）、受限的 ffuf 和自适应 Nuclei 配置文件，以及 nmap 配置文件。 - 有限的、操作员批准的单次 HTTP 探测，用于 XSS、SSRF、开放重定向、命令注入、SSTI、LFI/RFI、SSI、XXE、CORS 和 GraphQL 内省，以及批准的访问控制矩阵重放跨凭证上下文。每个主动探测都经过范围检查、`confirm=true` 门控，并且通过构造保持良性。 - 长期运行的工具作为工作区范围的后台作业运行，默认情况下具有持久的 `jobs.list` / `jobs.status` / `jobs.cancel` 记录，这些记录在 MCP 重启后仍然存在；延迟终结将已完成输出摄入工作区。 - stdio 传输应用每个调用的有限截止时间，以便慢速同步调用返回可恢复的 JSON-RPC 错误，而不是阻塞服务器。 ### 报告和文档 - 规范的被动报告层（边界、JavaScript、身份验证、访问控制），具有共享结构：摘要、章节、每个目标的上下文、覆盖范围和推荐的下一步骤。 - 单层和全层工作区报告为 Markdown、JSON 上下文或便携式自包含 HTML，具有共享的 Synapse 视觉身份。 - 报告、发现草稿、证据包、覆盖范围和评估摘要上下文。HTML 报告是内部操作员工件，具有操作员/高级演示视图。报告生成永远不会发送主动流量。 ## 心智模型 ```text 操作员 / AI 客户端 | v MCP 边界 |-- Burp MCP 可选的实时 Burp Suite 状态和 UI/会话操作 `-- Synapse MCP 本地策略、工作区内存、证据和适配器 |-- 范围和批准门控 |-- 规范的工作区实体 |-- 证据和凭证引用 |-- 被动分析器和文档上下文 `-- 受控的主动适配器和后台作业 ``` Synapse 支持两个 MCP 边界： - `synapse`：用于策略、状态、证据和适配器的本地 Synapse MCP。这是必需的操作端点。 - `burp`：PortSwigger 的官方 Burp MCP stdio 代理启动器，可选但强烈建议用于实时 Burp Suite 状态和 UI/会话操作。 有关完整的运行时拓扑、数据流和边界决策，请参见 [架构](docs/Architecture.md)。 ## 核心概念 | 概念 | 目的 | | --- | --- | | 范围 | 持久的授权允许列表，适用于主机、模式和 CIDR。 | | 工作区 | `DATA/workspaces/<workspace-id>/` 下的参与级状态。 | | 目标 | 每个主机规范化状态：服务、端点、参数、发现结果、操作、观察结果。 | | 证据 | 原始本地工件加上全局和主机索引的 JSONL 事件日志。 | | 观察结果 | 通过解析、被动分析、OSINT 或工作流映射产生的假设或线索。 | | 发现结果 | 操作员审查或生命周期管理的具有状态、严重性、置信度、证据 ID、影响和补救的议题。 | | 操作 | 记录的目标的被动或主动工具活动。 | | 凭证 | 本地存储的范围 HTTP 机密，引用 `credentialId`；响应被删除。 | | 后台作业 | 工作区范围的长期运行工具记录，通过 `jobs.*` 查询。 | | 指纹 | 来自转储或规范的工作区数据的被动技术和主机行为摘要。 | | 边界 | 资产、技术的被动库存、Web 应用程序、登录门户、受保护资源和审查候选。 | | 文档上下文 | 从工作区数据构建的规范报告、发现结果、证据包、覆盖范围、层或整个工作区模型，然后渲染。 | ## 快速入门 必需： - Python 3.10+ 作为 `python3` - Synapse MCP 运行时依赖的存储库虚拟环境。 - 可以启动 stdio 服务器的 MCP 客户端，例如 Codex 推荐的可选工具： - 用于浏览器辅助身份验证流程的 Playwright Chromium。 - 适用于匹配适配器工作流的 `sqlmap`、`ffuf`、`nuclei` 和 `nmap`。 - 用于 `MCPS/Burp-Mcp/mcp-proxy.jar` 的 Java - 启用了 PortSwigger 的 MCP 服务器扩展的 Burp Suite - `MCPS/Burp-Mcp/` 下的 PortSwigger 的 Burp MCP 代理启动器 1. 从存储库根目录创建并填充 Synapse 虚拟环境： ```bash python3 -m venv .venv . .venv/bin/activate python -m pip install -U pip python -m pip install -e '.[browser]' python -m playwright install chromium ``` 2. 运行设置检查，验证所需的 Synapse 先决条件并打印 MCP 客户端配置： ```bash bin/check-setup ``` 默认情况下，缺少的外部扫描器二进制文件会发出警告，因为被动、离线、报告和静态分析工作流在没有它们的情况下仍然有效。 3. 对于完整的主动适配器工作站，还需要扫描器二进制文件： ```bash bin/check-setup --strict-tools ``` 4. 打印 MCP 客户端配置而不运行检查： ```bash bin/print-mcp-config ``` MCP 客户端应启动 `MCPS/Synapse-MCP/bin/synapse-mcp` 而不是系统 `python3`，因此浏览器身份验证依赖项来自存储库 venv。两个启动器都从 `config/synapse.env` 加载本地配置；运行时数据默认情况下位于 `SYNAPSE_ROOT/DATA` 下。Shodan API 密钥从不存储在配置中 — 仅在运行时使用 `shodan.session_key.set` 设置。 可选的 Burp MCP 支持对于 Synapse MCP、离线转储分析、工作区内存、被动分类或报告不是必需的。仅当您需要实时 Burp Suite 状态（例如代理历史记录、Repeater 或 UI/会话交互）时才安装它。 有关环境详细信息、超时旋钮和完整操作员程序，请参见 [操作](docs/Operations.md)。 ## 示例工作流 ```text 1. 启动具有授权范围的评估工作区。 2. 导入被动的 Burp 流量或运行批准的爬取/侦察。 3. 使用 `jobs.status` 将任何后台作业轮询到完成。 4. 规范化端点、参数、服务、观察结果和证据。 5. 运行或查看工作区指纹识别。 6. 刷新边界摘要/报告。 7. 为 AI 助手准备紧凑的目标上下文。 8. 仅当被动图片证明合理时，运行更深入的批准验证。 9. 审查候选观察结果并将验证的议题提升为发现结果。 10. 链接证据并导出报告就绪的上下文。 ``` 示例 MCP 工具调用： ```json { "tool": "project.start", "arguments": { "organization": "Client", "workspaceId": "client-web-2026", "hosts": ["app.example.com"], "notes": "外部网络评估范围" } } ``` ## MCP 工具表面 权威的运行时模式位于 `MCPS/Synapse-MCP/synapse_mcp/transport/stdio_server.py`；完整的、测试防护的工具列表在 [MCPS/Synapse-MCP/README.md](MCPS/Synapse-MCP/README.md) 中维护。在高级别上，Synapse 公开了以下工具： - 适配器发现：`adapters.list`、`adapters.capabilities`。 - 项目、范围、工作区、证据、凭证和发现生命周期。 - 后台作业：`jobs.list`、`jobs.status`、`jobs.cancel`。 - 离线转储、缓存检查、被动站点地图生成和工作流图工件。 - 工作区指纹识别、外部边界分析和边界报告渲染。 - JavaScript 智能和 JS 丰富的应用地图报告。 - 文档上下文和内部 Markdown/JSON/HTML 导出。 - Web 评估适配器：爬虫、ffuf、Nuclei、SQLi/XSS 分类、SSRF、开放重定向、命令注入、SSTI、LFI/RFI、SSI、访问控制、CSRF、CORS、XXE、GraphQL、不安全反序列化、安全头/cookie、JWT、TLS 姿势和 OpenAPI/Swagger/Postman 规范导入。 - 基础设施和 OSINT 适配器：nmap 和 Shodan。 代表性的实体和事件模式在 [实现地图](docs/Implementation-Map.md) 中有文档记录。 ## 适配器框架 Synapse 适配器是模块化的评估组件，插入工作区、证据、范围、凭证、操作和发现生命周期。每个适配器都声明其元数据、功能、风险模型、流量行为和输出类型，以便组织可以在 Synapse 核心框架之上构建自己的方法论，而无需修改它。 - [适配器开发](docs/Adapter-Development.md) - [自定义适配器模板](examples/custom_adapter_template/README.md) ## 工作区数据布局 运行时数据在 `DATA/` 下本地且文件支持： ```text DATA/ |-- scope/scope.json 全局主机、模式、CIDR 和注释 |-- credentials/credentials.json 范围凭证存储（0600） |-- evidence/ 全局和主机索引的事件日志 `-- workspaces/<workspace-id>/ |-- workspace.json 参与元数据和目标索引 |-- scope.json 工作区拥有范围快照 |-- jobs/<job-id>/job.json 后台作业记录 |-- reports/ 生成的层、工作区和应用地图报告 |-- outputs/ 工作区级生成的输出 `-- targets/<host>/ |-- entities/ 服务、端点、参数、发现结果、操作、观察结果 |-- models/ 边界和访问控制模型 |-- outputs/ 工具和 JavaScript 智能输出 `-- evidence/ 原始工件和 Burp 转储 ``` 完整的带注释的布局在 [实现地图](docs/Implementation-Map.md) 中。 ## 安全模型 Synapse 设计用于授权的安全评估，并让操作员保持控制： - 只在操作员授权测试的系统上工作。 - 范围和执行批准是独立的门控；主动流量需要范围内验证和 `confirm=true`，优先检查工作区的持久范围。 - 被动/离线摄取可能会保留范围外数据，但始终会报告 `scopeStatus` 和警告，而不是隐藏授权状态。 - 凭证按授权主机进行范围限定，并以删除的凭证返回；证据事件在写入前会对机密进行清理。 - 默认情况下，生成的文件输出位于工作区文件夹下；外部输出路径需要 `allowExternalOutput=true`。 - 转储和生成工件的清理是先检查再删除，删除前需要确认。 - 不公开 SQLMap 执行；仅提供离线分析和受控命令生成。命令注入执行仅限于批准的良性标记请求。 完整的 安全模型，包括凭证、浏览器会话和证据清理保证，在 [架构](docs/Architecture.md) 中有文档记录。 ## 文档 - [文档索引](docs/README.md) - [架构](docs/Architecture.md)：边界、数据流、安全模型。 - [实现地图](docs/Implementation-Map.md)：模块、工具表面、数据布局、工作流、模式。 - [报告模型](docs/Reporting-Model.md)：内部报告视图、呈现切换和报告不应做的事项。 - [操作](docs/Operations.md)：设置、操作员程序、清理、测试。 - [适配器开发](docs/Adapter-Development.md) - [Synapse MCP](MCPS/Synapse-MCP/README.md)：完整的工具列表和适配器策略。 - 当安装可选的启动器时，`MCPS/Burp-Mcp/README.md` 下的 Burp MCP 注释。 ## 项目卫生 - [贡献指南](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [许可证](LICENSE) ## 测试 运行所有存储库测试： ```bash bin/test ``` 有用聚焦模式： ```bash bin/test --core bin/test --template bin/test --core -k access_control ``` 测试套件涵盖适配器分析、凭证安全、证据删除、工作区摄取和重复数据删除、被动 Burp 上下文解析、候选分析器、JavaScript 智能提取/报告、发现生命周期操作、主动工具钩子、MCP 调度以及自定义适配器模板。 ## 授权使用声明 Synapse 旨在授权安全测试、内部研究和防御性评估工作流。未经授权，请勿将其用于您无权测试的系统。操作员负责范围、批准、验证和遵守适用法律和参与规则。 ## 许可证 Synapse 在 Apache License, Version 2.0 下许可。 参见 [LICENSE](LICENSE) 获取完整许可文本， [NOTICE](NOTICE) 获取属性和第三方通知。