Davinci-lab/BridgeGuard

# BridgeGuard 防护 **面向跨链桥系统的防御性运行时安全内核。** BridgeGuard v2 是一个本地优先的运营者控制台与 API，用于模拟桥接事件、检查运行时不变量、评估风险以及生成可解释的决策。它保留了原始的 v1 模拟端点，同时新增了身份验证、项目隔离、事件监听器、告警、策略校准、连接器发现以及签名合规报告等功能。 ## v2 功能集 - 基于 FastAPI v2 的身份验证 API，支持 JWT 登录/注册和 `/api/v2/auth/me` 端点。 - 项目范围的多租户支持，涵盖模拟、决策、告警、监听器、策略配置和报告。 - 项目仪表盘，包含近期决策、告警状态、监听器状态和 v2 模拟流程。 - 多链连接器框架，支持 EVM、Solana 和 Cosmos 连接器类型。 - EVM 自动发现端点，提供已验证 ABI 方法映射建议。 - 基于 Celery/Redis 的监听器基础架构，支持轮询或 WebSocket 连接器事件。 - 针对高风险决策的 Slack、邮件和 Webhook 告警规则。 - 支持风险权重和自定义表达式规则的策略校准。 - 生成带数字签名验证的 PDF 决策报告。 - TailwindCSS/shadcn 风格的前端组件。 - Docker Compose 部署栈，包含 PostgreSQL、Redis、后端、Celery 工作进程和 Nginx 前端。 - 用于后端 pytest 和前端类型检查/构建的 GitHub Actions 工作流。 ## 向后兼容性 原始 v1 API 已被有意保留： - 根 v1 端点仍然可用，包括 `/health`、`/simulate`、`/simulate-attack/{name}`、`/decisions`、`/metrics`、`/reason-codes` 和 `/connectors`。 - 同样的 v1 路由也可通过 `/api/v1` 访问。 - v2 路由位于 `/api/v2` 下，项目范围内的操作需要身份验证。 - 前端保留了一个 **v1 工具** 部分，用于历史回放、风险指标、旧连接器存储、近期 v1 决策以及原因代码参考。 - 现有的本地 `backend/connectors.json` 文件可继续与旧连接器端点配合使用。 ## 快速开始 最快的方式是使用 Docker： ``` docker compose up --build ``` 打开： - 前端：`http://localhost:3000` - 后端健康检查：`http://localhost:8000/health` - API 文档：`http://localhost:8000/docs` Alembic 种子数据迁移会创建一个演示账户： ``` Email: demo@bridgeguard.local Password: bridgeguard-demo Project: Demo Bridge Operations ``` 有关引导式操作指南，请参阅 [快速入门指南](QUICKSTART.md)。 ## Docker 配置 部署栈包含： - `db`：PostgreSQL 16 - `redis`：Redis 7 - `backend`：启动时执行 Alembic 迁移的 FastAPI 应用 - `celery`：用于处理监听器和告警任务的 BridgeGuard 工作进程 - `frontend`：提供生产构建 React 应用并代理 API 路由的 Nginx 服务 常用命令： ``` docker compose up --build docker compose ps docker compose logs -f backend docker compose down ``` 重置数据库卷： ``` docker compose down -v docker compose up --build ``` ## 手动配置 后端： ``` cd backend python -m pip install -r requirements.txt alembic upgrade head python -m pytest tests python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` 前端： ``` cd frontend npm install npm.cmd exec tsc -- --noEmit npm.cmd run build npm start ``` 可选的本地服务，用于支持 v2 监听器/告警工作流： ``` redis-server cd backend celery -A app.tasks.celery_app worker --loglevel=info ``` 环境变量： ``` DATABASE_URL=sqlite:///./bridgeguard.db DATABASE_URL=postgresql://bridgeguard:bridgeguard@localhost:5432/bridgeguard CELERY_BROKER_URL=redis://localhost:6379/0 CELERY_RESULT_BACKEND=redis://localhost:6379/1 ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000 SECRET_KEY=change-this-in-real-deployments ``` ## API 概览 v1 示例： ``` curl http://127.0.0.1:8000/health curl http://127.0.0.1:8000/attacks curl -X POST "http://127.0.0.1:8000/simulate-attack/Ronin%20Bridge" ``` v2 身份验证： ``` curl -X POST http://127.0.0.1:8000/api/v2/auth/register ` -H "Content-Type: application/json" ` -d "{\"email\":\"operator@example.com\",\"password\":\"bridgeguard-demo\",\"project_name\":\"Ops\"}" curl -X POST http://127.0.0.1:8000/api/v2/auth/login ` -H "Content-Type: application/x-www-form-urlencoded" ` -d "username=operator@example.com&password=bridgeguard-demo" ``` v2 项目范围请求使用： ``` Authorization: Bearer X-Project-ID: ``` ## 连接器 BridgeGuard 支持连接器注册表，包含： - EVM 连接器 - Solana 连接器模拟 - Cosmos 连接器模拟 - 配置文件发现 - 通过 `POST /api/v2/connectors/discover` 进行 Etherscan ABI 发现 默认的演示连接器配置存储在： ``` backend/app/sample_data/default_connectors.json ``` 用户创建的旧版连接器存储在： ``` backend/connectors.json ``` ## 测试 后端： ``` cd backend python -m pytest tests ``` 前端： ``` cd frontend npm.cmd exec tsc -- --noEmit npm.cmd run build ``` CI 在推送和拉取请求时会运行相同的后端和前端检查。 ## 谁在使用 BridgeGuard？ BridgeGuard 面向桥接运营者、审计方、保险公司以及评估运行时桥接监控的 DeFi 安全研究人员开放。 如果在试点项目、审计流程、研究项目或保险风险评估中使用了 BridgeGuard？请提交 issue 或讨论以在此处列出。 ## 防御边界 BridgeGuard 是纯防御性的： - 不涉及私钥 - 不进行交易签名 - 不包含漏洞利用载荷 - 不涉及实际资金移动 - 不保证绝对安全 - 不暴露内部的专有桥接逻辑 有关报告指南和安全使用须知，请参阅 [安全说明](SECURITY.md)。 ## 风险模型 风险模型是确定且可解释的。v2 增加了项目级别的权重校准和自定义表达式规则，但运营者必须在使用真实操作数据进行校准后才能用于生产环境。 请参阅 [风险模型文档](RISK_MODEL.md)。 ## 商业用途 如需托管服务、企业功能或定制集成，请通过 [邮箱/网站] 联系我们。 ## 数据来源 历史事件库仅用于防御性模拟和产品演示。 | 事件 | 参考链接 | | --- | --- | | Ronin Bridge | https://nomoslabs.io/archive/ronin-bridge-2022 | | Wormhole | https://www.halborn.com/blog/post/explained-the-wormhole-hack-february-2022 | | Nomad | https://nomoslabs.io/archive/nomad-bridge-2022 | | Harmony Horizon | https://techcrunch.com/2022/06/24/harmony-blockchain-crypto-hack/ | | BNB Token Hub | https://www.nansen.ai/research/bnb-chains-cross-chain-bridge-exploit-explained | | Poly Network | https://www.cnbc.com/2021/08/11/cryptocurrency-theft-hackers-steal-600-million-in-poly-network-hack.html | | Multichain | https://www.coindesk.com/tech/2023/07/07/multichain-team-confirms-exploit-across-fantom-moonriver-and-dogechain-bridges | | THORChain 近期事件 | https://blog.thorchain.org/post-mortem-eth-router-exploits-1-2-and-premature-return-to-trading-incident/ | | Orbit Chain | https://rekt.news/orbit-chain-rekt/ | | Socket/Bungee | https://rekt.news/socket-rekt/ | | Heco Bridge (HTX) | https://rekt.news/htx-heco-bridge-rekt/ | | Mixin Network | https://rekt.news/mixin-network-rekt/ | | LI.FI 协议 | https://rekt.news/lifi-rekt/ | | Celer cBridge DNS 劫持 | https://blog.celer.network/2023/08/18/celer-cbridge-dns-hijack-incident/ | | Kelp DAO rsETH Bridge | https://rekt.news/kelp-dao-rekt/ | | Shibarium Bridge | https://rekt.news/shibarium-bridge-rekt/ | | Nervos Force Bridge | https://rekt.news/nervos-force-bridge-rekt/ | | Verus Ethereum Bridge | https://blockchain.news/verus-ethereum-bridge-exploited | | NoOnes Solana Bridge | https://www.gate.com/news/noones-8m-cross-chain-bridge-exploit | ## 状态 BridgeGuard v2.0.0 是一个稳定的开源防御性版本，适用于演示、内部评审、原型运营工作流和商业评估。它不能替代独立的审计、针对特定桥接的威胁建模或生产事件响应控制措施。 ## 许可证 本项目基于 MIT 许可证授权 – 详情请参阅 LICENSE 文件。

标签：AV绕过, Celery, FastAPI, JWT, Nginx, PostgreSQL, Redis, TailwindCSS, 不变检查, 前端组件, 区块链安全, 合规报告, 后端API, 多链支持, 多链连接器, 安全内核, 安全决策, 开源安全工具, 搜索引擎查询, 模拟工具, 测试用例, 策略校准, 自动发现, 警报系统, 认证API, 请求拦截, 跨链桥安全, 跨链监控, 连接器框架, 逆向工程平台, 风险评分