MIESC
35个分析模块。9层防御。一条命令。
企业级智能合约安全，免费开放给所有人。
快速开始 •
为什么选择 MIESC •
GitHub Action •
Docker •
Español •
文档
## 快速开始
```
pip install miesc
miesc scan MyContract.sol
```
仅此而已。MIESC 运行 Slither + Aderyn + Solhint，并在数秒内为你提供统一报告。
想要完整的 9 层分析以及 AI 相关性？
```
miesc audit full MyContract.sol -o results.json
miesc report results.json -t premium -f pdf --llm-interpret
```
查看示例输出
```
=== Layer 1: Static Analysis ===
OK slither: 5 findings in 1.7s
OK aderyn: 5 findings in 3.0s
OK solhint: 0 findings in 0.7s
=== Layer 2: Dynamic Testing ===
OK echidna: 0 findings in 2.0s
OK foundry: 0 findings in 9.0s
=== Layer 3: Symbolic Execution ===
OK mythril: 2 findings in 298.0s
=== Layer 5: AI Analysis ===
OK smartllm: 4 findings in 198.9s
OK gptscan: 4 findings in 49.7s
Full Audit Summary
+----------+-------+
| Severity | Count |
+----------+-------+
| CRITICAL | 1 |
| HIGH | 11 |
| MEDIUM | 1 |
| LOW | 9 |
| TOTAL | 22 |
+----------+-------+
Tools executed: 12/29
Report saved to results.json
```
## 为什么选择 MIESC
**问题**：专业智能合约审计成本为 5 万至 20 万美元，且耗时数周。与此同时，每年超过 15 亿美元因漏洞而损失。大多数项目根本没有进行任何审计。仅运行 Slither 就能发现约 70% 的漏洞，但会产生 15-20% 的误报。每个工具都有盲点。审计人员手动运行 5-10 个工具，归一化输出并交叉引用结果。这需要数小时。
**MIESC 让这一流程对每个人开放。** 一条命令协调多个安全工具，采用 9 种互补分析技术，去重并生成专业报告。免费、开源、本地运行——你的代码永远不会离开你的机器。
### 基准测试结果
**SmartBugs curated**（143 个合约，207 个真实漏洞）：
| 指标 | 仅 Slither | 仅 Mythril | MIESC（静态） | MIESC（全层） |
|--------|:------------:|:-------------:|:--------------:|:------------------:|
| 召回率 | 43.2% | 27.4% | 54.6% | **80.0%** |
| 精确率 | 8.3% | 6.1% | 9.3% | 22.7% |
| F1 分数 | 13.9% | 10.0% | 15.9% | **35.4%** |
**真实世界漏洞**（11 个已确认 DeFi 漏洞，总损失 33 亿美元）：
| 漏洞类型 | 实际利用数 | 检测到 | 召回率 | 示例 |
|---------------|:--------:|:--------:|:------:|----------|
| 重入攻击 | 3 | 3 | **100%** | Euler $1.97 亿，Rari $8000 万，Platypus $850 万 |
| 访问控制 | 3 | 3 | **100%** | Parity $2.8 亿，Ronin $6.24 亿 |
| 闪电贷攻击 | 2 | 2 | **100%** | bZx $810 万，Compound $8000 万 |
| 总体 | 11 | 9 | **81.8%** | Cohen's Kappa: 0.773 |
**为何召回率比精确率对预审计分流更重要**：高召回率意味着更少的漏洞被遗漏。误报可在分流阶段过滤；遗漏的漏洞则可能在生产中成为实际攻击。
### 9 层防御
```
Layer 1 Static Analysis Slither, Aderyn, Solhint, Semgrep
Layer 2 Dynamic Testing Echidna, Foundry, Medusa
Layer 3 Symbolic Execution Mythril, Halmos, Manticore
Layer 4 Formal Verification SMTChecker, Scribble, Certora*
Layer 5 AI/LLM Analysis SmartLLM, GPTScan, LLMSmartAudit (Ollama)
Layer 6 Pattern Detection Gas Analyzer, Clone Detector, Threat Model
Layer 7 DeFi Security MEV Detector, Flash Loan Analyzer, Oracle Checker
Layer 8 Exploit Validation PoC Synthesizer (Foundry), Vulnerability Verifier
Layer 9 Consensus & Reporting Bayesian Consensus, RAG Enrichment, PDF Reports
```
*Certora 需要 API 密钥。其他工具均为完全开源。
### MIESC 集成了什么
| 类别 | 数量 | 示例 |
|----------|:-----:|---------|
| **外部安全工具** | 13 | Slither、Mythril、Echidna、Foundry、Halmos、Aderyn、Semgrep |
| **LLM 分析模块** | 6 | SmartLLM、GPTScan、PropertyGPT（通过本地 Ollama） |
| **内部分析器** | 16 | MEV 检测器、Gas 分析器、威胁模型、克隆检测器 |
| **总分析模块** | **35** | 覆盖 9 种互补技术 |
### 与 SmartBugs 2.0（最接近的竞争对手）对比
| | MIESC | SmartBugs 2.0 |
|---|---|---|
| 外部工具 | 13 | 19 |
| AI/LLM 分析 | 是（本地 Ollama） | 否 |
| 内部分析器 | 16 | 否 |
| 误报过滤 | 是（RAG + 机器学习） | 否 |
| 专业 PDF 报告 | 是 | 否 |
| 插件系统 | 是（PyPI） | 否 |
| GitHub Action | 是 | 否 |
| SARIF 输出 | 是 | 是 |
## GitHub Action
在 30 秒内将智能合约安全功能添加到任意 CI/CD 流水线：
```
# .github/workflows/security.yml
name: Security
on: [push, pull_request]
permissions:
security-events: write
pull-requests: write
jobs:
miesc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: fboiero/MIESC@v5
with:
path: contracts/
mode: scan
fail-on: high
upload-sarif: true
comment-on-pr: true
```
结果会显示在 GitHub 的 **Security** 标签页中，并作为 PR 评论呈现。详见 [示例工作流](./.github/workflows/example-miesc-action.yml) 了解高级配置。
### 可用模式
| 模式 | 工具 | 耗时 | 适用场景 |
|------|-------|------|----------|
| `scan` | Slither、Aderyn、Solhint | ~30s | 每次推送 |
| `audit-quick` | 4 个核心工具 | ~2min | PR 检查 |
| `audit-full` | 全部 9 层 | ~10min | 预发布 |
| `audit-profile` | 可配置 | 可变 | DeFi、代币等 |
## 安装
```
# 最小 CLI
pip install miesc
# 带 PDF 报告
pip install miesc[pdf]
# 一切（PDF、LLM、RAG、Web UI）
pip install miesc[full]
# 开发
git clone https://github.com/fboiero/MIESC.git
cd MIESC && pip install -e .[dev]
```
要求：Python 3.12+。Slither 会自动安装。其他工具为可选——MIESC 会使用所有可用的工具。
## Docker
```
# 标准镜像（约 3GB，包含 Apple Silicon 的多架构）
docker pull ghcr.io/fboiero/miesc:latest
docker run --rm -v $(pwd):/contracts ghcr.io/fboiero/miesc:latest scan /contracts/MyContract.sol
# 完整镜像（约 8GB，包含全部 50 个工具，amd64）
docker pull ghcr.io/fboiero/miesc:full
docker run --rm -v $(pwd):/contracts ghcr.io/fboiero/miesc:full audit full /contracts/MyContract.sol
# 检查可用工具
docker run --rm ghcr.io/fboiero/miesc:latest doctor
```
Docker + 主机 Ollama（推荐用于 GPU 加速）
MIESC 的 LLM 层（Layer 5）使用 Ollama 进行本地 AI 分析。推荐设置在主机上运行 Ollama（并启用 GPU 访问），然后通过网络让 Docker 容器连接：
```
# 1. 在主机（不在 Docker 内）安装并启动 Ollama
# 从 https://ollama.com 下载
ollama serve &
ollama pull qwen2.5-coder:14b # Best model for code analysis
ollama pull deepseek-coder:6.7b # Lighter alternative
# 2. 使用主机 Ollama 扫描（macOS）
docker run --rm \
-e OLLAMA_HOST=http://host.docker.internal:11434 \
-v $(pwd)/contracts:/contracts \
ghcr.io/fboiero/miesc:latest \
scan /contracts/MyContract.sol -o /contracts/results.json
# 3. 使用主机 Ollama 扫描（Linux）
docker run --rm --network=host \
-e OLLAMA_HOST=http://localhost:11434 \
-v $(pwd)/contracts:/contracts \
ghcr.io/fboiero/miesc:latest \
scan /contracts/MyContract.sol
# 4. 生成 AI 驱动的 PDF 报告
docker run --rm \
-e OLLAMA_HOST=http://host.docker.internal:11434 \
-v $(pwd):/work \
ghcr.io/fboiero/miesc:full \
report /work/results.json -t premium -f pdf \
--llm-interpret -o /work/audit_report.pdf
```
**为何在主机运行 Ollama？** Docker 容器默认无法访问 GPU。在主机运行 Ollama 可让其使用你的 GPU（Apple Silicon、NVIDIA CUDA），实现 10-50 倍更快的 LLM 推理。
Docker Compose（完整栈，含捆绑的 Ollama）
在没有主机 Ollama 的环境中，使用 docker-compose 一并运行所有服务：
```
# 启动 MIESC + Ollama + 模型初始化
docker compose --profile llm up -d
# 运行分析
docker compose exec miesc miesc scan /contracts/MyContract.sol
# 停止
docker compose down
```
编排栈会自动拉取 `deepseek-coder:6.7b` 并配置服务间网络。
ARM / Apple Silicon 注意事项
**标准** 镜像原生支持 ARM。
**完整** 镜像仅含 amd64，需在 QEMU 下仿真运行。如需在原生 ARM 上构建，请使用：
```
./scripts/build-images.sh full # ~30-60 min, but native speed
```
## CLI 参考
```
miesc scan contract.sol # Quick scan (Slither + Aderyn + Solhint)
miesc scan contract.sol --ci # CI mode: exit 1 on critical/high
miesc audit quick contract.sol # 4-tool audit
miesc audit full contract.sol # Full 9-layer audit
miesc audit layer 3 contract.sol # Specific layer (e.g., symbolic execution)
miesc audit profile defi contract.sol # Named profile (defi, token, security, etc.)
miesc report results.json -t premium -f pdf --llm-interpret # AI-powered PDF report
miesc export results.json -f sarif # Export as SARIF
miesc doctor # Check tool availability
miesc watch ./contracts # Auto-scan on file changes
miesc benchmark ./contracts --save # Track security posture over time
```
### 分析配置
| 配置 | 层数 | 适用场景 |
|---------|--------|----------|
| `fast` | 1 | 开发过程中快速反馈 |
| `balanced` | 1, 3 | 预提交检查 |
| `ci` | 1 | CI/CD 流水线 |
| `security` | 1, 3, 4,5 | 高价值合约 |
| `defi` | 1, 2, 3, 5, 8 | DeFi 协议 |
| `token` | 1, 3, 5 | ERC20/721/1155 代币 |
| `thorough` | 1-9 | 预发布 / 全面审计 |
## 扩展 MIESC
### 自定义检测器
```
from miesc.detectors import BaseDetector, Finding, Severity
class DangerousDelegatecall(BaseDetector):
name = "dangerous-delegatecall"
description = "Detects unprotected delegatecall patterns"
def analyze(self, source_code, file_path=None):
findings = []
# Your detection logic here
return findings
```
通过 `pyproject.toml` 注册：
```
[project.entry-points."miesc.detectors"]
dangerous-delegatecall = "my_package:DangerousDelegatecall"
```
### 插件系统
```
miesc plugins install miesc-defi-detectors # Install from PyPI
miesc plugins create my-detector # Scaffold a new plugin
miesc plugins list # List installed plugins
miesc detectors list # List all available detectors
```
### 集成
```
# 预提交钩子（.pre-commit-config.yaml）
repos:
- repo: https://github.com/fboiero/MIESC
rev: v5.1.1
hooks:
- id: miesc-quick
args: ['--ci']
```
```
# Foundry（foundry.toml）
[profile.default]
post_build_hook = "miesc audit quick ./src --ci"
```
```
// Hardhat (hardhat.config.js)
require("hardhat-miesc");
module.exports = {
miesc: { enabled: true, runOnCompile: true, failOn: "high" }
};
```
### MCP 服务器
MIESC 通过 [模型上下文协议](https://modelcontextprotocol.io) 与 AI 代理集成：
```
miesc server mcp # Start MCP WebSocket server
```
```
// Claude Desktop / MCP client config
{
"mcpServers": {
"miesc": {
"command": "miesc",
"args": ["server", "mcp"]
}
}
}
```
### Python API
```
from miesc.api import run_tool, run_full_audit
results = run_tool("slither", "contract.sol")
report = run_full_audit("contract.sol")
```
### Web UI
```
pip install miesc[web]
make webapp # Opens at http://localhost:8501
```
带有上传、分析、结果可视化与报告导出的交互式 Streamlit 仪表板。
## 多链支持
| 链 | 状态 | 语言 |
|-------|--------|-----------|
| **EVM**（以太坊、Polygon、BSC、Arbitrum 等） | 生产 | Solidity、Vyper |
| Solana | 早期 | Rust/Anchor |
| NEAR | 早期 | Rust |
| Move（Sui、Aptos） | 早期 | Move |
| Stellar/Soroban | 早期 | Rust |
| Algorand | 早期 | TEAL、PyTeal |
| Cardano | 早期 | Plutus、Aiken |
```
miesc scan program.rs --chain solana
miesc scan module.move --chain sui
```
## 合规性映射
MIESC 将每个发现映射到国际安全标准：
**ISO/IEC 27001:2022** | **NIST CSF** | **OWASP 智能合约 Top 10** | **CWE** | **SWC 注册表** | **MITRE ATT&CK** | **PCI-DSS** | **SOC 2**
## 架构
```
Contract.sol
|
v
CLI / API / MCP / GitHub Action
|
v
Orchestrator --> 9 Layers --> 50 Tool Adapters
|
v
Finding Aggregator --> ML Pipeline --> RAG Context --> FP Filter
|
v
Report Generator --> JSON / SARIF / PDF / HTML / Markdown
```
MIESC 采用双包架构：
- `miesc/` - 公共 API（稳定，可 pip 安装）
- `src/` - 内部实现（35 个分析模块、ML 流水线、RAG、报告生成）
详见 [ARCHITECTURE.md](./docs/ARCHITECTURE.md) 获取完整技术设计（含 Mermaid 图表）。
## 学术验证
MIESC 在 [UNDEF-IUA](https://www.iua.edu.ar/)（阿根廷）的网络防御硕士论文中开发。在 SmartBugs curated 基准（Durieux 等，ICSE 2020）上评估：
- **143 个合约**，207 个真实漏洞，10 个类别
- **80% 召回率**（230 个中的 184 个被检测出）——多工具编排中表现最佳
- **对重入攻击的召回率达 90.6%**，对未检查调用和时间操控为 100%
- **比手动运行工具快 85%**（约 1 秒/合约）
- 完整结果：[SMARTBUGS_SCIENTIFIC_REPORT.md](./benchmarks/results/SMARTBUGS_SCIENTIFIC_REPORT.md)
如果在研究中使用 MIESC，请引用：
```
@mastersthesis{boiero2025miesc,
title={Integrated Security Assessment Framework for Smart Contracts:
A Defense-in-Depth Approach to Cyberdefense},
author={Boiero, Fernando},
year={2025},
school={Universidad de la Defensa Nacional (UNDEF) - IUA C{\'o}rdoba},
type={Master's Thesis in Cyberdefense}
}
```
## 数字公共产品
MIESC 是 [数字公共产品联盟](https://digitalpublicgoods.net/) 的候选产品（申请 ID: GID0092948），符合联合国可持续发展目标：
- **SDG 9**（产业与基础设施）：加强区块链基础设施安全
- **SDG 16**（和平与强大机构）：保护数字资产，减少欺诈
- **SDG 17**（伙伴关系）：开源协作推动全球安全标准
该项目完全符合全部 9 项 DPGA 指标：开放许可证（AGPL-3.0）、清晰所有权、平台独立性、全面文档、数据可移植性（SARIF/CSV/JSON）、隐私优先（本地优先）、基于标准（12 项国际标准）以及负责任使用政策。
| 政策 | 描述 |
|--------|-------------|
| [DPG 合规](./docs/policies/DPG-COMPLIANCE.md) | 完整的 9 项指标合规声明 |
| [SDG 相关性](./docs/policies/SDG_RELEVANCE.md) | 可持续发展目标映射 |
| [隐私政策](./PRIVACY.md) | 数据处理和隐私声明 |
| [负责任使用](./RESPONSIBLE_USE.md) | 伦理使用指南 |
| [不造成伤害](./docs/policies/DO_NO_HARM.md) | 风险评估与缓解措施 |
## 文档
| 资源 | 描述 |
|----------|-------------|
| [安装指南](./docs/INSTALLATION.md) | 完整的设置说明 |
| [快速开始](./docs/guides/QUICKSTART.md) | 5 分钟内上手 |
| [架构](./docs/ARCHITECTURE.md) | 技术设计和各层详情 |
| [工具参考](./docs/TOOLS.md) | 所有 35 个分析模块及其能力 |
| [报告指南](./docs/guides/REPORTS.md) | 报告模板和定制 |
| [自定义检测器](./docs/CUSTOM_DETECTORS.md) | 构建你自己的检测器 |
| [多链支持](./docs/MULTICHAIN.md) | 非 EVM 链分析 |
| [API 参考](https://fboiero.github.io/MIESC/api/) | 从 docstrings 自动生成 |
| [贡献指南](./.github/CONTRIBUTING.md) | 开发指南 |
| [路线图](./docs/ROADMAP.md) | 下一步计划 |
## 故障排除
常见问题
**`miesc: command not found`**
安装 `pip install miesc` 后，入口点可能不在 PATH 中。请使用：
```
python3 -m miesc.cli.main --help
```
或将 `~/.local/bin`（或虚拟环境的 `bin`）添加到 PATH。
**`Tool 'mythril' not installed`**
可选工具需单独安装。可执行以下操作之一：
```
pip install miesc[full] # All Python-based tools
brew install mythril # System install
docker run ghcr.io/fboiero/miesc:full # Or use the full Docker image
```
**`Ollama API error: HTTP 404` 或 LLM 分析返回空**
所需模型未拉取。请运行：
```
ollama pull qwen2.5-coder:14b # ~9 GB, recommended
ollama pull qwen2.5-coder:32b # ~20 GB, more accurate (needs 24+GB RAM)
```
验证 Ollama 是否运行：`curl http://localhost:11434/api/tags`
**Docker 容器无法连接主机上的 Ollama（macOS）**
```
docker run -e OLLAMA_HOST=http://host.docker.internal:11434 ...
```
在 Linux 上，使用 `--network=host` 并设置 `OLLAMA_HOST=http://localhost:11434`。
**Slither 报错提示 `solc not found` 或版本不匹配**
安装 solc-select：
```
pip install solc-select
solc-select install 0.8.20 && solc-select use 0.8.20
```
**PDF 报告生成失败（`weasyprint` 错误）**
WeasyPrint 需要系统库：
```
brew install pango cairo gdk-pixbuf libffi # macOS
sudo apt install libpango-1.0-0 libpangoft2-1.0-0 # Linux
```
**`miesc audit full` 运行缓慢（>10 分钟/合约）**
大型模型（32B）在小合约上较慢。请在 `~/.miesc/config.yaml` 中使用 `qwen2.5-coder:14b`，或运行快速扫描：`miesc audit quick`。
## 贡献
```
git clone https://github.com/fboiero/MIESC.git
cd MIESC && pip install -e .[dev]
pytest tests/ # 4,800+ tests, 82% coverage
```
详见 [CONTRIBUTING.md](./.github/CONTRIBUTING.md) 获取指南。[CONTRIBUTING_ES.md](./.github/CONTRIBUTING_ES.md) 提供西班牙语版本。
## 许可证
[AGPL-3.0](./LICENSE) - 任何用途免费使用。安全不应成为只有资金充足的项目才能享有的特权。如果你在 MIESC 基础上构建服务，请回馈你的修改。
## 作者
**Fernando Boiero** - 网络防御硕士论文，UNDEF-IUA 阿根廷
站在巨人的肩膀上：[Slither](https://github.com/crytic/slither)、[Mythril](./docs/ARCHITECTURE.md)、[Echidna](https://github.com/crytic/echidna)、[Foundry](https://github.com/foundry-rs/foundry)、[Aderyn](https://github.com/Cyfrin/aderyn)、[Halmos](https://github.com/a16z/halmos) 以及以太坊安全社区。