GAUNTLEX

---

它是什么

每款 AI 编码工具都会交付代码，并寄希望于有人日后对其进行安全测试。 GAUNTLEX 消除了“日后再说”。它会针对同一份规范并发运行两个 Agent：

• Builder — 生成实现
• Breaker — 在同一时刻针对同一份规范生成对抗性攻击

Arbiter 会为每次攻击评分（已缓解／部分缓解／未发现），并生成 对抗韧性评分（ARS）。可配置的门禁会在评分低于阈值时阻止 CI 流水线——就像测试套件失败会阻止合并一样。

无需手动编写测试。无需单独的安全审查环节。无需等待扫描器追上上周就已交付的代码。

---

观看运行演示

📊 一页概览 — 介绍它是什么、有哪些不同之处以及如何部署。适合分享给技术负责人或架构评审委员会。

下载完整 PDF

观看演示 从设置到 CI 门禁，包含真实的终端输出和仪表板——一次展示并发运行 Builder 与 Breaker、HIPAA 领域测试，以及所有 IDE 集成。

---

为什么它在架构上与众不同

它有三项结构性特性，而非功能点——各项特性的设计依据详见深入了解：

1. 并发运行，而非依次执行。 Builder 和 Breaker 通过 asyncio.gather() 在同一时刻启动。Breaker 看不到生成的代码——它只根据规范进行推理，而真实攻击者在你的实现方案尚未存在之前，面对的也正是这层信息。
2. 原生 MCP 集成，双向协作。 GAUNTLEX 将自身作为 MCP 服务开放，让 Claude Code、Cursor、Windsurf 或 Zed 能够直接从你的编码工具触发并轮询运行；同时，它也会使用外部 MCP 服务（以及内置的 CISA KEV / NIST NVD 数据源），为每次运行补充实时威胁数据。关于哪些内容是实时数据、哪些是静态数据，请参阅领域情报页面。
3. 将监管领域作为一等输入。 FINRA、HIPAA、PCI DSS、SOC 2 和 OWASP Top 10 手册会引导 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 或门槛值等可调默认值的 .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（免费、本地运行）、OpenRouter 免费层级，或 Anthropic/OpenAI API 密钥

---

CLI 参考

全部 22 条命令，按使用场景分组：

入门
gauntlex setup	配置模型提供方和集成（可随时运行以重新配置）
gauntlex init	使用合理的默认值生成 .gauntlex.yml
gauntlex doctor	全面的环境健康检查
gauntlex validate	试运行——检查配置和连接，不会发起任何攻击

运行评估
gauntlex run	针对规格运行对抗式 Builder + Breaker
gauntlex status	显示正在运行和最近完成的运行
gauntlex findings	上次运行发现的漏洞——优先修复，最后评分
gauntlex compare	对比两份 Resilience 报告——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	列出、安装、搜索或验证策略领域——参见 Domain Intelligence

团队与 CI 部署
gauntlex integrate	一条命令：将 GAUNTLEX 接入 Claude Code、Cursor、Windsurf、Copilot、Codex、Zed、Antigravity 或 GitHub Actions
gauntlex mcp-server	将 GAUNTLEX 作为 MCP 服务启动（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 参考。

---

语言支持

根据规格自动检测——无需按项目进行配置：

语言	优先关注的 CWE（示例）
Python	SQL 注入、OS 命令注入、不安全反序列化、路径遍历
JavaScript / TypeScript	原型污染、XSS、CSRF、SSRF
Java	反序列化、XXE、授权绕过
Go	竞态条件、空指针解引用、资源耗尽

---

合规与领域覆盖

目前提供 5 种受监管行业的手册——共 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 已列入路线图 ——目前尚不可用。

关于当前提供的威胁数据与静态手册内容的具体区别，以及如何 添加自己的领域，请参阅完整的 Domain Intelligence 页面。

---

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

每个目标都会获得适用于该工具的正确文件、格式和架构——这条命令会处理这些差异，无需你操心；它会合并到已有配置中，而不是覆盖配置，因此你已配置的其他 MCP 服务也会保留。

Claude Code 用户也可以通过插件市场安装，而不必使用 integrate：

/plugin marketplace add sanjoy1234/gauntlex
/plugin install gauntlex@gauntlex

此操作会一步完成 MCP 服务注册，以及所有 /gauntlex:* 技能（run、verify、doctor、compare、report、learn、validate）的注册，并可通过 /plugin update 更新。要求 PATH 中包含 gauntlex（pip install gauntlex-ai）。

**零配置：**此仓库附带一个 AGENTS.md，Codex、Cursor、Cline、Windsurf 和 Gemini CLI 无需安装步骤即可自动读取——如果你是在 GAUNTLEX 的基础上进行开发，而不仅仅是使用它，可以将这种模式复制到自己的仓库中。

