使用 Iron Laws 审查并改进 AI 生成的代码

什么是 Iron Laws？

Iron Laws，也称为 오철칙，是一款静态检查工具，旨在发现 AI 生成项目中常见的安全性和可维护性问题。它借鉴企业和公共部门系统集成审计中的经验，并以易于理解的语言解释每项发现。

该工具关注的不只是应用能否运行。它还会检查硬编码密钥、不安全的输入处理、被吞掉的异常、未经身份验证的管理 API、缺少 Supabase 或 Firebase 访问控制、已提交的 .env 文件、重复函数、循环依赖以及绕过类型安全检查等问题。

Iron Laws 还会生成结构化的修复指令，可直接粘贴到 AI 编程助手中。这就形成了可重复的工作流程：

使用 AI 构建 → iron-laws check → iron-laws fix-prompt
→ 请求 AI 修复发现的问题 → 再次运行 check

Iron Laws 是开发阶段的审查辅助工具，不是官方认证产品，也不能证明应用是安全的。请将它与测试、代码审查及其他安全工具结合使用。

主要功能

安全性与质量检查

该项目包含涵盖多个领域的 90 条规则：

• 参考规则：覆盖所参考的韩国行政安全部软件开发安全指南中全部 49 项实施阶段条目，包括注入、XSS、SSRF、XXE、弱加密、禁用证书验证、不安全反序列化、错误处理和内存安全。
• AI 代码修正：硬编码配置、密钥回退值、前端密钥泄露、不安全的 CORS、缺失的访问规则、危险的 Docker 或 CI 设置、依赖项拼写错误、未锁定版本的依赖项、敏感日志、IDOR 以及 Cookie 属性问题。
• 架构检查：过大的函数和文件、不当的层间依赖、请求处理程序直接访问数据库、循环依赖、重复函数、重复的字符串常量以及缺少测试。
• 类型安全检查：TypeScript 的 any 和 @ts-ignore、Python 的 type: ignore 和类型转换、Java 原始类型、C# 的 dynamic，以及其他受支持语言中的类型系统绕过。

易读的问题发现与修复指导

每项发现都包含问题说明、风险原因以及修复方法。对于对应已发布指南条目的规则，报告会包含该条目编号及其 CWE 映射。项目专属的质量规则会明确标记为 Iron Laws 规则，而不是外部要求。

适用于 AI 的修复提示

fix-prompt 命令会按严重性整理发现，并将其转换为供 AI 编程工具使用的指令。提示还会强调一些原则，例如不要吞掉错误、不要将密钥放入源代码、不要绕过类型检查，以及不要创建重复实现。

本地解析

软件包中包含所需的解析器，因此安装后无需网络访问即可运行检查。

语言与文件支持

不同语言和文件类型的支持深度有所不同：

• 深度支持：Python、JavaScript、TypeScript、Java 和 C# 支持语法分析、输入跟踪以及最广泛的规则覆盖。
• 基础支持：Go 和 PHP 支持语法分析，以及重要的注入、错误处理和加密检查。
• 有限支持：Rust 和 C/C++ 支持错误处理、内存使用、格式字符串、API 和类型绕过检查。
• 配置与定义文件：SQL、YAML、JSON、.env、Dockerfile、Compose、GitHub Actions、MyBatis XML 和 HTML 模板会针对相关的密钥、访问控制、部署和转义问题进行检查。

在函数内部，Iron Laws 会分析分支、循环和异常中的流程。它会跟踪同一文件中的辅助函数调用，最多深入四层。Python 还支持通过导入进行实验性的跨文件跟踪，但受分析限制约束。其他语言中的跨文件流程可能会被遗漏，或被报告为需要审查。

安装

Iron Laws 要求 Python 3.12 或更高版本。推荐使用 uv 将其作为独立工具安装：

uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git

也可以使用 pip 安装：

pip install git+https://github.com/JinHo-von-Choi/iron-laws.git

安装后，通过列出已打包的规则确认命令可用：

iron-laws rules

如需查看各语言和规则的实现及验证状态，请运行：

