Kefmat/web3-guard-sentinel

# Web3-Guard Sentinel Web3-Guard Sentinel 是一款专为企业级区块链生态系统设计的静态应用安全测试 (SAST) 工具和软件组成分析 (SCA) 引擎。它通过比对实时的漏洞数据源来评估项目 lockfile 中的依赖项，并对 Solidity 智能合约执行基于模式的静态分析，从而在 DevSecOps pipeline 中实现自动化安全合规。 ## 系统架构与数据流 该引擎采用解耦的模块化设计，以最大化执行速度并保持严格的关注点分离。 ``` graph TD A[CLI Input / CI Pipeline] --> B(Sentinel Core Orchestrator) B --> C{Asset Discovery Engine} C -->|package-lock.json / package.json| D[SCA Dependency Audit Module] C -->|*.sol| E[Solidity Static Analysis Module] D --> F[Local Threat Registry Fallback] D --> G[Google Upstream OSV API Feed] E --> H[AST-Heuristic Line Tokenizer] F --> I[Unified Report Aggregator] G --> I H --> I I --> J[JSON Structural Export] I --> K[Markdown Compliance Log] I --> L[Interactive HTML Dashboard] I --> M{Policy Enforcement Engine} M -->|Breach Detected| N[Process Exit 1 / Break Build] M -->|Compliant| O[Process Exit 0 / Pass Build] ``` ## 模块分解 1. **Orchestrator Context** (`sentinel.ts`)：初始化核心服务，利用原生的跨平台参数解析功能 (util.parseArgs) 处理参数，并配置执行阈值。 2. **SCA Engine** (`scanner.ts`)：检测并解包完整的 package 依赖图，解析顶层 manifest 库以及嵌套的传递性子依赖，然后再运行异步查询。 3. **Upstream Broker** (`osvService.ts`)：与 Google 的 Open Source Vulnerability (OSV) API 数据库交互，以查询实时的安全公告。 4. **Solidity Parser** (`contractScanner.ts`)：按顺序读取智能合约源代码，以识别已知的漏洞反模式。 5. **Automation Compliance Reporter** (`fileReporter.ts`)：收集扫描结果，用于编排并生成简洁的 Markdown、JSON 以及主题隔离的单页 HTML dashboard。 ## 核心功能 - **传递依赖图分析**：解包完整的 lockfile 树（支持 package-lock.json v1、v2 和 v3 格式），以检测深层的、嵌套的以及隐藏的下游安全风险。 - **实时威胁情报**：通过高性能的 promise pool 设计，并发查询实时的分布式 CVE 和 GitHub Advisory (GHA) 数据源。 - **智能合约静态分析**：对原始 .sol 文件进行分词，以标记结构性漏洞、安全 bug 和设计反模式。 - **Pipeline 强制执行 (Policy-as-Code)**：支持严格的安全等级阈值 (--fail-on HIGH)，以便在引入严重风险时中断自动化的 CI/CD 构建。 - **零依赖 Runtime 映射**：使用纯现代 ECMAScript Modules (ESM) 和 Node.js 核心 API 原生运行，以实现最佳的安全性和效率。 ## Solidity 检测向量 智能合约扫描器实现了逐行的模式匹配，以防范系统性的 Web3 攻击向量。 | 漏洞向量 | 严重程度 | 审计标记条件 | 风险上下文 | | --- | --- | --- | --- | | 重入漏洞 | CRITICAL | 在本地状态余额修改之前执行了底层 `call{value: ...}`。 | 违反了 Checks-Effects-Interactions 模式；允许状态重入以耗尽智能合约余额。 | | 不安全的访问控制 | HIGH | 在评估断言或条件守卫中使用了 `tx.origin`。 | 使管理功能暴露于钓鱼攻击和伪造来源的代理干预漏洞中。 | | 过时的编译器规范 | MEDIUM | 使用了已弃用的编译器版本（例如 `^0.4.x`、`^0.5.x`、`^0.6.x`）。 | 使 bytecode 容易受到已知的、历史性的、未修复的编译器级别处理 bug 的影响。 | ## 执行演示与可视化 Dashboard ## 快速开始 ### 前置条件 - Node.js v20.0.0 或更高版本 - TypeScript v5.0.0 或更高版本 ### 安装说明 克隆代码仓库并安装开发者依赖： ``` git clone https://github.com/Kefmat/web3-guard-sentinel.git cd web3-guard-sentinel npm ci ``` ### 运行 在本地编译并运行该工具： ``` npm run build && npm start ``` ### 示例：强制执行 HIGH 严重程度 ``` node dist/sentinel.js --fail-on HIGH ``` ## 持续集成 (DevSecOps) 该工具经过优化，可在 CI 环境中运行。它会在每次 `push` 或 `pull_request` 时自动生成 artifact 合规性输出。 ``` sequenceDiagram autonumber participant Developer as Dev / Git Push participant Runner as GitHub Actions Runner participant Tool as Web3-Guard Sentinel participant API as Live OSV API Developer->>Runner: Trigger Pipeline (.github/workflows) Runner->>Runner: Check out code & Build Environment Runner->>Tool: Execute (node dist/sentinel.js --dir ./ --fail-on HIGH) Tool->>API: Query Transitive Package Matrix (POST) API-->>Tool: Stream Live Vulnerability JSON Tool->>Tool: Execute Solidity Structural Static Analysis Tool->>Runner: Output JSON, Markdown, and HTML Dashboard Artifacts alt Vulnerability Weight >= Policy Threshold Tool->>Runner: Terminate Execution (Exit Code 1) Runner-->>Developer: Build Failed / Deployment Blocked else Clean / Compliant Run Tool->>Runner: Terminate Execution (Exit Code 0) Runner-->>Developer: Build Passed / Deployment Authorized end ```

标签：DevSecOps, MITM代理, Web3, 上游代理, 智能合约审计, 自动化攻击, 静态应用安全测试