shawalkhalid667/chainSentinel

# 智能合约审计流水线 # 本 README 并非仅由我编写，其结构和内容等由 LLM 辅助生成。 ``` contracts/ ← drop your .sol files here │ ├── SlitherAgent ← subprocess wrapper → normalised findings ├── MythrilAgent ← subprocess wrapper → normalised findings │ ├── Normalizer ← maps raw JSON → FindingSchema ├── Merge/Dedup ← fingerprint-based cross-tool deduplication ├── SARIF Export ← industry-standard output for VS Code viewer │ └── reports/ ← generated .sarif + .json files ``` ``` # Clone 并在 VS Code 中打开 git clone https://github.com/crytic/not-so-smart-contracts cd smart-contract-auditor code . # 创建 virtual environment python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 安装依赖 pip install -r requirements.txt # 安装 solc（live runs 必需） pip install solc-select solc-select install 0.4.15 solc-select use 0.4.15 ``` ## 在 VS Code 中运行 ### 选项 A — 运行任务（最简单） - 按 `Ctrl+Shift+B`（Mac 上按 `Cmd+Shift+B`） - 选择 **"Audit: All Contracts"** - 输出将显示在终端面板中 ### 选项 B — 调试 / F5 - 打开 `Run and Debug` 面板（`Ctrl+Shift+D`） - 从下拉菜单中选择 **"Audit: All Contracts"** - 按 **F5** —— 您可以在任意位置设置断点 ### 选项 C —— 审计当前编辑的文件 - 打开任意 `.sol` 文件 - 按 `Ctrl+Shift+B` → **"Audit: Current File"** ### 选项 D —— 终端 ``` python -m pipeline.auditor contracts/Reentrancy.sol python -m pipeline.auditor contracts/ ``` ## 在 VS Code 中查看 SARIF 结果 1. 安装 **SARIF Viewer** 扩展（它位于 `.vscode/extensions.json` 中，VS Code 会提示您安装） 2. 运行结束后，打开 `reports/*.sarif` 中的任意文件 3. VS Code 将直接在您的 `.sol` 文件中显示内联注解 ## 项目结构 ``` smart-contract-auditor/ ├── .vscode/ │ ├── tasks.json ← Ctrl+Shift+B tasks │ ├── launch.json ← F5 debug configs │ ├── settings.json ← Python path, SARIF association │ └── extensions.json ← Recommended extensions │ ├── agents/ │ ├── slither_agent.py ← Runs slither subprocess, falls back to fixture │ └── mythril_agent.py ← Runs myth subprocess, falls back to fixture │ ├── normalizer/ │ ├── schema.py ← FindingSchema dataclass (canonical format) │ ├── slither_normalizer.py │ └── mythril_normalizer.py │ ├── pipeline/ │ ├── auditor.py ← Main pipeline orchestrator (also the CLI entry) │ └── merge.py ← Fingerprint dedup + MergeReport │ ├── sarif/ │ └── exporter.py ← SARIF 2.1.0 output │ ├── fixtures/raw/ │ ├── slither_output.json ← Real-shaped fixture for offline runs │ └── mythril_output.json │ ├── contracts/ ← Your .sol files go here ├── reports/ ← Generated .sarif and .json output ├── tests/ │ └── test_pipeline.py └── requirements.txt ``` ## Normaliser Schema 的工作原理 来自任何工具的每项发现都会被转换为： ``` { "tool": "slither", "category": "reentrancy-eth", "rule_id": "slither/reentrancy-eth", "swc_id": "SWC-107", "severity": "high", "severity_raw": "High", "confidence": "medium", "message": "Reentrance.withdrawBalance() sends eth to arbitrary user...", "location": { "file": "contracts/Reentrancy.sol", "contract": "Reentrance", "function": "withdrawBalance", "exact_line": 16 }, "fingerprint": "a3f2c1d4e5b6a7f8" } ``` ## 去重逻辑 指纹是 `category + file + contract + function + line` 的 SHA-256 哈希值 —— **故意排除了工具名称**。因此，如果 Slither 和 Mythril 都标记了第 16 行 `withdrawBalance()` 中的重入漏洞，它们将生成相同的指纹，并被合并为一项发现，且保留： - 最高严重级别 - 最高可信度 - 最长/最丰富的信息 - 工具被标注为 `[mythril, slither]` ## Fixture 模式与实时模式 Agent 具有一个 `use_fixture_on_fail=True` 标志。当实时工具执行失败时（例如未安装 solc、超时），它们会自动回退到 `fixtures/raw/` 中预构建的 fixture JSON。这使您能够在没有可用 solc 的情况下开发和测试流水线。 要强制使用纯实时模式： ``` pipeline = AuditorPipeline(use_fixture_on_fail=False) ``` ## 添加新的工具 Agent 1. 创建 `agents/newtool_agent.py` —— 实现 `.run(target) -> list[FindingSchema]` 2. 创建 `normalizer/newtool_normalizer.py` —— 实现 `normalise(raw) -> list[FindingSchema]` 3. 将其添加到 `pipeline/auditor.py` 中的 `AuditorPipeline.__init__` 4. 在 `fixtures/raw/newtool_output.json` 中添加一个 fixture 就是这样。合并和 SARIF 步骤是与工具无关的。

标签：AI多智能体框架, Mythril, Python, SARIF, Slither, Solidity, Subfinder, URL发现, Web3安全, 代码分析, 以太坊安全, 凭证管理, 区块链安全, 去重处理, 图数据库, 安全检测, 对称加密, 无后门, 智能合约审计, 符号执行, 自动化审计, 逆向工具, 错误基检测, 静态代码分析