iron-laws support

这一点很重要，因为存在解析器并不一定意味着每条规则都已针对该语言完成验证。

运行首次检查

扫描当前项目

在项目目录中打开终端并运行：

iron-laws check .

默认情况下，当命令发现严重性达到 HIGH 或更高的问题时会失败。退出代码如下：

• 0：检查在所选严重性策略下通过。
• 1：至少有一项发现达到或超过配置的失败严重性。
• 2：输入或配置无效、未检查任何文件，或由于规则错误、文件读取失败等问题导致检查无法完成。

未完成的检查不会获得已确认的评级或通过结果。其原因会记录在 diagnostics 下。除非明确提供 --allow-empty，否则空目标也不会被视为扫描成功。

了解单条规则

需要以通俗语言了解规则时，请使用 explain：

iron-laws explain IL-501

你还可以查看 49 个被引用的实现项目中哪些已覆盖：

iron-laws coverage

生成报告

要生成一份包含全部 49 个被引用项目检查状态的 Markdown 报告，请运行：

iron-laws audit . --format markdown -o report.md

要生成供 GitHub Code Scanning 或其他兼容系统使用的 SARIF 文件，请使用：

iron-laws audit . --format sarif -o iron-laws.sarif

为 AI 编程助手生成指令

查看检查结果后，生成适用于 AI 的修复提示：

iron-laws fix-prompt .

将生成的指令粘贴到你的编程助手中，检查其建议的更改，然后再次运行检查：

iron-laws check .

即使存在检查结果，fix-prompt 命令也会返回退出代码 0，因为它的用途是生成指令。不要将它用作部署门禁。请使用 check 或 audit 进行强制检查。

报告和生成的提示中会将已识别的机密值屏蔽为 ****。但是，无法自动屏蔽未识别的机密，因此在将生成的文本发送给外部 AI 服务前，请先进行检查。

配置项目策略

使用以下命令生成初始配置文件：

iron-laws init

项目使用 .iron-laws.yml。典型配置如下：

fail_on: HIGH
excludes: [".git", "node_modules", "dist"]
disabled_rules: ["ARC-206"]
limits:
  max_function_lines: 80
  max_file_lines: 600
  max_parameters: 7
  max_nesting: 5
  duplicate_similarity: 0.9

fail_on 设置接受 CRITICAL、HIGH、MEDIUM 或 LOW。实际优先级依次为 --fail-on 命令行选项、配置文件，以及默认值 HIGH。报告会记录当前阈值由哪个来源提供。

默认情况下，Iron Laws 使用被检查目录中的配置。使用 --config 可选择特定文件，或使用 --search-parents 在父目录中查找。未知键和无效设置不会被静默忽略，而是会产生退出代码 2。

处理有意例外

只有包含原因时，才能抑制误报或有意例外。不包含原因的注释会被忽略。

在 Python 中抑制单条检查结果：

except ImportError:  # iron-laws: ignore[IL-301] Optional dependency disables this feature
    yaml = None

要抑制整个文件中的某条规则，请在前 30 行内放置 ignore-file 指令：

# iron-laws: ignore-file[IL-102] Pattern definitions intentionally identify weak algorithms

抑制指令可以包含到期日期：

# iron-laws: ignore[IL-101] until=2026-12-31 Temporary exception with documented reason

到期的抑制将不再生效，并会出现在报告中。Iron Laws 还会报告未使用的抑制指令，以及对未知规则 ID 的引用。

在现有项目中采用 Iron Laws

创建基线

如果现有代码库已经存在已接受的检查结果，请将其记录为已批准的技术债务：

iron-laws baseline create .

然后仅针对保存的基线中未包含的新检查结果进行评估：

iron-laws check . --baseline .iron-laws-baseline.json

检查发生更改的文件

要针对修改过的文件提供拉取请求反馈，请与主分支进行比较：

iron-laws check . --changed-since origin/main

README 建议将变更文件检查与完整扫描和定期扫描结合使用，以免遗漏整个代码库范围内的问题。

记录审查反馈

