ABSatVPS/nsap-ci

# NSAP-CI NSAP-CI 是一个基于 Docker 的 GitHub Action，用于基于源码的 Solidity 安全扫描。 它在 CI 中运行 NSAP 快速扫描，输出 SARIF/Markdown/JSON 报告，计算 SHA-256 执行哈希值，并在验证后的漏洞发现达到或超过配置的严重性阈值时，使拉取请求（pull request）失败。 NSAP-CI 不能替代人工审计员。它是一个可重现的审计前关卡，旨在在易受攻击的代码进入 `main` 分支之前捕获基于源码的问题。 ## 它的功能 - 在 GitHub Actions 中扫描 Solidity 源码 - 从代码中提取基于源码的事实 - 运行快速扫描验证层 0–2 - 输出用于 GitHub 代码扫描的 SARIF 2.1.0 - 生成 Markdown 和 JSON 报告 - 计算 SHA-256 执行哈希值 - 根据可配置的严重性阈值使 CI 失败 ## 快速安装 添加到您的 `.github/workflows/security.yml`： ``` name: NSAP Security Gate on: pull_request: branches: [main] jobs: nsap: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run NSAP-CI uses: ./ with: source-dir: contracts fail-on: high - name: Upload SARIF if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: nsap-reports/nsap-results.sarif ``` ## 60 秒演示 该仓库包含两个冒烟测试固件： | 固件 | 预期结果 | |---|---| | `VulnerableBank.sol` | 2 个发现，SARIF 有效，退出代码 1 | | `CleanToken.sol` | 0 个发现，SARIF 有效，退出代码 0 | | `UncheckedArithmetic.sol` | 发现漏洞，SARIF 有效，退出代码 >= 0 | | `AccessControl.sol` | 0 个发现，SARIF 有效，退出代码 0 | 存在漏洞的固件演示了 `tx.origin` 和访问控制相关的发现。 无漏洞固件演示了通过扫描的情况。 有关包含确切命令的完整演练，请参阅 [DEMO.md](DEMO.md)。 ## 示例输出 ``` [Layer 0] Extracting semantic facts from source... [Gate 0] Validated [Layer 1] Checking invariants... [Layer 2] Scanning for known vulnerability patterns... [Promotion] Validated findings: 2 SARIF saved to nsap-reports/nsap-results.sarif Execution hash: sha256: [FAIL] Finding NSAP-001 severity high meets or exceeds fail-on threshold high exit: 1 ``` ## 它不包含的功能 NSAP-CI MVP 不是： - 专业智能合约审计的替代品， - 托管的 SaaS 平台， - AI/LLM 审计员， - 完整的形式化验证系统， - 深度的符号执行流水线， - v0.1 版本中的 PoC 生成产品， - 对已扫描合约安全性的保证。 ## MVP 范围 当前的 MVP 仅运行 NSAP 快速扫描： | 层级 | 状态 | |---|---| | 第 0 层：Rust tree-sitter 事实提取 | 已启用 | | 关卡 0：结构验证 | 已启用 | | 第 1 层：不变量检查 | 已启用 | | 第 2 层：基于源码的模式匹配 | 已启用 | | 第 1b 层：Z3 SMT | 未来路径 | | 第 1.5 层：Mythril | 未来路径 | | 第 2.5 层：Slither | 未来路径 | | 第 3 层：Julia BigInt 算术 | 未来路径 | | 第 4 层：PoC 生成 | 未来路径 | ## 路线图 计划的未来路径工作： - Marketplace 发布 - 深度扫描模式 - 可选的 Z3/Mythril/Slither/Julia 集成 - PoC 生成与验证 - 面向认证的报告 - 额外的智能合约语言支持 ## 验证状态 | 检查项 | 状态 | |---|---| | 存在漏洞的合约 + `fail-on=high` 退出代码为 1 | 通过 | | 存在漏洞的合约 + `fail-on=critical` 退出代码为 0 | 通过 | | 无漏洞合约 + `fail-on=high` 退出代码为 0 | 通过 | | 空目录退出代码为 1 | 通过 | | SARIF 2.1.0 验证 | 通过 | | 发现的问题基于源码 | 通过 | | 存在 SHA-256 执行哈希值 | 通过 | | MVP 演示验证通过 | 通过 | | 无私有路径泄露 | 通过 | | 深度扫描标记为超出范围 | 通过 | ## 工作原理 ``` Solidity source → Layer 0: Rust tree-sitter semantic fact extraction → Gate 0: Structural validation → Layer 1: Invariant verification (8 curated rules) → Layer 2: Source-grounded pattern matching → Finding promotion (co-location based confidence) → SARIF 2.1.0 + Markdown + JSON reports → SHA-256 execution hash → Severity threshold decision → exit code ``` ## 输出文件 全部写入工作区的 `nsap-reports/` 目录： | 文件 | 格式 | 用途 | |------|--------|---------| | `nsap-results.sarif` | SARIF 2.1.0 | 上传至 GitHub 代码扫描 | | `audit_report.md` | Markdown | 包含证明轨迹的易读摘要 | | `audit_report.json` | JSON | 完整的机器可读报告 | ## 严重性阈值 | `--fail-on` | 当发现的严重性为...时 CI 失败 | |---|---| | `critical` | `critical` | | `high` | `high` 或 `critical` | | `medium` | `medium`、`high` 或 `critical` | | `low` | `low`、`medium`、`high` 或 `critical` | ## 执行哈希 每次运行都会输出一个根据报告 payload 确定性计算的 SHA-256 哈希值。相同的输入（仓库 commit + 容器摘要 + 工具链版本）会产生相同的哈希值。 ## 支持的语言 - **Solidity** (>=0.8.0，已测试至 0.8.28) ## 环境要求 - **Docker** — 用于 GitHub Action 容器执行 - **Solidity** — >=0.8.0 ## 许可证 MIT

标签：GitHub Actions, SARIF, Solidity, 区块链安全, 可视化界面, 智能合约审计, 自动笔记, 请求拦截, 错误基检测, 静态代码分析