各平台的确切文件路径、合并安全保障，以及 GAUNTLEX 提供的 MCP 工具（gauntlex_run、gauntlex_status、gauntlex_verify 等）：集成指南。

---

企业级部署

• gauntlex dashboard — 查看所有已连接仓库的 ARS 趋势、门禁状态和攻击结果细分。团队共用一个 URL。
• gauntlex serve --rbac — 在共享实例中实施基于 GitHub 团队的访问控制（admin / reviewer / developer）。
• gauntlex audit — 在可配置的时间范围内列出每次运行，并映射到 NIST SSDF / OWASP SAMM / SOC 2 控制项。
• 气隙环境运行 — 完整引擎在本地 Ollama 上运行，不会发起任何出站调用，适用于无法连接互联网的环境。

各项功能的详细信息：深入解析 → 企业功能。

---

关键术语

• 对抗韧性评分（ARS） — 每次运行中所有攻击的单项得分均值（已缓解 = 1.0、部分缓解 = 0.5、未命中 = 0.0）。范围为 [0.0, 1.0]。这是 GAUNTLEX 生成的核心指标。
• 构建者（Builder） — 根据规格生成代码的 Agent。
• 攻击者（Breaker） — 在同一时刻根据同一规格生成对抗性攻击、且看不到构建者输出的 Agent。
• 并发协同生成 — Builder 和 Breaker 同时针对同一规格通过 asyncio.gather() 运行，而不是等代码编写完成后再进行测试。
• 韧性报告 — GAUNTLEX 运行生成的防篡改输出，其中包含针对有序攻击结果的 SHA-256 哈希，可通过 gauntlex verify 独立验证。
• 门禁 — 当某次运行的 ARS 低于配置阈值（默认值为 0.80）时，阻止合并的 CI 检查。

---

常见问题

如何测试 AI 生成的代码是否存在安全漏洞？ 让 GAUNTLEX 使用 AI 编码工具所用的同一份规范：gauntlex run --issue your_spec.md --mode quick。它会根据该规范发起对抗性攻击，并在不到一分钟内返回对抗韧性评分。

什么是对抗韧性评分（ARS）？ 它是某次运行中所有攻击的单项得分的平均值（已缓解 = 1.0，部分缓解 = 0.5，未拦截 = 0.0），是衡量生成代码抵御攻击能力的连续指标，范围为 [0.0, 1.0]，而非简单的通过／失败计数。完整公式和说明请参阅 ARS 说明。

GAUNTLEX 在代码生成前还是生成后进行测试？ 就在同一时刻。Breaker Agent 直接根据规范进行推理，与 Builder 并行工作——它不会等到代码生成后才开始，这就是“并行而非串行”在实践中的含义。

GAUNTLEX 支持哪些合规框架？ 开箱即支持 OWASP Top 10、HIPAA、FINRA、PCI DSS 和 SOC 2；NIST SSDF 和 OWASP API Security 则可通过可安装扩展使用。每个领域的具体覆盖范围请参阅领域智能。

GAUNTLEX 能否在不向外部 API 发送代码的情况下运行？ 可以——完整引擎可在本地 Ollama 上运行，不会发起任何出站调用，适用于气隙环境或受合规要求限制的环境。

更多问题，包括门控阈值和如何贡献新的策略领域，请参阅 Deep Dive 中的完整常见问题。

---

了解更多

• 深入指南 — 完整介绍：并行执行为何重要、GAUNTLEX 与 SAST／DAST／渗透测试的对比、完整的 CLI 和配置参考、架构、常见问题及路线图。
• 领域智能 — 各受监管领域的具体覆盖范围、实时与静态内容的区别，以及如何扩展。
• 贡献 — 如何添加策略领域、语言配置或功能。

---

在哪里找到 GAUNTLEX

软件包和注册表

• PyPI — pip install gauntlex-ai
• 官方 MCP Registry — 登记名称为 io.github.sanjoy1234/gauntlex

文章

• GAUNTLEX 运行 GAUNTLEX — 一份经过签名、可验证的自测报告，以及在一个真实规范上对并行与串行对抗性测试进行的正面对比测量
• dev.to — “为什么我构建了一个对抗性协同生成引擎”
• dev.to — “对抗韧性评分：衡量 AI 生成代码的新指标”
• dev.to — “GAUNTLEX 如何在 CI 中把关 HIPAA／FINRA 合规性”
• dev.to — “那个发放令牌却无人检查的登录端点”
• LinkedIn 文章 — “AI 编写百万行代码时，数学为何会失效”

社区

• GitHub Discussions — 提问、反馈，以及“我用这个做了 X”的成果展示

---

致谢

• Deven Samant — 早期反馈与验证

---