MikeHathaway/smart-contract-auditor

# codex-smart-contract-auditor `codex-smart-contract-auditor` 是一个可复用的 GitHub Actions 仓库，用于**针对 Pull Request 和分支快照进行最大深度、顺序执行的智能合约审计**。 它将两个必需的审计技能系列连接在一起： - Trail of Bits `building-secure-contracts`，特别是 `$secure-workflow-guide` - forefy `.context`，特别是 `$smart-contract-audit` 目标很简单：让一个 EVM 仓库放入**一个工作流文件**，并获得合并后的 Markdown 和 JSON 审计报告，以及一个可选的置顶 PR 摘要评论。 该可复用工作流同时支持 OpenAI 托管的 Responses 和 Venice 托管的 Responses。 ## 本仓库的功能 该可复用工作流： 1. 检出调用者仓库。 2. 安装确定性审计先决条件，例如 Slither。 3. 从其上游仓库的固定引用处安装外部技能包。 4. 通过仓库作用域的 `.agents/skills` 向 Codex 暴露选定的技能。 5. 构建运行时审计提示，包含审计模式、范围上下文、爆炸半径、入口点表面、代币表面和升级表面。 6. 运行**顺序** Codex 审计： - `$secure-workflow-guide` - `$smart-contract-audit` - 需要时确定性触发的辅助技能，例如 `$token-integration-analyzer`、`$entry-point-analyzer` 和 `$foundry-poc` - 合并的最终报告 7. 上传： - `audit-report.md` - `audit-report.json` - `.codex-smart-contract-auditor/preflight/` - `.context/outputs/` 8. 可选地更新置顶 PR 评论，包含严重性计数和 blocked-check 状态。 ## 为什么采用顺序执行 这个 v1 设计特意采用**仅顺序执行**。 对于智能合约审计来说，这是更好的可复用默认设置： - 一个共享的预检 - 一个确定性提示 - 更少的竞态条件 - 更简单的产物处理 - 更清晰的合并输出 - 当所需技能被阻止时，更容易调试 - 更好地保留原始审计证据 并行执行以后是可能的，但它增加了重复、合并复杂性，以及可复用工作流以嘈杂方式失败的更多途径。 ## 使用者设置 向你要审计的仓库添加一个工作流文件： ``` name: Smart Contract Audit on: pull_request: types: [opened, synchronize, reopened, ready_for_review] permissions: contents: read issues: write pull-requests: write jobs: audit: uses: MikeHathaway/smart-contract-auditor/.github/workflows/codex-smart-contract-audit.yml@main with: provider: auto audit-mode: pr model: "" effort: "" severity-threshold: medium fail-on-severity: high post-pr-comment: true pr-number: ${{ github.event.pull_request.number }} base-sha: ${{ github.event.pull_request.base.sha }} head-sha: ${{ github.event.pull_request.head.sha }} secrets: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} VENICE_API_KEY: ${{ secrets.VENICE_API_KEY }} ``` 即拿即用的使用者工作流： - 通用 provider 感知示例：[`.github/workflows/example-consumer.yml`](/home/mike/Projects-2026/smart-contract-auditor/.github/workflows/example-consumer.yml) - 仅 Venice 示例：[`.github/workflows/example-consumer-venice.yml`](/home/mike/Projects-2026/smart-contract-auditor/.github/workflows/example-consumer-venice.yml) - 手动分支快照示例：[`.github/workflows/example-consumer-manual-snapshot.yml`](/home/mike/Projects-2026/smart-contract-auditor/.github/workflows/example-consumer-manual-snapshot.yml) 如果你直接使用此仓库，请保持 `uses:` 目标指向 `MikeHathaway/smart-contract-auditor`。 如果你 fork 或重新发布此可复用工作流，还需要设置这些高级输入以匹配你的 fork 和引用： - `workflow-source-repository` - `workflow-source-ref` 这是必要的，因为可复用工作流在调用者仓库上下文中运行，所以辅助脚本必须显式地从工作流源仓库检出。 ## Provider Secrets - `OPENAI_API_KEY` 用于 OpenAI 托管的 Responses - `VENICE_API_KEY` 用于 Venice 托管的 Responses 默认情况下，将这些存储为 **GitHub Actions 仓库 secrets**： - 仓库：`Settings` -> `Secrets and variables` -> `Actions` -> `Repository secrets` 这是该工作流的预期默认设置。它不需要 GitHub Actions 环境。 这两个 secrets 都是可选的，以便工作流可以在像 fork 的 PR 这样的环境中优雅降级。如果选定的 provider key 不可用，它仍然会生成带有 `Blocked Checks` 部分的确定性产物，而不是静默失败。 如果选择了 `provider: venice` 且未设置 `VENICE_API_KEY`，工作流将回退到 `OPENAI_API_KEY` 作为兼容性逃生舱。如果你已经在旧的 secret 名称下存储了 Venice key，这很有用，但 `VENICE_API_KEY` 是更清晰的长期设置。 如果你想跨多个仓库共享一个 provider key，请使用组织 secret。仅当你有意想要环境级别的批准或作用域，并且也在调用者工作流中连接了 `environment:` 时，才使用环境 secret。 ## 快速设置指南 对于典型的 Venice 支持的 Pull Request 设置： 1. 在你要审计的仓库中，转到 `Settings` -> `Secrets and variables` -> `Actions`。 2. 在 `Repository secrets` 下，创建 `VENICE_API_KEY`。 3. 添加一个调用以下内容的工作流： `MikeHathaway/smart-contract-auditor/.github/workflows/codex-smart-contract-audit.yml@main` 4. 设置 `provider: venice`。 5. 如果你想要工作流的 Venice 默认值，请保留 `model: ""` 和 `effort: ""`。 6. 通过以下方式传递 secret： `VENICE_API_KEY: ${{ secrets.VENICE_API_KEY }}` 7. 打开或更新 Pull Request 以触发审计。 ## 所需权限 调用者工作流： - `contents: read` - `issues: write` 如果你想要置顶 PR 评论 - `pull-requests: write` 如果你想要置顶 PR 评论 审计作业本身仅使用 `contents: read`。PR 写入权限被隔离到单独的评论作业。 ## 输入 该可复用工作流支持以下输入： - `provider`：`auto`、`openai` 或 `venice`；默认为 `auto` - `audit-mode`：`pr` 或 `snapshot`；默认为 `pr` - `model`：可选的 Codex 模型覆盖 - `effort`：可选的 Codex 推理努力覆盖 - `responses-api-endpoint`：可选的 Responses API 端点覆盖 - `working-directory`：要优先考虑的仓库子目录 - `severity-threshold`：摘要强调阈值，默认为 `medium` - `fail-on-severity`：当存在等于或高于此严重性的发现时，使工作流失败 - `post-pr-comment`：启用或禁用置顶 PR 评论 - `extra-audit-instructions`：将额外的 markdown 指令附加到运行时提示 - `cost-profile`：`max`、`balanced` 或 `lean`；默认为 `balanced` - `enable-tiny-auditor`：运行可选的最终关键损失扫描；默认为 `false` - `base-sha`：可选的显式 base SHA，主要用于 `audit-mode: pr` - `head-sha`：可选的显式 head SHA - `pr-number`：可选的显式 pull request 编号，主要用于 `audit-mode: pr` - `workflow-source-repository`：从何处检出辅助脚本的高级覆盖；默认为 `MikeHathaway/smart-contract-auditor` - `workflow-source-ref`：从哪个引用检出辅助脚本的高级覆盖；默认为 `main` Provider 默认值特意是不对称的： - `provider: auto` 当 `OPENAI_API_KEY` 和 `VENICE_API_KEY` 都存在时优先选择 OpenAI - OpenAI：如果 `model` 和 `effort` 为空，该 action 使用 Codex 默认值 - Venice：如果 `model` 为空，工作流使用 `openai-gpt-54` - Venice：如果 `effort` 为空，工作流使用 `high` - Venice：如果 `responses-api-endpoint` 为空，工作流使用 `https://api.venice.ai/api/v1/responses` 这保持了 OpenAI 行为更清晰，同时使 Venice 足够确定性以便与 `openai/codex-action` 一起使用，但对于完整的 Codex `workspace-write` 行为，Venice 仍应被视为尽力而为。 成本默认值特意是保守的： - `cost-profile: balanced` 是默认值 - `enable-tiny-auditor: false` 是默认值 这保持了两个必需的核心技能到位，同时避免在每次运行时进行最昂贵的可选扫描。 ## 工作流内部 该可复用工作流仍然暴露一个公共入口点，但最大的实现部分现在位于仓库本地辅助脚本中以便于维护： - `scripts/run-preflight.sh` - `scripts/validate-audit-outputs.sh` - `scripts/upsert-pr-comment.cjs` 这使得 provider 选择、预检逻辑、回退产物生成和置顶评论行为更容易审查和更改，而无需进一步增加工作流 YAML。 ## 分支快照模式 该可复用工作流现在支持一流的快照模式： - `audit-mode: pr` - 优先差异的 Pull Request 审查 - 可用时使用 PR 上下文 - PR 评论在这里很有意义 - `audit-mode: snapshot` - 完整的检出分支审计 - 不假设 PR 上下文 - 最适合手动 `main` 或 release-branch 审计 在快照模式下，工作流将整个检出树视为范围内，而不是假装有有意义的 PR 差异。 在 [`.github/workflows/example-consumer-manual-snapshot.yml`](/home/mike/Projects-2026/smart-contract-auditor/.github/workflows/example-consumer-manual-snapshot.yml) 中有一个即拿即用的手动快照示例。 要审计特定的分支快照，请在 GitHub Actions "Run workflow" 分支选择器中选择该分支，或者使用 CLI 通过 `gh workflow run ... --ref ` 运行工作流。 ## Venice 设置 要强制将 Venice 作为后备 Responses provider： ``` jobs: audit: uses: MikeHathaway/smart-contract-auditor/.github/workflows/codex-smart-contract-audit.yml@main with: provider: venice audit-mode: pr model: "" effort: "" secrets: VENICE_API_KEY: ${{ secrets.VENICE_API_KEY }} ``` 使用这些设置，工作流会自动解析这些 Venice 默认值： - endpoint：`https://api.venice.ai/api/v1/responses` - model：`openai-gpt-54` - effort：`high` 如果你需要不同的 Venice 模型或端点，请显式传递 `model` 或 `responses-api-endpoint`。 如果配置了两个 provider secrets 并且你仍然想要 Venice，请显式设置 `provider: venice`。 工作流现在还假设 Venice 有时可能返回成功的 Responses 完成而不创建预期的仓库文件。为了处理这种情况，提示需要标记的最终消息回退块，并且工作流将在可能时从最终消息中恢复 `audit-report.md` 和 `audit-report.json`。 在 [`.github/workflows/example-consumer-venice.yml`](/home/mike/Projects-2026/smart-contract-auditor/.github/workflows/example-consumer-venice.yml) 中还有一个专门的复制粘贴 Venice 使用者工作流。 ## 证据产物 此仓库现在保留的不仅仅是合并摘要。 上传的产物包括： - `audit-report.md` - `audit-report.json` - `.codex-smart-contract-auditor/preflight/` 用于确定性预检证据 - `.context/outputs/` 用于原始 forefy 输出目录 这很重要，因为上游 forefy 框架期望持久的编号审计输出，并且当保留生成的摘要和图表而不是被转述时，Trail of Bits 工作流会明显更强。 ## 报告包含的内容 `audit-report.md` 包含合并的人类可读报告，包含以下部分： 1. Executive Summary 2. Scope 3. PR / Diff Context or Snapshot Context 4. Blast Radius 5. Skills / Checks Run 6. Findings Table 7. Detailed Findings 8. Attack Paths / PoC Notes 9. Security Properties to Add 10. Tests / Verification Gaps 11. Blocked Checks 12. Recommended Next Actions `audit-report.json` 包含一个确定性的机器可读摘要，适用于： - 基于 Codex 的审查者工具 - 未来的 Claude 审查者集成 - 后处理管道 - 仪表盘和策略门控 JSON 包括： - 严重性计数 - 审计模式 - 已更改和已审查的范围 - 运行的检查 - 带有源技能的发现 - 分类器状态和产物路径（如果可用） - 要添加的安全属性 - 被阻止的检查 ## 如何集成技能包 ### Trail of Bits 此仓库在固定引用处安装 `trailofbits/skills`，并通过 `.agents/skills` 暴露选定的智能合约技能，包括： - `secure-workflow-guide` - `token-integration-analyzer` - `entry-point-analyzer` - `guidelines-advisor` 提示明确要求运行 `$secure-workflow-guide`，并明确要求合并报告涵盖其 5 步工作流： - 已知问题扫描 - 特殊功能检查 - 目视检查 - 安全属性 - 手动审查区域 ### forefy 此仓库在固定引用处安装 `forefy/.context` 并暴露这些仓库作用域技能： - `smart-contract-audit` - `foundry-poc` - `tiny-auditor` 提示明确要求 `$smart-contract-audit` 并要求 forefy 风格的输出： - 已分类的发现 - 多专家分析 - 分类器验证 - 漏洞路径推理 - 攻击路径 / 调用流分析 - 实用的现实 PoC 注释 - 修复指导 它还保留原始编号的 `.context/outputs/X/` 审计跟踪，而不是仅用顶级摘要替换它。 ## 确定性辅助技能触发 辅助技能行为现在取决于运行时成本配置文件： - `cost-profile: max`倾向于最大的辅助技能深度 - `cost-profile: balanced` 仅在辅助技能增加超出确定性预检产物的信号时才运行 - `cost-profile: lean` 最小化辅助技能的使用，除非它们实质性地提高发现质量 主要的辅助触发器是： - 与代币相关的爆炸半径 -> 当它增加超出预检产物的信号时触发 `token-integration-analyzer` - 已更改的外部、管理员、治理或升级表面 -> 当它增加超出预检产物的信号时触发 `entry-point-analyzer` - 合理的高严重性漏洞加上 Foundry 可用性 -> `foundry-poc` - 可选的最终可处理损失扫描 -> 仅当 `enable-tiny-auditor: true` 时触发 `tiny-auditor` ## 技能安装如何工作 `install-skills.sh` 克隆上游技能仓库，然后将选定的技能目录符号链接到调用者仓库的 `.agents/skills` 文件夹。 这很重要，因为 Codex 官方从工作树中的 `.agents/skills` 发现仓库作用域技能。 安装程序是： - 幂等的 - 模块化的 - 易于扩展 - 固定到具体的上游引用 要稍后添加另一个技能包，只需更新： - [`install-skills.sh`](/home/mike/Projects-2026/smart-contract-auditor/install-skills.sh) - [`audit-prompt.md`](/home/mike/Projects-2026/smart-contract-auditor/audit-prompt.md) ## 置顶 PR 评论行为 当 `post-pr-comment` 为 `true` 时，工作流会保持一个由以下内容标识的置顶评论： ``` ``` 评论包括： - 整体状态 - 严重性计数 - 被阻止的检查计数 - 产物名称 详细的 markdown 和 JSON 报告保留在工作流产物中，而不是刷屏 PR 线程。 ## 安全说明 此工作流主要设计用于不受信任的 Pull Request，但相同的信任模型对于手动分支快照审计也很重要。 此处包含的安全默认设置： - 使用者示例使用 `pull_request`，而不是 `pull_request_target` - checkout 使用 `persist-credentials: false` - 审计作业仅使用 `contents: read` - PR 写入权限被隔离到评论作业 - Codex 使用 `safety-strategy: drop-sudo` 运行 - Codex 使用 `sandbox: workspace-write` 运行 - 不请求额外的仓库写入权限 - 在模型运行之前生成确定性预检产物 额外的面向严谨性的设置： - 安装 `graphviz`，以便 Trail of Bits 视觉输出不太可能被阻止 - 当检测到 `foundry.toml` 仓库时，使用官方 `foundry-rs/foundry-toolchain` action 安装 Foundry - 在模型启动之前运行尽力而为的预检 Slither 摘要 同样重要的是： - 不要在未经清理的情况下将原始的不受信任的 PR 描述或 issue 正文输入到提示中 - 保持 provider API keys 作用于可复用工作流调用 - 请记住，在某些仓库中预期会出现被阻止的检查，特别是当 Slither 或更深入的静态分析无法在没有额外项目设置的情况下干净运行时 ## 限制 - 此仓库在 v1 中**不**尝试并行多代理执行。 - 它故意避免使用未记录的 `openai/codex-action@v1` 输入。 - 智能合约仓库差异很大。某些检查仍会在编译器或依赖项布局上被阻止。发生这种情况时，工作流会报告阻止，而不是假装检查已运行。 - 对于 fork 的 PR，GitHub 经常扣留 secrets。在这种情况下，你仍然会获得产物，但报告将显示 Codex 执行被阻止。 - Venice 支持取决于 Venice 继续接受 Codex 兼容的 Responses API 载荷。工作流现在直接针对 Venice 的 `/api/v1/responses` 端点，但特定于 provider 的载荷差异仍可能影响行为。 - 如果你需要实质性地降低 token 使用量，最大的杠杆是 `cost-profile: lean` 并将 provider `effort` 从 `high` 降低到 `medium`。 ## 兼容性 该仓库的构建使得输出可以在 Codex 之外重用： - 提示主要是审查者无关的 markdown - 工作流将编排与提示内容分离 - 安装程序独立于报告格式 - 最终 JSON 足够确定性，可用于未来的 Claude 或其他审查者工具 ## 上游技能许可 此仓库**不**将第三方技能内容引入仓库树。 相反，它在运行时从上游源安装它们： - Trail of Bits 技能保留其上游许可和历史 - forefy `.context` 保留其上游许可和历史 在固定或重新分发修改版本之前，请查看这些上游仓库。

标签：AI审计, Codex, Cutter, DevSecOps, EVM, Foundry, GitHub Actions, MITM代理, OpenAI, Petitpotam, POC验证, Pull Request, Slither, Trail of Bits, Venice, 上游代理, 云安全监控, 代码审查, 以太坊, 内存规避, 区块链, 智能合约, 消息认证码, 网络调试, 自动化, 自动笔记, 静态分析