0xCD4/n8n-ai-agent-security-lab

# n8n AI 安全回归门禁 [](https://github.com/0xCD4/n8n-ai-agent-security-lab/actions/workflows/test.yml) [](LICENSE) 这是一个 [CSINT Research](https://en.csintresearch.org/) 的副业项目，旨在在投入生产环境之前捕获 n8n AI 工作流中的安全退化问题。 它提供三个小巧且易于解释的输出： - **静态审计：** 跟踪导出工作流中的执行路径，并报告有风险的安全模式。 - **回归门禁：** 向隔离的 staging webhook 发送合成请求，并检查必须保持不变的行为。 - **暴露图：** 将结构化的风险路径转换为 JSON、Mermaid 以及可打印的 SVG 报告图表。 工作流导出文件将保留在本地。扫描器不会上传它们，也不会调用 AI API。 首次扫描：`npm run audit`。查看 [60 秒演示](assets/security-review-demo-en.mp4) 或 [示例审查 PDF](reports/sample-security-review.pdf)。  ## 暴露图 在审计报告旁边生成静态图： ``` node bin/audit.mjs \ workflows/unsafe-support-agent.json \ reports/unsafe-support-agent-audit.md \ --graph reports/unsafe-support-agent-exposure ``` 该命令会生成 `.json`、`.mmd` 和 `.svg` 文件。JSON 保留了扫描器发现项的 ID，因此可以将相同路径与 SARIF 结果相关联。该图仅包含结构化的风险路径，而非所有的工作流节点。 SVG 是一个独立的报告图表：一条从入口点指向最终特权操作的合并数据流，每条风险边上都有发现项 ID，并且包含一个发现项记录表，将每个 ID 和严重程度映射回扫描器证明的确切路径。它仅使用系统字体，在屏幕、PDF 导出和打印报告中均保持清晰可读。  ## 一分钟快速开始 环境要求：Node.js 20 或更高版本。 ``` npm test npm run audit npm run gate:demo ``` 无需安装任何 npm 包。 ## 验证真实的 n8n fixture 本仓库包含一个可导入的 staging 工作流以及与之匹配的运行时契约。在 Docker Desktop 运行的情况下： ``` npm run verify:n8n ``` 此命令将： 1. 创建一个临时的 n8n 2.21.5 实例 2. 导入并发布 staging 工作流 3. 运行全部八项契约测试 4. 确认未执行任何模拟的外部操作 5. 移除临时容器和卷 它不会使用现有的 n8n 实例、卷或凭据。 ## 当前结果 | 工作流 | 静态结果 | 主要发现 | | --- | ---: | --- | | 不安全支持代理 | 10/100, F | 9 项发现，包含 4 项高危 | | 已加固支持代理 | 93/100, A | 1 项中等风险项，保留用于人工 URL 审查 | | 运行时 staging fixture | 8/8 通过 | 0 项模拟外部操作 | 此分数仅作为审查辅助，并非工作流安全的证明。 ## 门禁检查项 | 检查项 | 预期的 staging 行为 | | --- | --- | | 缺少身份验证 | 拒绝 | | 无效的 staging 签名 | 拒绝 | | 缺少或意外字段 | 拒绝 | | 提示注入标记 | 保持在审批之后 | | 无效的审批 token | 拒绝 | | 有效请求 | 入队但不执行外部操作 | | 重复的请求 ID | 返回相同的操作 | | 不支持的方法 | 拒绝 | 包含的运行时 fixture 不包含任何电子邮件、HTTP 请求、数据库或 AI 节点。有效的审批只会增加一个独立的测试计数器。 ## 扫描您自己的导出文件 ``` node bin/audit.mjs path/to/workflow.json reports/my-audit.md ``` 在存储或共享导出文件之前，请务必移除凭据、客户数据、私有 URL 和生产环境的 payload。 ## 运行 staging 契约 ``` export N8N_STAGING_SIGNATURE="replace-with-a-test-only-value" node bin/gate.mjs \ --workflow path/to/workflow.json \ --contract path/to/security-contract.json \ --target http://127.0.0.1:5678 \ --out reports/runtime-gate.md ``` PowerShell： ``` $env:N8N_STAGING_SIGNATURE = "replace-with-a-test-only-value" ``` 默认情况下允许使用环回目标。远程目标需要提供 `--allow-remote`、精确的主机名允许列表以及严格的路径允许列表。不执行重定向跳转。报告中会省略请求标头和正文。 在调整 fixture 之前，请阅读 [安全契约指南](docs/security-contract.md)。 ## 输出格式 回归门禁可以输出以下格式： - Markdown，用于人工审查 - JSON，用于自动化处理 - JUnit，用于测试流水线 - SARIF，用于代码扫描 请参阅 [GitHub Actions 集成](docs/github-actions.md)。 ## 仓库结构 | 路径 | 用途 | | --- | --- | | `bin/` | 静态审计和回归门禁命令 | | `contracts/` | 运行时行为契约 | | `src/` | 扫描器、目标策略和报告生成 | | `test/` | 确定性单元测试和契约测试 | | `workflows/unsafe-support-agent.json` | 故意设计为不安全的教学 fixture | | `workflows/hardened-support-agent.json` | 已加固的对比 fixture | | `workflows/security-regression-staging-target.json` | 可导入、无操作的 n8n staging 目标 | | `reports/` | 示例审计和门禁输出，以及示例审查 PDF | | `media/` | 演示视频和示例 PDF 的源文件及构建脚本 | | `outreach/` | 用于试点审查的发布文案 | ## 安全边界 本项目仅用于防御和教育目的。 - 切勿激活该不安全工作流。 - 切勿将生产环境凭据附加到测试 fixture 上。 - 仅对您拥有或被授权测试的隔离系统运行动态检查。 - 切勿将通过审查的报告视为渗透测试、合规性结果或安全保证。 在报告敏感问题之前，请阅读 [SECURITY.md](SECURITY.md)。 ## CSINT 研究 由 Ahmet Göker 作为 CSINT Research 的副业项目构建并维护。 - [CSINT Research](https://en.csintresearch.org/) - [AI 代理工作流审查](https://en.csintresearch.org/ai-agent-audit) - [人工审查范围](SERVICE.md) ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。

标签：DevSecOps, MITM代理, 上游代理, 人工智能, 工作流引擎, 用户模式Hook绕过, 自定义脚本, 请求拦截, 错误基检测, 静态代码分析