heavenlost/contract-guard

# Contract Guard CI 面向 Foundry 项目的开源智能合约安全 CI。 `contract-guard-ci` 是一个小型、对自动化友好的 EVM 团队安全工作流。它优先封装确定性工具——Foundry、Slither，以及后续的 Echidna/Medusa——并且仅在分类/解释时使用 AI，从不将其作为唯一的真实来源。 ## 产品立场 - **要做：** PR 级别的智能合约安全检查、差异感知报告、SARIF/JSON/Markdown 输出、团队策略基线。 - **不要做：** 声称取代人工审计、持有用户资金、运行支付基础设施、托管密钥或执行法律/合规决策。 - **首批客户：** 使用 Foundry 且需要持续的预审计安全检查的小型 EVM 协议团队。 ## MVP 形态 1. CLI 探测仓库/工具就绪状态。 2. GitHub Action 在 Pull Request 上运行。 3. Foundry 测试和 Slither 静态分析被标准化为一份报告。 4. 建议性不变量模板可帮助团队开始 Foundry 不变量测试，而无需声明审计的完整性。 5. 仅包含脚手架的 Echidna/Medusa 钩子定义了本地模糊测试命令，默认不执行外部模糊测试器。 6. 误报审查记录生成可审计的非高危基线候选。 7. 本地仓库策略文件定义了确定性扫描默认值，不启用私有上传或 AI 分类。 8. 可选的 AI 分类 payload 从确定性脱敏开始，默认从不调用外部 AI。 9. 未来计划：PR 评论、AI 辅助分类、实时模糊测试执行、付费团队仪表板。 ## 快速开始 ``` python3 -m venv .venv . .venv/bin/activate pip install -e . contract-guard plan --repo . --json ``` 运行本地冒烟测试： ``` ./scripts/contract_guard.sh smoke ``` ## 设计合作伙伴反馈 如果您维护或审查 Foundry/EVM 代码库，欢迎在公开的设计合作伙伴 issue 中提供反馈：。 请从 `docs/design-partner-feedback.md` 开始，了解安全的试用命令以及哪些内容不应公开分享。请勿发布私有源码片段、机密信息、原始的私有仓库日志，或关于第三方仓库的漏洞声明。 ## 公开测试版路径 对于公开、安全的本地 Beta 流程： 1. 使用 `docs/beta-install.md` 进行本地安装、空运行扫描、GitHub Actions 输出、基线/策略设置以及 beta 限制说明。 2. 在尝试真实的 Foundry 仓库之前，先运行 `docs/dogfood-readiness.md` 中的本地固定测试包。 3. 使用 `docs/demo-case-study.md` 查看公开的 DeFi 金库演示和开发者会议叙述。 4. 使用 `docs/public-foundry-dogfood-candidates.md` 选择一个公开只读的内部测试仓库。 5. 使用 `docs/aderyn-integration-feasibility.md` 查看可选的 `contract-guard scan --include-aderyn` 分析器路径；默认扫描仍不会启用额外的分析器。 6. 使用 `docs/beta-design-partner-checklist.md` 了解更广泛的合作伙伴契合度、入门命令、权限边界和反馈信号。 7. 将 `docs/commercial-boundary.md` 作为任何托管仪表板、自托管运行器、定价或付费 Beta 讨论的边界。 Beta 路径始终保持本地运行器优先：默认不进行托管上传、不共享私有片段、不进行实时 AI 提供商调用、不涉及支付/托管范围，也不声称审计完整性。 ## 预审计证据包 在审计、发布、升级或有风险的 Pull Request 之前，生成本地优先的证据包： ``` contract-guard evidence-pack \ --repo . \ --output-dir /tmp/contract_guard_evidence_pack \ --repo-label your-repo-label \ --format markdown ``` 该证据包会在本地写入 Markdown/JSON/SARIF 产物，并将确定性工具输出保留为真实来源。默认情况下，它不需要托管私有代码上传、不发送私有片段、在公开摘要中不包含原始的 stdout/stderr、不进行实时 AI 提供商调用，也不做任何审计/合规/保证声明。 请参阅 `docs/pre-audit-evidence-pack.md` 获取公开的证据包演练，以及 `docs/ci-supply-chain-safety.md` 了解本地工作流安全检查器。 ## PR 扫描输出 运行确定性的本地扫描： ``` contract-guard scan --repo . --format json contract-guard scan --repo . --format markdown contract-guard scan --repo . --format sarif ``` 对于 Pull Request 样式的范围限定，请使用仅限更改模式： ``` contract-guard scan \ --repo . \ --changed-only \ --diff-base origin/main...HEAD \ --format markdown ``` GitHub Action 会在 `contract-guard-reports/` 目录下写入三个确定性输出： - `scan.json` — 经过策略控制的机器报告。 - `scan.md` — PR 评论样式的确定性证据，不含原始 stdout/stderr。 - `scan.sarif` — 用于 GitHub 代码扫描上传。 这些输出中故意未包含 AI 分类。确定性工具证据与任何未来的建议性解释层保持分离。 ## 基线与失败策略 基线抑制是可选且显式的： ``` cp .contract-guard-baseline.example.json .contract-guard-baseline.json contract-guard scan --repo . --baseline-file .contract-guard-baseline.json ``` 规则： - 基线通过确切的发现 `id`，或确切的 `check` + `file` + `start_line` 进行匹配。 - 只有非高危的 Slither 发现才能被抑制。 - 高危发现永远不会被基线抑制，即使已被列出。 - 被抑制的发现会单独保留在机器报告中；它们不会被删除。 默认的 CI 策略在遇到置信度为低或更好的活跃高危 Slither 发现时会失败： ``` contract-guard scan \ --repo . \ --changed-only \ --baseline-file .contract-guard-baseline.json \ --fail-on-severity high \ --fail-on-confidence low ``` 仅在生成非门控产物（例如在策略控制的 JSON 扫描已捕获退出状态之后的 Markdown 或 SARIF）时，才使用 `--fail-on-severity none`。 ## 建议性不变量模板 生成确定性的 Foundry 不变量起点： ``` contract-guard invariants --profile erc20 --contract Token --format markdown contract-guard invariants --profile vault --contract Vault --format json contract-guard invariants --profile access-control --contract Governor ``` 配置文件目前涵盖常见的 ERC20 会计核算、Vault/ERC4626 样式的会计核算，以及访问控制/暂停状态检查。这些模板仅作为建议性的起点：它们不是证明、审计或保证，每个代码片段都必须根据协议实际的处理程序、角色、资产和预期的边缘情况进行调整。 ## 模糊测试钩子脚手架 生成本地运行器的模糊测试命令脚手架，而不执行 Echidna 或 Medusa： ``` contract-guard fuzz-hooks --tool all --target test/invariants/InvariantTest.sol --contract InvariantTest contract-guard fuzz-hooks --tool echidna --target test/invariants/TokenInvariant.t.sol --contract TokenInvariant --format json contract-guard fuzz-hooks --tool medusa --target test/invariants/VaultInvariant.t.sol --contract VaultInvariant ``` 这些钩子仅是确定性脚手架。在启用实时执行之前，请固定模糊测试器版本，根据该版本审查生成的命令/配置，并将模糊测试器输出与可选的 AI 解释保持分离。模糊测试钩子不是安全性的证明、审计或保证。 ## 误报工作流 为非高危发现生成可审计的基线候选： ``` contract-guard false-positive \ --id slither:unchecked-transfer:contracts/Token.sol:7 \ --check unchecked-transfer \ --file contracts/Token.sol \ --start-line 7 \ --severity medium \ --confidence high \ --reason "Known safe return-value wrapper in SafeERC20 adapter." \ --reviewer security-team \ --expires 2026-12-31 \ --format json ``` 该命令不会编辑基线文件。它会发出确定性的审查记录，并且仅针对带有必需审查元数据的非高危发现，提供一个可复制的 `baseline_candidate`。高危发现总是返回 `blocked_high_severity` 且不提供基线候选，从而维护了使新的高风险问题保持可见的 CI 规则。 ## 仓库策略文件 验证本地项目默认值： ``` cp .contract-guard-policy.example.json .contract-guard-policy.json contract-guard policy --repo . --policy-file .contract-guard-policy.json --format markdown ``` 策略文件目前涵盖扫描默认值（`changed_only`、`diff_base`、基线路径、失败阈值）、报告格式、仅含脚手架的模糊测试钩子首选项以及安全边界。规范化后的策略始终保持默认禁用 AI 分类、禁用私有片段上传、禁用托管上传，并将原始 stdout/stderr 排除在报告之外。 ## 可选的 AI 分类隐私边界 构建本地、脱敏的建议性 payload，无需调用外部 AI： ``` contract-guard ai-triage-payload \ --check reentrancy-eth \ --file contracts/Vault.sol \ --start-line 42 \ --severity high \ --confidence medium \ --description "Vault withdraw sends before state update." \ --format markdown ``` 代码片段文本默认会被丢弃。如果团队明确要求包含上下文，`--include-redacted-snippet` 仅发出确定性的脱敏片段，并且仍然报告 `send_private_snippets=false` 和 `external_ai_call_made=false`。确定性分析器证据与任何未来的建议性 AI 解释保持分离。 从相同的脱敏 payload 结构生成本地建议性解释脚手架： ``` contract-guard ai-triage-explain \ --check reentrancy-eth \ --file contracts/Vault.sol \ --start-line 42 \ --severity high \ --confidence medium \ --description "Vault withdraw sends before state update." ``` 此解释脚手架不是确定性证据，不是证明，不是审计，也不是保证。它是一个用于审查问题和测试建议的本地模板；未来的实时 AI 提供商集成必须保持相同的证据/建议分离。 在任何实时集成存在之前验证提供商的选择加入边界： ``` contract-guard ai-triage-config --format markdown contract-guard ai-triage-config \ --provider openai \ --enable-external-provider \ --include-redacted-snippets \ --format json ``` 即使在显式的选择加入结构中，此命令也不会进行外部 AI 调用，并报告 `private_code_leaves_local_runner=false`、`send_private_snippets=false` 和 `hosted_uploads_enabled=false`。私有片段和托管上传是被阻止的，而不仅仅是按照惯例关闭。 渲染带有严格部分分隔的组合分类报告： ``` contract-guard ai-triage-combined \ --check reentrancy-eth \ --file contracts/Vault.sol \ --start-line 42 \ --severity high \ --confidence medium \ --description "Vault withdraw sends before state update." ``` 组合报告始终在 `Advisory AI text (separate, non-gating)` 之前渲染 `Deterministic evidence (source of truth)`。AI 文本不能抑制发现或替代确定性工具证据。

标签：AI辅助分析, CI, DevSecOps, EVM, Foundry, GitHub Actions, SARIF, Slither, Web3安全, 上游代理, 以太坊, 区块链安全, 开源安全工具, 开源框架, 持续集成, 智能合约安全, 本地优先, 自动笔记, 逆向工具, 逆向工程平台, 错误基检测, 静态代码分析