sanjoy1234/gauntlex

## 它是什么 每一款 AI 编码工具都在生成代码后，指望有人能在之后进行安全测试。 GAUNTLEX 消除了“之后”。它会针对同一份规范并发运行两个 agent： - **Builder** — 生成实现代码 - **Breaker** — 在同一时刻针对同一份规范生成对抗攻击 **Arbiter** 会对每次攻击进行评分（已缓解 / 部分缓解 / 未拦截），并生成 **对抗韧性评分 (ARS)**。当评分低于阈值时，一个可配置的 gate 会阻断你的 CI 流水线 —— 就像失败的测试套件阻断合并一样。 无需手动编写测试。无需单独的安全审查步骤。也无需等待扫描器去追赶上周发布的代码。 ## 运行展示 **📊 单页概述** —— 它是什么、有何不同、如何部署。专为分享给技术负责人或架构审查委员会而制作。 **[下载完整 PDF](docs/media/GAUNTLEX_Overview.pdf)** **观看演示** 从设置 CI gate 到真实的终端输出、真实的仪表盘 —— 并发的 Builder + Breaker、HIPAA 领域测试，以及所有的 IDE 集成一次性展示。 ## 为什么它在结构上与众不同 这是三个属性，而非功能 —— 每个属性背后的逻辑都在[深度解析](docs/DEEP_DIVE.md)中： 1. **并发，而非顺序。** Builder 和 Breaker 通过 `asyncio.gather()` 在同一瞬间触发。Breaker 永远看不到生成的代码 —— 它仅从规范进行推断，这与在你的实现选择存在之前，真实攻击者所利用的攻击面完全相同。 2. **双向的原生 MCP 集成。** GAUNTLEX 将自身作为 MCP server 暴露出来，因此 Claude Code、Cursor、Windsurf 或 Zed 可以直接从你的编码工具中触发和轮询运行 —— 并且它还能调用外部 MCP server（以及内置的 CISA KEV / NIST NVD 数据源），利用实时的威胁情报来丰富每一次运行。关于哪些是动态数据、哪些是静态数据的具体信息，请参阅[领域情报](docs/DOMAIN_INTELLIGENCE.md)页面。 3. **将合规领域作为一等输入。** FINRA、HIPAA、PCI DSS、SOC 2 和 OWASP Top 10 playbook 会引导 Breaker 去关注那些对于受监管代码库真正重要的场景 —— 而不是对每个行业重新标签化的通用扫描。 ## GAUNTLEX 与其他安全测试的定位对比 它不是以下任何工具的替代品 —— 而是生命周期中的另一个触发点。静态分析和渗透测试依然值得去做；GAUNTLEX 的存在是因为它们都没有在*代码生成的同时*运行。 | | 传统 SAST (Semgrep, Snyk 等) | 手动渗透测试 | 无专门测试 | GAUNTLEX | |---|---|---|---|---| | **运行时机** | 代码编写完成之后 | 代码编写完成之后，定期进行 | 从不，直到发生安全事件 | 与代码生成的同一瞬间 | | **测试对象** | 现有代码中的已知漏洞模式 | 实时的、已部署的系统 | 无专门测试 | 从规范到代码的生成流水线本身 | | **速度** | 每次扫描数分钟 | 每次评估数天至数周 | — | 每次运行约 45秒–12分钟（取决于模式） | | **成本** | 免费 - 适中 | 高（专家时间） | 出事前“免费” | 免费且开源 | | **合规映射** | 因工具而异 | 手动的，特定于每次评估 | 无 | 内置 —— OWASP/HIPAA/FINRA/PCI-DSS/SOC2 + CWE + NIST SSDF/SAMM/ISO 27001 | | **后续可验证的输出** | 扫描报告 | 渗透测试报告 | — | 带有防篡改 SHA-256 哈希的报告 (`gauntlex verify`) | ## 快速开始 ``` gauntlex setup # start here — interactive, detects and validates the best # model for your environment (Ollama, OpenRouter free # tier, or your own API key) gauntlex run --issue examples/demo_issue.md --mode quick --pretty # then run the demo spec ``` 首先使用 `pip install gauntlex-ai` 安装，或者使用 `uvx --from gauntlex-ai gauntlex setup` 完全跳过安装步骤。 `gauntlex setup` 会将你的模型提供商和凭证写入 `.env` 中 —— 不需要手动配置步骤，也不会退而使用环境中碰巧存在的任何 API 密钥。你在设置期间配置的内容就是始终会运行的内容（如果你还想要 一个包含诸如 `rounds_max` 或 gate 阈值等可调默认值的 `.gauntlex.yml`，请 单独运行 `gauntlex init`）。 ``` ────────────────────────────────────────────────────────────────────── GAUNTLEX Adversarial Run Mode: quick (5 attacks) Language: python [signals: filesystem, async] Domain: owasp_top10 ────────────────────────────────────────────────────────────────────── ARS Score: 0.87 ✅ PASSED (gate: ≥ 0.80) ✅ CWE-89 SQL Injection via username param mitigated ✅ CWE-502 Unsafe deserialization mitigated ✅ CWE-78 OS command injection in file path mitigated ✅ CWE-22 Path traversal in upload handler mitigated ❌ CWE-79 Reflected XSS in error message MISSED ────────────────────────────────────────────────────────────────────── ``` 实际耗时取决于你配置的模型 —— 从使用快速的付费 API 只需几秒，到使用免费层级或本地模型需要几分钟不等。 攻击数量目标按模式（`quick`/`standard`/`thorough`）分别为 5/20/50，分布在多个对抗轮次中 —— 实际的攻击总数会接近但并不总是完全等于目标值（例如，一次 `thorough` 运行可能会触发 ~30–50 次攻击），因为它取决于模型在每轮实际返回的攻击数量。 ### 直接针对 GitHub issue 运行 ``` gauntlex run --issue https://github.com/your-org/your-repo/issues/42 --mode standard --domain hipaa --pretty ``` ### 添加业务意图 —— 攻击面 = 规范 + 为什么需要它 `--issue` 是规范 —— 足够精确，能让 Builder 和 Breaker 进行实现和攻击。它回答了要构建*什么*。`--intent` 增加了第二个独立的输入，回答了*为什么*需要它，这些信息提取自你的团队实际跟踪业务的地方：Jira key、Confluence 页面或 Aha! 路线图项目。GAUNTLEX 会结合两者进行推断，而不仅仅是单看规范。 ``` gauntlex run --issue SPEC.md --intent PROJ-123 --domain hipaa --pretty ``` 如果 `gauntlex setup` 在你的环境中检测到凭证，它会自动连接 Jira/Confluence/Aha! —— 请参阅交互式向导中的业务意图步骤。 ### 前置条件 - Python 3.11+ - macOS、Linux 或 Windows（在 Windows 上推荐使用 WSL2） - 一个模型提供商：[Ollama](https://ollama.com)（免费，本地）、OpenRouter 免费层级，或 Anthropic/OpenAI API 密钥 ## CLI 参考 所有 22 个命令，按你可能会用到它们的时间进行分组： | 初始设置 | | |---|---| | `gauntlex setup` | 配置模型提供商和集成（随时运行以重新配置） | | `gauntlex init` | 以合理的默认值搭建 `.gauntlex.yml` | | `gauntlex doctor` | 完整的运行环境健康检查 | | `gauntlex validate` | Dry run —— 检查配置和连接性，不触发任何攻击 | | 运行评估 | | |---|---| | `gauntlex run` | 在规范上运行对抗性的 Builder + Breaker | | `gauntlex status` | 显示正在运行和最近完成的运行 | | `gauntlex findings` | 上次运行的漏洞发现 —— 修复优先，评分随后 | | `gauntlex compare` | 对比两个韧性报告的差异 —— ARS 差值和攻击级别的变化 | | `gauntlex learn` | 将某次运行输入到 Knowledge Forge + Forge Ledger（在每次 `gauntlex run` 后自动运行 —— 使用此命令可重新处理较早的运行） | | 证据与合规 | | |---|---| | `gauntlex report` | 以任何输出格式（HTML/SARIF/JUnit/JSON）渲染存储的报告 | | `gauntlex verify` | 重新生成 SHA-256 完整性哈希，确认报告未被篡改 | | `gauntlex audit` | 列出在特定时间窗口内具有合规控制映射的所有报告 | | `gauntlex vault` | 浏览 Forge Ledger —— 人类可读的 Markdown 攻击记录 | | `gauntlex stats` | ARS 趋势、学习曲线和成本指标 | | 领域与策略 | | |---|---| | `gauntlex policy` | 列出、安装、搜索或验证策略领域 —— 参见[领域情报](docs/DOMAIN_INTELLIGENCE.md) | | 团队与 CI 部署 | | |---|---| | `gauntlex integrate` | 一条命令：将 GAUNTLEX 接入 Claude Code、Cursor、Windsurf、Copilot、Codex、Zed、Antigravity 或 GitHub Actions | | `gauntlex mcp-server` | 启动 GAUNTLEX 作为 MCP server（stdio 传输）以供本地 IDE 使用 | | `gauntlex serve` | 启动 GAUNTLEX 作为 webhook/CI 服务，带有可选的基于 GitHub 团队的 RBAC | | `gauntlex dashboard` | 启动 GAUNTLEX 仪表盘 Web UI（同时提供位于 `/leaderboard` 的实时排行榜） | | `gauntlex leaderboard` | 跨多个 agent/运行构建一个*静态的* ARS 排行榜 HTML 页面 —— 例如用于 GitHub Pages | | `gauntlex forge-network` | 选择性加入的社区对抗模式共享 | | `gauntlex prune` | 删除过期的报告 | 每个命令的完整用法、标志和示例：[深度解析 → 完整 CLI 参考](docs/DEEP_DIVE.md#complete-cli-reference)。 ## 语言支持 从规范中自动检测 —— 无需针对项目进行配置： | 语言 | 优先关注的 CWE（示例） | |---|---| | Python | SQL 注入、OS 命令注入、不安全的反序列化、路径遍历 | | JavaScript / TypeScript | 原型链污染、XSS、CSRF、SSRF | | Java | 反序列化、XXE、越权访问 | | Go | 竞态条件、空指针解引用、资源耗尽 | ## 合规性与领域覆盖 目前附带了 5 个受监管行业的 playbook —— **总计 43 个攻击场景**，每个 场景都映射到具体的规则或控制措施，而不是通用的标签： | 领域 | 场景数 | 监管框架 | |---|---|---| | `owasp_top10` | 12 | OWASP Top 10 (2021/2025) | | `finra` | 9 | FINRA Rules 4370, 3110; SEC Rule 17a-4 | | `hipaa` | 9 | HIPAA Security Rule (45 CFR §§160, 164) | | `soc2` | 7 | AICPA SOC 2 Trust Service Criteria | | `pci_dss` | 6 | PCI DSS v4.0 | 另外两个（`owasp_api_security`、`nist_ssdf`）可以通过 `gauntlex policy install` 获取。GDPR、FedRAMP 和 DORA 已在[路线图](docs/DEEP_DIVE.md#roadmap) 中 —— 目前尚不可用。 **关于哪些是实时威胁数据、哪些是静态 playbook 内容，以及如何 引入你自己的领域，请参阅完整的 [领域情报页面](docs/DOMAIN_INTELLIGENCE.md)。** ## IDE 与 agent 集成 一条命令即可将 GAUNTLEX 接入你当前打开的任何 AI 编码工具： ``` gauntlex integrate --dry-run # preview every config it would write, writes nothing gauntlex integrate # wire up every supported target at once gauntlex integrate --platform claude-code # or just one — .mcp.json gauntlex integrate --platform cursor # .cursor/mcp.json gauntlex integrate --platform windsurf # ~/.codeium/windsurf/mcp_config.json gauntlex integrate --platform copilot # .vscode/mcp.json gauntlex integrate --platform codex # ~/.codex/config.toml gauntlex integrate --platform zed # .zed/settings.json gauntlex integrate --platform antigravity # ~/.gemini/config/mcp_config.json gauntlex integrate --platform github-actions # .github/workflows/gauntlex.yml CI gate ``` 每个目标都会获得适合该特定工具的文件、格式和 schema —— 这个命令处理了这些差异，因此你无需操心 —— 并且它会**合并** 到你已有的任何配置中，而不是覆盖它，因此你已经配置好的其他 MCP server 会继续保留。 **Claude Code 用户**也可以通过插件市场安装，而不是使用 `integrate`： ``` /plugin marketplace add sanjoy1234/gauntlex /plugin install gauntlex@gauntlex ``` 这将在一个步骤中注册 MCP server 和所有的 `/gauntlex:*` 技能（`run`、`verify`、 `doctor`、`compare`、`report`、`learn`、`validate`），并通过 `/plugin update` 进行更新。要求 `gauntlex` 在 `PATH` 中（`pip install gauntlex-`）。 **零配置：**此仓库附带了一个 [AGENTS.md](AGENTS.md)，Codex、Cursor、 Cline、Windsurf 和 Gemini CLI 会自动读取它，完全无需任何安装步骤 —— 如果你是在 GAUNTLEX 的基础之上进行构建，而不仅仅是使用它，可以将这种模式 复制到你自己的仓库中。 各平台的确切文件路径、合并安全保证，以及 GAUNTLEX 暴露的 MCP 工具（`gauntlex_run`、`gauntlex_status`、`gauntlex_verify` 等）：**[集成指南](docs/INTEGRATIONS.md)**。 ## 企业部署 - **`gauntlex dashboard`** —— 跨每个连接的仓库的 ARS 趋势、gate 状态和攻击结果分解。一个 URL 即可供整个团队使用。 - **`gauntlex serve --rbac`** —— 跨共享实例的基于 GitHub 团队的访问控制（管理员 / 审查者 / 开发者）。 - **`gauntlex audit`** —— 列出带有 NIST SSDF / OWASP SAMM / SOC 2 控制映射的每次运行，支持自定义时间窗口。 - **气隙隔离运行** —— 整个引擎在本地 Ollama 上运行，零出站调用，适用于无法连接互联网的环境。 各项详情：[深度解析 → 企业特性](docs/DEEP_DIVE.md#enterprise-features)。 ## 关键术语 - **对抗韧性评分 (Adversarial Resilience Score, ARS)** —— 针对一次运行触发的每次攻击的评分均值（已缓解=1.0，部分缓解=0.5，未拦截=0.0）。取值范围 [0.0, 1.0]。这是 GAUNTLEX 产出的核心指标。 - **Builder** —— 根据规范生成代码的 agent。 - **Breaker** —— 在同一瞬间根据相同的规范生成对抗攻击，且不查看 Builder 输出的 agent。 - **并发协同生成** —— Builder 和 Breaker 通过 `asyncio.gather()` 在同一时间针对相同的规范运行，而不是在代码编写完成后再进行测试。 - **韧性报告** —— GAUNTLEX 运行的防篡改输出，包含基于有序攻击结果的 SHA-256 哈希，可通过 `gauntlex verify` 进行独立验证。 - **Gate** —— 当一次运行的 ARS 低于配置的阈值（默认为 0.80）时，阻断合并的 CI 检查。 ## 常见问题解答 **我该如何针对安全漏洞测试 AI 生成的代码？** 将 GAUNTLEX 指向你的 AI 编码工具所使用的同一份规范：`gauntlex run --spec your_spec.md --mode quick`。它会触发源自该规范的对抗攻击，并在一分钟内返回对抗韧性评分。 **什么是对抗韧性评分 (ARS)？** 它是针对一次运行触发的每次攻击的评分均值（已缓解 = 1.0，部分缓解 = 0.5，未拦截 = 0.0） —— 这是一个衡量生成代码防御能力的连续区间 [0.0, 1.0] 指标，而不是简单的通过/失败计数。完整的公式和推理：[ARS 解释说明](https://dev.to/sanjoy1234/the-adversarial-resilience-score-a-new-metric-for-ai-generated-code-4gej)。 **GAUNTLEX 是在代码生成之前还是之后测试代码？** 在同一瞬间。Breaker agent 与 Builder 并发工作，直接从规范进行推断 —— 它永远不需要等待代码先生成，这就是“并发而非顺序”在实际中的含义。 **GAUNTLEX 支持哪些合规框架？** 开箱即支持 OWASP Top 10、HIPAA、FINRA、PCI DSS 和 SOC 2，NIST SSDF 和 OWASP API Security 可作为可安装扩展使用。有关每个领域的具体覆盖范围，请参阅[领域情报](docs/DOMAIN_INTELLIGENCE.md)。 **GAUNTLEX 可以在不将代码发送到外部 API 的情况下运行吗？** 可以 —— 整个引擎在本地 Ollama 上运行，零出站调用，适用于气隙隔离或受合规限制的环境。 更多问题，包括 gate 阈值和如何贡献新的策略领域：[深度解析中的完整 FAQ](docs/DEEP_DIVE.md#faq)。 ## 了解更多 - **[深度解析](docs/DEEP_DIVE.md)** —— 完整的故事：为什么并发执行很重要、GAUNTLEX 与 SAST/DAST/渗透测试的对比、完整的 CLI 和配置参考、架构、FAQ 和路线图。 - **[领域情报](docs/DOMAIN_INTELLIGENCE.md)** —— 每个受监管领域的确切覆盖范围、什么是动态数据与静态数据，以及如何扩展它。 - **[贡献指南](docs/DEEP_DIVE.md#contributing)** —— 如何添加策略领域、语言配置文件或功能。 ## 哪里可以找到 GAUNTLEX **包与注册表** - [PyPI](https://pypi.org/project/gauntlex-ai/) —— `pip install gauntlex-ai` - [官方 MCP 注册表](https://registry.modelcontextprotocol.io) —— 列为 `io.github.sanjoy1234/gauntlex` **文章** - [dev.to — “为什么我构建了一个对抗式协同生成引擎”](https://dev.to/sanjoy1234/why-i-built-an-adversarial-co-generation-engine-2038) - [LinkedIn 文章 — “当 AI 编写数百万行代码时，崩溃的数学逻辑”](https://www.linkedin.com/feed/update/urn:li:activity:7482279870576611328/) **社区**

标签：AI代码生成, AI风险缓解, Petitpotam, Python, 安全扫描, 对抗性AI, 无后门, 时序注入, 计算机取证, 逆向工具