mystiquemide/breachresponse
GitHub: mystiquemide/breachresponse
面向 Mantle 智能合约的自主事件响应基础设施，通过链上监控、LLM 分析、共识验证与人工审批为安全团队提供可控的 runtime 审计与应急响应路径。
Stars: 0 | Forks: 0
# BreachResponse
针对可疑智能合约活动的 Mantle runtime 审计助手。
在线指挥中心：https://breachresponse.xyz
BreachResponse 是一个专门针对 Mantle 的 runtime 审计助手。它监控可疑的合约活动，将原始信号转化为结构化的事件上下文，并将高风险响应操作置于操作员审批之后。该系统结合了感知 Mantle 的监控代理、Solidity 审查合约、外部共识守卫，以及为需要可控响应路径而非“恐慌按钮”的安全团队构建的指挥中心 UI。
## 为什么它很重要
智能合约团队在安全事件期间很少能得到一个清晰的决策窗口。BreachResponse 围绕更严谨的审查模型构建：
1. 监控 Mantle 活动和哨兵遥测数据。
2. 呈现可疑的交易模式和协议异常。
3. 用操作员易懂的语言解释发生了什么变化。
4. 将风险上下文结构化为响应提案。
5. 将高风险操作置于人工审批和限定的策略控制之下。
6. 记录审查轨迹以供后续跟进和审计。
## 工作原理
1. 协议注册受保护的 Mantle 合约或哨兵地址。
2. 哨兵监控 Mantle RPC 活动、遥测数据和已注册的协议状态。
3. 可疑行为将被转化为结构化的事件上下文，而不是模糊的警报。
4. 代理准备限定范围的响应 calldata，并通过外部决策守卫路由处理模棱两可的情况。
5. 操作员在任何 Mantle 端执行之前批准或拒绝该操作。
## 支持的价值监控
指挥中心包含一个由只读 Mantle Sepolia RPC 调用支持的**监控价值**卡片。它聚合来自活动哨兵地址的原生 MNT 余额和可选的白名单 ERC-20 余额。该路由不使用签名者、不使用私钥，也不执行任何交易。缺失的代币价格将保持不可用状态，而不是伪造。
## 产品范围
BreachResponse 专注于 Mantle 安全基础设施：监控协议活动、分类可疑行为，以及为操作员审批准备限定范围的紧急响应提案。该产品刻意避开交易自动化、流动性管理和钱包经济功能，从而确保指挥中心始终专注于为 Mantle 构建者提供 runtime 审计协助。
有关范围决策、集成边界和未来的适配器路径，请参阅[产品范围](./docs/PRODUCT_SCOPE.md)。
## 核心能力
- Mantle 哨兵注册表，用于协议接入和审查权限管理。
- Next.js 指挥中心，用于可疑活动审查、审批控制和实时遥测。
- Python 监控代理，用于 Mantle RPC 扫描、LLM 辅助的 runtime 分析和结构化事件输出。
- Solidity 验证合约和测试，证明漏洞路径和受控防御路径。
- 不提交密钥或生产环境机密的安全环境模板。
- CI 检查涵盖前端、合约、代理语法和依赖审计。
## Runtime 审计协助
BreachResponse 使用 LLM 辅助分析层，将可疑的 Mantle 活动转化为结构化的 runtime 审查报告。该模型会解释可能存在的问题，分配置信度，总结证据，并在涉及高风险下一步操作时将结果传递到审批路径。
LLM 不会获得不受限制的执行权限。人工审批是默认的响应模式，任何自动化策略都应仅限于白名单合约、上限操作、紧急选择器和受监控的阈值。
有关模型输入/输出结构和安全模型，请参阅 [AI 事件分析](./docs/AI_INCIDENT_ANALYSIS.md)。
## 外部决策守卫
BreachResponse 包含一个外部守卫层，适用于快速 LLM 路径不可用、格式错误、低置信度、相互冲突或建议执行高风险操作的情况。面向用户的钱包流仍保持在 Mantle 上。在此版本中，守卫层由 GenLayer 智能合约提供支持。应用程序将 GenLayer 作为共识验证层进行通信，然后在涉及高风险的 Mantle 端响应进入审批之前使用其结果。操作员、审查员和协议团队可以直接在此处检查它：
| 文件 | 用途 |
| --- | --- |
| [`contracts/genlayer/IncidentConsensusGuard.py`](./contracts/genlayer/IncidentConsensusGuard.py) | GenLayer 智能合约，用于存储事件、调用验证器端的 LLM 推理、执行紧急操作白名单并记录共识决策。 |
| [`tests/direct/test_incident_consensus_guard.py`](./tests/direct/test_incident_consensus_guard.py) | Direct-mode GenLayer 测试，涵盖审批、拒绝、低置信度升级、格式错误的验证器输出、不安全操作拒绝、重复事件和执行标记。 |
| [`frontend/src/lib/genlayerConsensus.ts`](./frontend/src/lib/genlayerConsensus.ts) | 指挥中心共识守卫面板使用的真实 `genlayer-js` 读写集成。 |
| [`frontend/src/app/dashboard/page.tsx`](./frontend/src/app/dashboard/page.tsx) | 操作员 UI 面板，用于准备应用管理的 GenLayer 签名者、读取共识记录，并在配置已部署的守卫地址后验证事件。 |
该合约通过 `gl.nondet.exec_prompt(...)` 和 `gl.vm.run_nondet_unsafe(...)` 使用 GenLayer 非确定性和验证器共识。它仅批准限定范围的紧急操作，例如 `pause_protocol`、`quarantine_address`、`monitor_only`、`alert` 和 `multisig_proposal`。
普通用户无需将钱包切换到 GenLayer。Mantle 仍然是受保护协议、注册表更新、钱包用户体验和响应交易的执行网络。GenLayer 在 StudioNet/testnet 上运行，并通过 BreachResponse 服务/UI 层接收事件上下文。
使用以下命令进行验证：
```
genvm-lint check contracts/genlayer/IncidentConsensusGuard.py --json
python3.12 -m venv /tmp/breachresponse-direct
/tmp/breachresponse-direct/bin/python -m pip install -r tests/direct/requirements.txt
/tmp/breachresponse-direct/bin/python -m pytest tests/direct/test_incident_consensus_guard.py -q
```
Direct-mode 套件在 Python 3.12 下运行，因为当前的 GenLayer 测试夹具需要 Python 3.12+。
前端使用的 StudioNet 部署如下：
| 字段 | 值 |
| --- | --- |
| 网络 | GenLayer StudioNet |
| 共识守卫合约地址 | `0x86369EC44fbB5EB682729368557176858aBe0c73` |
| 部署交易 | `0xec4e0f05378f1f9ebd0d3d47fc1b6ee815ff3b0a4cd271988f0c1d5ab3b9970a` |
| 部署者 | `0x65567Bf52e47A20C10793748C36597fAC2E3056D` |
| 验证 | `genlayer schema` 和 `genlayer call get_stats` 在 StudioNet 上执行成功 |
要启用前端实时升级，请设置：
```
NEXT_PUBLIC_GENLAYER_CONSENSUS_GUARD_ADDRESS=0x86369EC44fbB5EB682729368557176858aBe0c73
NEXT_PUBLIC_GENLAYER_STUDIO_URL=https://studio.genlayer.com/api
```
## Mantle Sepolia 部署
前端使用的当前 SentinelRegistry 部署如下：
| 字段 | 值 |
| --- | --- |
| 网络 | Mantle Sepolia |
| 注册表合约地址 | `0xea3C039795B5b04105B795c8B0cB85e0a42Cc85C` |
| 浏览器 | https://sepolia.mantlescan.xyz/address/0xea3C039795B5b04105B795c8B0cB85e0a42Cc85C#code |
| 部署交易 | https://sepolia.mantlescan.xyz/tx/0x0dac721b1ed137bf93132222348aab39bae48ed3a6e8b8e6ed0d0ee9d91f2b07 |
| 部署者 | `0x9f758be3ae3d985713964339e2f0bd783fc6015c` |
| 源码验证 | 已在 Mantlescan 和 Sourcify 上验证 |
## 产品截图
### 指挥中心
### 移动端概览
## 产品操作演示
对于产品评审，请使用最简明客观的操作演示：
1. 打开登录页面并点击 **Features** 跳转到 **Pipeline Execution**。
2. 点击 **Connect and Enter** 或 **Enter Command Center** 打开操作员仪表板。
3. 连接 Mantle Sepolia 钱包以获取实时钱包状态，或者保持断开连接以展示安全的禁用状态。
4. 审查 **Register Sentinel Guard**，并确认在存在所需的钱包和目标合约状态之前，受守卫的操作保持禁用。
5. 审查 **GenLayer Consensus Guard** 并解释其边界：普通用户将钱包保留在 Mantle 上，而 BreachResponse 通过应用层将模棱两可的事件上下文提交给 GenLayer 进行验证器共识审查。
6. 打开 **Threat History** 进行事件审查，然后通过浏览器后退或 **BACK** 返回，而不会困在仪表板中。
7. 断开钱包并确认仪表板恢复到安全的可读状态。
有关完整的演示和准确的措辞，请参阅[审查工作流](./docs/REVIEW_WORKFLOW.md)。
## 架构
Mantle 仍然是用于注册表状态、受监控资产、钱包操作和已批准响应交易的执行网络。外部守卫在涉及高风险的操作进入审批之前，验证模棱两可的 AI/安全决策。
### 系统架构
```
flowchart LR
user[Operator / Web2 User] --> frontend[Next.js Command Center]
frontend --> wallet[Injected Wallet
OKX / MetaMask] wallet --> mantle[Mantle Sepolia] frontend --> api[Next.js API Routes] api --> agent[Python Sentinel Agent] agent --> mantleRpc[Mantle RPC + Telemetry] mantleRpc --> registry[Mantle Sentinel Registry] agent --> llm[LLM Incident Analysis] llm --> decision{Confidence high?} decision -->|Yes| approval[Human Approval Gate] decision -->|No / Ambiguous| genlayer[GenLayer Consensus Guard
StudioNet] genlayer --> consensus[Validator Consensus Result] consensus --> approval approval --> action[Approved Emergency Action] action --> mantle subgraph Mantle_Execution_Network[Mantle Execution Network] mantle mantleRpc registry action end subgraph GenLayer_Validation_Layer[GenLayer Validation Layer] genlayer consensus end subgraph App_Layer[BreachResponse App Layer] frontend api agent llm approval end ``` ### 事件验证流程 ``` sequenceDiagram actor Operator participant UI as Command Center participant Agent as Python Sentinel Agent participant Mantle as Mantle Sepolia participant LLM as LLM Incident Analysis participant GenLayer as GenLayer Consensus Guard participant Approval as Human Approval Gate Operator->>UI: Connect wallet UI->>Mantle: Read protected protocols and wallet state Agent->>Mantle: Monitor RPC telemetry and sentinel registry Agent->>LLM: Submit incident evidence LLM-->>Agent: Threat class, confidence, proposed action alt High-confidence incident Agent->>Approval: Request operator approval else Ambiguous incident Agent->>GenLayer: Submit Mantle incident context GenLayer-->>Agent: Consensus decision Agent->>Approval: Present consensus-backed action end Operator->>Approval: Approve or reject Approval->>Mantle: Execute approved response action Mantle-->>UI: Updated protocol and sentinel status ``` 有关完整的系统设计和信任边界，请参阅[架构](./docs/ARCHITECTURE.md)。 ## 快速开始 ### 前置条件 - Node.js 22+ - Python 3.11+ - npm 10+ - Mantle Sepolia RPC 访问权限 ### 克隆 ``` git clone https://github.com/mystiquemide/breachresponse.git cd breachresponse cp .env.example .env ``` 使用您自己的本地或测试网值填充 `.env`。测试期间切勿使用生产环境的私钥。 ### 前端 ``` cd frontend npm ci npm run lint -- --max-warnings=0 npx tsc --noEmit npm run build npm run dev ``` 打开 http://localhost:3000。 ### 合约 ``` cd contracts npm ci npm run compile npm test ``` 合约测试涵盖了事件模型的两个方面： - 未受保护时，漏洞金库路径可能会被抽空 - 当哨兵暂停金库时，相同的攻击将回退 ### 代理 ``` cd agent python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python -m compileall -q . python main.py ``` ## 验证命令 在提交 PR 之前运行这些命令： ``` cd frontend npm ci npm run lint -- --max-warnings=0 npx tsc --noEmit npm run build npm audit --audit-level=moderate cd ../contracts npm ci npm run compile npm test npm audit --audit-level=moderate cd ../agent python -m compileall -q . ``` GenLayer 回退检查： ``` genvm-lint check contracts/genlayer/IncidentConsensusGuard.py --json python -m pytest tests/direct/test_incident_consensus_guard.py -q ``` ## 仓库结构 ``` agent/ Python monitoring and payload formulation agent contracts/ Solidity registry, target vault, attacker validation scenario, tests contracts/genlayer/ GenLayer intelligent contract fallback for consensus incident review frontend/ Next.js Command Center and API routes tests/direct/ GenLayer direct-mode tests docs/ Architecture, threat model, deployment, runbooks, roadmap .github/ CI, CodeQL, Dependabot, issue templates, PR template ``` ## 生产环境姿态 BreachResponse 专为可控部署而设计。人工审批是默认的响应模式。仅应针对限定范围的合约、上限操作、白名单 payload、紧急暂停功能和受监控的策略阈值启用自主执行。 请参阅[威胁模型](./docs/THREAT_MODEL.md)、[操作员手册](./docs/OPERATOR_RUNBOOK.md)和[部署](./docs/DEPLOYMENT.md)。 ## 许可证 MIT。详见 [LICENSE](./LICENSE)。
OKX / MetaMask] wallet --> mantle[Mantle Sepolia] frontend --> api[Next.js API Routes] api --> agent[Python Sentinel Agent] agent --> mantleRpc[Mantle RPC + Telemetry] mantleRpc --> registry[Mantle Sentinel Registry] agent --> llm[LLM Incident Analysis] llm --> decision{Confidence high?} decision -->|Yes| approval[Human Approval Gate] decision -->|No / Ambiguous| genlayer[GenLayer Consensus Guard
StudioNet] genlayer --> consensus[Validator Consensus Result] consensus --> approval approval --> action[Approved Emergency Action] action --> mantle subgraph Mantle_Execution_Network[Mantle Execution Network] mantle mantleRpc registry action end subgraph GenLayer_Validation_Layer[GenLayer Validation Layer] genlayer consensus end subgraph App_Layer[BreachResponse App Layer] frontend api agent llm approval end ``` ### 事件验证流程 ``` sequenceDiagram actor Operator participant UI as Command Center participant Agent as Python Sentinel Agent participant Mantle as Mantle Sepolia participant LLM as LLM Incident Analysis participant GenLayer as GenLayer Consensus Guard participant Approval as Human Approval Gate Operator->>UI: Connect wallet UI->>Mantle: Read protected protocols and wallet state Agent->>Mantle: Monitor RPC telemetry and sentinel registry Agent->>LLM: Submit incident evidence LLM-->>Agent: Threat class, confidence, proposed action alt High-confidence incident Agent->>Approval: Request operator approval else Ambiguous incident Agent->>GenLayer: Submit Mantle incident context GenLayer-->>Agent: Consensus decision Agent->>Approval: Present consensus-backed action end Operator->>Approval: Approve or reject Approval->>Mantle: Execute approved response action Mantle-->>UI: Updated protocol and sentinel status ``` 有关完整的系统设计和信任边界，请参阅[架构](./docs/ARCHITECTURE.md)。 ## 快速开始 ### 前置条件 - Node.js 22+ - Python 3.11+ - npm 10+ - Mantle Sepolia RPC 访问权限 ### 克隆 ``` git clone https://github.com/mystiquemide/breachresponse.git cd breachresponse cp .env.example .env ``` 使用您自己的本地或测试网值填充 `.env`。测试期间切勿使用生产环境的私钥。 ### 前端 ``` cd frontend npm ci npm run lint -- --max-warnings=0 npx tsc --noEmit npm run build npm run dev ``` 打开 http://localhost:3000。 ### 合约 ``` cd contracts npm ci npm run compile npm test ``` 合约测试涵盖了事件模型的两个方面： - 未受保护时，漏洞金库路径可能会被抽空 - 当哨兵暂停金库时，相同的攻击将回退 ### 代理 ``` cd agent python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python -m compileall -q . python main.py ``` ## 验证命令 在提交 PR 之前运行这些命令： ``` cd frontend npm ci npm run lint -- --max-warnings=0 npx tsc --noEmit npm run build npm audit --audit-level=moderate cd ../contracts npm ci npm run compile npm test npm audit --audit-level=moderate cd ../agent python -m compileall -q . ``` GenLayer 回退检查： ``` genvm-lint check contracts/genlayer/IncidentConsensusGuard.py --json python -m pytest tests/direct/test_incident_consensus_guard.py -q ``` ## 仓库结构 ``` agent/ Python monitoring and payload formulation agent contracts/ Solidity registry, target vault, attacker validation scenario, tests contracts/genlayer/ GenLayer intelligent contract fallback for consensus incident review frontend/ Next.js Command Center and API routes tests/direct/ GenLayer direct-mode tests docs/ Architecture, threat model, deployment, runbooks, roadmap .github/ CI, CodeQL, Dependabot, issue templates, PR template ``` ## 生产环境姿态 BreachResponse 专为可控部署而设计。人工审批是默认的响应模式。仅应针对限定范围的合约、上限操作、白名单 payload、紧急暂停功能和受监控的策略阈值启用自主执行。 请参阅[威胁模型](./docs/THREAT_MODEL.md)、[操作员手册](./docs/OPERATOR_RUNBOOK.md)和[部署](./docs/DEPLOYMENT.md)。 ## 许可证 MIT。详见 [LICENSE](./LICENSE)。
标签：Mantle, Python, 区块链安全, 库, 应急响应, 无后门, 智能合约审计, 自动化攻击, 逆向工具