cybort360/sentinel
GitHub: cybort360/sentinel
SENTINEL 是一个多 Agent 智能合约审计「作战室」，通过多个 Qwen Agent 在真实 EVM 沙盒中进行辩论式安全审计并验证补丁，以解决单遍代码扫描无法发现深层漏洞和量化剩余风险的问题。
Stars: 0 | Forks: 0
# SENTINEL
一个多 Agent 的“作战室”，会基于真实的模拟数据、真实的机构记忆，以及在关键决策环节引入真实的人工介入（human in the loop），来讨论你的协议是否安全到可以发布。
已提交至 Qwen Cloud Global AI Hackathon，主赛道为 Track 3 (Agent Society)，并集成了 Track 1 (Memory) 和 Track 4 (Autopilot) 作为子赛道。
- **它是什么 / 如何工作：** 请参阅下方的[架构](#architecture)部分以及 [`docs/architecture.png`](docs/architecture.png)。
- **如何部署 + 记录阿里云验证：** 请参阅 [`deploy/DEPLOY.md`](deploy/DEPLOY.md)。
## 架构
五个基于 Qwen 的 Agent 在一个 War Room orchestrator 内进行辩论；每一个事实性主张都来源于真实的 MCP 工具调用（黄金法则 1），并且任何应用决策都会在人工检查点处被阻塞（黄金法则 2）。来源：[`docs/architecture.mmd`](docs/architecture.mmd) · PNG：[`docs/architecture.png`](docs/architecture.png)。
```
flowchart TB
subgraph FE["Frontend"]
direction LR
WEB["Web War Room UI
live SSE trace · evidence drill-down · browser checkpoint"] CLI["CLI
make run · demo · bench · verify"] end subgraph QC["Qwen Cloud — Alibaba Model Studio (OpenAI-compatible API)"] direction LR QM1["qwen3-coder-plus"] QM2["qwen3-max"] QM3["qwen3-max"] QM4["qwen-plus"] end subgraph ORCH["SENTINEL Orchestrator — War Room graph"] direction TB FLOW["Control flow
ingest → parallel scan → propose · veto · adjudicate loop → RiskProfile"] subgraph SOC["Agent Society — Qwen function-calling"] direction LR YA["Yield
optimizer"] AA["Adversary
red team · veto"] ARB["Arbitrator
judge · synthesize"] LA["Lessons
memory"] BA["Baseline
single-pass control"] end HCP{{"Human Checkpoint
blocking gate"}} end subgraph MCP["Custom MCP Servers — stdio / streamable-http"] direction LR CMCP["CodebaseMCP
read · propose · diff · apply"] SMCP["SimulationMCP
deploy · gas · revert · exploit · verify_patch"] MMCP["MemoryMCP
query · write · decay"] end subgraph DATA["Sandbox & Data"] direction LR ANVIL["Anvil EVM fork
Foundry · local-only (Rule 3)"] GITWC["Git working copy
staged patches"] MEMDB[("SQLite + sqlite-vec
decaying memory store")] end YA <--> QM1 AA <--> QM2 ARB <--> QM3 LA <--> QM4 BA <--> QM3 SOC --> FLOW --> HCP YA -->|read| CMCP BA -->|read| CMCP ARB -->|stage patch| CMCP AA -->|"every claim → trace_id (Rule 1)"| SMCP LA -->|recall / post-mortem| MMCP CMCP --> GITWC SMCP --> ANVIL MMCP --> MEMDB HCP -->|approved| CMCP FLOW -->|"§10 structured trace (SSE)"| FE FE -->|"run audit / approve"| FLOW classDef qwen fill:#FFF3E0,stroke:#FB8C00,color:#5D4037; classDef orch fill:#ECEBFC,stroke:#4B45D6,color:#36309F; classDef mcp fill:#E7F6F1,stroke:#0E8A6E,color:#0A6A55; classDef data fill:#EEF1F5,stroke:#5B6573,color:#39414E; classDef fe fill:#E3F2FD,stroke:#2563EB,color:#14304F; class QM1,QM2,QM3,QM4 qwen; class YA,AA,ARB,LA,BA,FLOW,HCP orch; class CMCP,SMCP,MMCP mcp; class ANVIL,GITWC,MEMDB data; class WEB,CLI fe; ``` ## 快速开始 ``` make run-demo # reproducible showcase — no API keys needed make run # the real thing — live Qwen agents (needs QWEN_* in .env) ``` 两者都只需一条命令：它们会安装依赖，并在一个实时 Anvil 沙盒上运行双会话的 War Room（包含真实的模拟数据、真实的机构记忆、真实的阻塞式人工检查点），然后打印 §11 效率表。**沙盒会自动启动和停止** —— 无需手动设置或清理。 - **`make run-demo`** 使用确定性的 demo 驱动程序，进行*真实的* `SimulationMCP` 调用（保留了黄金法则 1）—— 完全可复现，无需凭证。这是展示用例 / CI 验证的内容。 - **`make run`** 运行真实的五 Agent Qwen War Room。请先在 `.env` 中设置 `QWEN_*`；如果未设置，它会打印通知并回退到 demo 驱动程序，因此依然可以正常运行。 唯一的前置条件是 **Foundry**（一次性操作：`curl -L https://foundry.paradigm.xyz | bash && foundryup`）；Python 3.11+ 由 `uv` 提供。复制 `.env.example` 到 `.env` 以配置 `ANVIL_FORK_URL` 和 `QWEN_*` 凭证。 检查点会自动批准并带有清晰标注的 demo 决策；如果需要真实的 `rich` 提示，请传入 `--interactive`（`uv run python -m demo.run_demo --interactive`，需在沙盒运行时执行）以进行交互。 ## Web UI（浏览器 War Room） ``` make run-web # one command: set up, then serve the UI (sandbox auto-managed) ``` 然后打开 **http://localhost:8088**。 ## 效率基准测试（Track 3：对比单 Agent 基线的可衡量增益） ``` make bench # audits a corpus with the single-pass Baseline AND the War Room ``` 对两者进行已知真值（ground truth）评分并打印对比结果。在当前的 3 合约语料库中，多 Agent Society 在各项指标上都击败了单 Agent 基线 —— 例如 **100% vs 67% 的检出率**，**3 vs 0 个暴露出的权衡（trade-offs）**，**0 vs 1 个假阴性**，**22 vs 0 个有真实模拟溯源的声明**。这种差距是结构性的：单遍历的源码阅读器无法看到由模拟发现的 DoS，也无法量化剩余风险。评分逻辑位于 `src/sentinel/orchestrator/benchmark.py`；添加合约可以扩充语料库。 ## 补丁验证（证明一个修复，而不只是建议） ``` make verify # re-runs the exact exploit against the vulnerable + patched contract ``` 部署两个合约并在每个合约上运行相同的重入攻击：它从 `SubscriptionBilling` 中抽干了 **0.3 ETH**，并在带有重入锁的补丁上被**阻塞（回滚）** —— 这是基于实时 Anvil 运行的真实前后对比读取，而不是一句口头声明。该功能作为 `verify_patch` MCP 工具暴露（`src/sentinel/mcp_servers/simulation_mcp/`）。 同一审计的单页视图：War Room 时间线实时流式传输（SSE），每个引用的数字距离其背后的真实 `SimulationMCP` 结果只有一次点击之遥（黄金法则 1，可视化呈现），而人工检查点由一个真正会阻塞运行的按钮驱动（黄金法则 2）。它是 §10 跟踪流的*只读渲染器* —— 它从不自行发起 Agent 声明。 ## 在 Docker 中运行全栈 ``` make docker-up # anvil + 3 MCP servers + orchestrator (architecture.md §15) ``` 同一个 `docker-compose.yml` 就是阿里云部署产物 —— `ECS_HOST=user@ip make deploy` 会将其发布到 ECS 实例。请参阅 [`deploy/DEPLOY.md`](deploy/DEPLOY.md) 了解配置和验证录像。 ## 状态 War Room（包含 Yield / Adversary / Arbitrator / Lessons / Baseline agents）、所有三个自定义 MCP 服务器、衰退型记忆存储、阻塞式人工检查点、编排图以及端到端 demo 均已实现，并覆盖了单元 + 集成（真实 Anvil）+ 黄金追踪（golden-trace）测试。默认的 demo agents 是进行**真实** `SimulationMCP` 调用的确定性驱动程序（保留了黄金法则 1）。实时的 Qwen agents 已**接入**相同的接口（`make dev` / `run_demo --live`，在缺少凭证时回退到 demo 驱动程序），并通过基于模拟客户端的冒烟测试进行了离线验证 —— 在它们正式上线运行前，只差真实的 Qwen 凭证即可。 ## 许可证 [MIT](LICENSE)。`CodebaseMCP` 和 `SimulationMCP` 旨在为任何审计 Solidity/EVM 代码的团队提供有用的独立工具 (architecture.md §16)。
live SSE trace · evidence drill-down · browser checkpoint"] CLI["CLI
make run · demo · bench · verify"] end subgraph QC["Qwen Cloud — Alibaba Model Studio (OpenAI-compatible API)"] direction LR QM1["qwen3-coder-plus"] QM2["qwen3-max"] QM3["qwen3-max"] QM4["qwen-plus"] end subgraph ORCH["SENTINEL Orchestrator — War Room graph"] direction TB FLOW["Control flow
ingest → parallel scan → propose · veto · adjudicate loop → RiskProfile"] subgraph SOC["Agent Society — Qwen function-calling"] direction LR YA["Yield
optimizer"] AA["Adversary
red team · veto"] ARB["Arbitrator
judge · synthesize"] LA["Lessons
memory"] BA["Baseline
single-pass control"] end HCP{{"Human Checkpoint
blocking gate"}} end subgraph MCP["Custom MCP Servers — stdio / streamable-http"] direction LR CMCP["CodebaseMCP
read · propose · diff · apply"] SMCP["SimulationMCP
deploy · gas · revert · exploit · verify_patch"] MMCP["MemoryMCP
query · write · decay"] end subgraph DATA["Sandbox & Data"] direction LR ANVIL["Anvil EVM fork
Foundry · local-only (Rule 3)"] GITWC["Git working copy
staged patches"] MEMDB[("SQLite + sqlite-vec
decaying memory store")] end YA <--> QM1 AA <--> QM2 ARB <--> QM3 LA <--> QM4 BA <--> QM3 SOC --> FLOW --> HCP YA -->|read| CMCP BA -->|read| CMCP ARB -->|stage patch| CMCP AA -->|"every claim → trace_id (Rule 1)"| SMCP LA -->|recall / post-mortem| MMCP CMCP --> GITWC SMCP --> ANVIL MMCP --> MEMDB HCP -->|approved| CMCP FLOW -->|"§10 structured trace (SSE)"| FE FE -->|"run audit / approve"| FLOW classDef qwen fill:#FFF3E0,stroke:#FB8C00,color:#5D4037; classDef orch fill:#ECEBFC,stroke:#4B45D6,color:#36309F; classDef mcp fill:#E7F6F1,stroke:#0E8A6E,color:#0A6A55; classDef data fill:#EEF1F5,stroke:#5B6573,color:#39414E; classDef fe fill:#E3F2FD,stroke:#2563EB,color:#14304F; class QM1,QM2,QM3,QM4 qwen; class YA,AA,ARB,LA,BA,FLOW,HCP orch; class CMCP,SMCP,MMCP mcp; class ANVIL,GITWC,MEMDB data; class WEB,CLI fe; ``` ## 快速开始 ``` make run-demo # reproducible showcase — no API keys needed make run # the real thing — live Qwen agents (needs QWEN_* in .env) ``` 两者都只需一条命令：它们会安装依赖，并在一个实时 Anvil 沙盒上运行双会话的 War Room（包含真实的模拟数据、真实的机构记忆、真实的阻塞式人工检查点），然后打印 §11 效率表。**沙盒会自动启动和停止** —— 无需手动设置或清理。 - **`make run-demo`** 使用确定性的 demo 驱动程序，进行*真实的* `SimulationMCP` 调用（保留了黄金法则 1）—— 完全可复现，无需凭证。这是展示用例 / CI 验证的内容。 - **`make run`** 运行真实的五 Agent Qwen War Room。请先在 `.env` 中设置 `QWEN_*`；如果未设置，它会打印通知并回退到 demo 驱动程序，因此依然可以正常运行。 唯一的前置条件是 **Foundry**（一次性操作：`curl -L https://foundry.paradigm.xyz | bash && foundryup`）；Python 3.11+ 由 `uv` 提供。复制 `.env.example` 到 `.env` 以配置 `ANVIL_FORK_URL` 和 `QWEN_*` 凭证。 检查点会自动批准并带有清晰标注的 demo 决策；如果需要真实的 `rich` 提示，请传入 `--interactive`（`uv run python -m demo.run_demo --interactive`，需在沙盒运行时执行）以进行交互。 ## Web UI（浏览器 War Room） ``` make run-web # one command: set up, then serve the UI (sandbox auto-managed) ``` 然后打开 **http://localhost:8088**。 ## 效率基准测试（Track 3：对比单 Agent 基线的可衡量增益） ``` make bench # audits a corpus with the single-pass Baseline AND the War Room ``` 对两者进行已知真值（ground truth）评分并打印对比结果。在当前的 3 合约语料库中，多 Agent Society 在各项指标上都击败了单 Agent 基线 —— 例如 **100% vs 67% 的检出率**，**3 vs 0 个暴露出的权衡（trade-offs）**，**0 vs 1 个假阴性**，**22 vs 0 个有真实模拟溯源的声明**。这种差距是结构性的：单遍历的源码阅读器无法看到由模拟发现的 DoS，也无法量化剩余风险。评分逻辑位于 `src/sentinel/orchestrator/benchmark.py`；添加合约可以扩充语料库。 ## 补丁验证（证明一个修复，而不只是建议） ``` make verify # re-runs the exact exploit against the vulnerable + patched contract ``` 部署两个合约并在每个合约上运行相同的重入攻击：它从 `SubscriptionBilling` 中抽干了 **0.3 ETH**，并在带有重入锁的补丁上被**阻塞（回滚）** —— 这是基于实时 Anvil 运行的真实前后对比读取，而不是一句口头声明。该功能作为 `verify_patch` MCP 工具暴露（`src/sentinel/mcp_servers/simulation_mcp/`）。 同一审计的单页视图：War Room 时间线实时流式传输（SSE），每个引用的数字距离其背后的真实 `SimulationMCP` 结果只有一次点击之遥（黄金法则 1，可视化呈现），而人工检查点由一个真正会阻塞运行的按钮驱动（黄金法则 2）。它是 §10 跟踪流的*只读渲染器* —— 它从不自行发起 Agent 声明。 ## 在 Docker 中运行全栈 ``` make docker-up # anvil + 3 MCP servers + orchestrator (architecture.md §15) ``` 同一个 `docker-compose.yml` 就是阿里云部署产物 —— `ECS_HOST=user@ip make deploy` 会将其发布到 ECS 实例。请参阅 [`deploy/DEPLOY.md`](deploy/DEPLOY.md) 了解配置和验证录像。 ## 状态 War Room（包含 Yield / Adversary / Arbitrator / Lessons / Baseline agents）、所有三个自定义 MCP 服务器、衰退型记忆存储、阻塞式人工检查点、编排图以及端到端 demo 均已实现，并覆盖了单元 + 集成（真实 Anvil）+ 黄金追踪（golden-trace）测试。默认的 demo agents 是进行**真实** `SimulationMCP` 调用的确定性驱动程序（保留了黄金法则 1）。实时的 Qwen agents 已**接入**相同的接口（`make dev` / `run_demo --live`，在缺少凭证时回退到 demo 驱动程序），并通过基于模拟客户端的冒烟测试进行了离线验证 —— 在它们正式上线运行前，只差真实的 Qwen 凭证即可。 ## 许可证 [MIT](LICENSE)。`CodebaseMCP` 和 `SimulationMCP` 旨在为任何审计 Solidity/EVM 代码的团队提供有用的独立工具 (architecture.md §16)。
标签：AI大模型, Qwen, Web3安全, 多智能体, 智能合约审计, 请求拦截, 逆向工具