标记为需要审查的检查结果可以进行分类，并分配审查成本：

iron-laws feedback add IL-501 src/a.py:3 --verdict false-positive --minutes 10

验证 AI 生成的补丁

Iron Laws 包含一种高级工作流，用于保留 AI 修改代码后哪些内容已验证、哪些内容未验证的证据。

检查证据契约

证据契约用于区分已完成的扫描与实际生成了所需证据的扫描：

iron-laws check . --contract .iron-laws-contract.yml

未解决的输入源不会自动转换为干净结果。目前证据契约覆盖 Python 命令执行、路径访问和 SQL 构造系列。

创建补丁验证回执

要检查提议的补丁并保存验证回执，请运行类似以下的命令：

iron-laws verify-patch . --patch fix.diff \
  --finding IL-504@app.py:6 \
  --runner docker \
  --image IMAGE_NAME \
  -o receipt.json

验证器使用相同策略比较原始版本和候选版本。它会单独报告可疑更改，例如删除测试、增加跳过项、新增忽略注释或弱化策略。警告消失本身并不被视为修复有效的证明。

测试仅在不含凭据的一次性隔离环境中运行。如果无法获得隔离环境，Iron Laws 不会悄悄在主机上执行测试，而是将结果保留为不确定。

提出可区分的回归测试

你可以针对某项发现生成候选回归测试规范：

iron-laws regression propose . --finding IL-504@app.py -o spec.yml

预期的验证模式是：原始版本因缺陷而失败，候选版本通过，而将修复回退后的变异版本再次失败。README 描述了重复这一序列三次。生成的测试在确认前仍只是提案。

记录人工批准

连同批准理由一起存储：

iron-laws approvals add . \
  --finding IL-504@app.py \
  --reason "Documented review reason" \
  --store approvals.jsonl

扫描时应用有效批准：

iron-laws check . --approvals approvals.jsonl

批准仅在其假设仍然成立期间有效。调用方、数据流、清理器、访问范围或规则含义发生变化时，可能需要重新审核。重复的易受攻击代码不会继承现有批准。

与 GitHub Actions 集成

以下工作流会安装 Iron Laws、上传 SARIF 报告，然后执行高严重性部署门禁：

name: Iron Laws
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git
      - run: iron-laws audit . --format sarif -o iron-laws.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: iron-laws.sarif
      - run: iron-laws check . --fail-on HIGH

报告生成步骤使用 || true，因此即使存在发现，SARIF 文件仍可以上传。最后的 check 命令才提供实际的通过或失败门禁。

实际限制

• 干净结果表示在已实现的规则和受支持的分析范围内未发现问题，并不证明应用不存在漏洞。
• 跨文件输入跟踪对 Python 仍处于实验阶段，对其他语言的支持有限。某些数据流可能被遗漏，或被报告为需要人工审核。
• 清理器仅针对其保护的上下文进行识别，例如 HTML、SQL、Shell 命令或路径。
• 根据 README，补丁验证、回归测试和批准跟踪尚未经过独立评估或真实世界试点。
• 项目引用的 OWASP Benchmark 结果显示多个类别有所改善，但误报仍然存在，包括已安全清理的 SQL 和命令注入案例。
• 如果不查询软件包仓库，该工具无法可靠识别每一个伪造依赖项，而是会报告名称看起来像热门软件包的依赖项。
• 压缩文件和生成文件会被跳过，原因记录在 skipped_files 下。

如需更多详情，请查阅仓库文档中的补丁验证、准确性测量、语言和规则支持以及报告格式。

结论

Iron Laws 提供了一种结构化方式，用于在 AI 生成的软件中的隐蔽安全和维护问题演变为生产事故之前进行审查。请从 iron-laws check . 开始，检查说明，生成修复提示词，审核 AI 的更改，然后再次扫描。随着项目日趋成熟，可以添加配置、基线、SARIF 报告、补丁凭据和人工批准，使流程具备可重复性和可审计性。

该项目采用 MIT 许可证。其结果应当用于支持测试、人工代码审查和更广泛的安全评估，而不是取代它们。