devbrewster/cveriskpilot-scan

# @cveriskpilot/scan Pipeline 合规扫描器 —— 扫描代码库中的有漏洞的依赖项、硬编码机密和基础设施即代码的错误配置，然后自动将发现结果映射到 **6 个合规框架**。 **零配置。离线优先。内置合规映射。** ## 快速入门 ### 从 npm 安装 ``` # 立即运行（无需安装——始终使用最新版本） npx --package @cveriskpilot/scan@latest crp-scan # 或者全局安装 npm install -g @cveriskpilot/scan@latest crp-scan cveriskpilot-scan # full name also works ``` ### 从 GitHub 安装 ``` git clone https://github.com/devbrewster/cveriskpilot-scan.git cd cveriskpilot-scan npm install npm run build # 扫描任意项目 node dist/cli.js /path/to/your/project # 或者全局链接 npm link crp-scan /path/to/your/project ``` ## 功能说明 1. 从四个维度对项目中的漏洞进行**扫描**： - **SBOM/SCA** — 检测 `package-lock.json`、`yarn.lock`、`requirements.txt`、`Cargo.lock`、`go.sum` 等文件中的有漏洞依赖项 - **机密** — 使用 30 多个正则表达式模式 + 熵检测，查找硬编码的 API 密钥、密码、私钥和 token - **IaC** — 检查 Terraform、Dockerfile、Kubernetes YAML 和 CloudFormation 中是否存在安全错误配置 - **API 路由** — 检测 API endpoint 上是否缺少身份验证、CSRF 保护和输入验证 2. 通过 CWE 将每项发现**映射**到合规控制项： 发现结果 → CWE → NIST 800-53 → SOC 2 / CMMC / FedRAMP / ASVS / SSDF 3. 使用免费的公开情报**丰富**每个 CVE： - **EPSS** — 利用预测评分系统概率 + 百分位数 (api.first.org) - **CISA KEV** — 包含联邦修复期限的已知被利用漏洞目录 - **风险评分** — 基于 CVSS + EPSS + KEV 的综合评分，范围 0-100 - **修复工作量** — 基于修复类型的启发式估算（低/中/高） 4. **报告**受影响的合规控制项，让您立即了解对审计的影响 ## 支持的框架 | 框架 | CLI ID | 别名 | 控制项数量 | |-----------|--------|---------|----------| | NIST 800-53 Rev 5 | `nist-800-53` | `nist`, `nist800` | 45 | | SOC 2 Type II | `soc2-type2` | `soc2`, `soc` | 7 | | CMMC Level 2 | `cmmc-level2` | `cmmc`, `cmmc2` | 33 | | FedRAMP Moderate | `fedramp-moderate` | `fedramp` | 35 | | OWASP ASVS 4.0 | `owasp-asvs` | `asvs`, `owasp` | 7 | | NIST SSDF 1.1 | `nist-ssdf` | `ssdf` | 8 | 通过 80 多个 CWE 条目映射了 **135 个控制项**。 ## 框架预设 | 预设 | 框架 | 适用对象 | |--------|-----------|-----| | `federal` | NIST 800-53 + FedRAMP + SSDF | 联邦机构 | | `defense` | NIST 800-53 + CMMC + SSDF | 国防承包商 | | `enterprise` | NIST 800-53 + SOC 2 + ASVS + SSDF | 企业 / 受监管行业 | | `startup` | SOC 2 + ASVS | SaaS 初创公司 | | `devsecops` | ASVS + SSDF | DevSecOps 团队 | | `all` | 所有 6 个框架 | 综合性扫描 | ## 用法 ``` # 扫描当前目录——所有框架，彩色表格输出 crp-scan # 扫描特定项目 crp-scan /path/to/your/project # 仅 SOC 2 + ASVS（startup 预设） crp-scan --preset startup # 仅 CMMC + FedRAMP（使用 aliases） crp-scan --frameworks CMMC,FEDRAMP # 仅限 HIGH 和 CRITICAL 发现 crp-scan --severity HIGH # 仅依赖项，JSON 输出 crp-scan --deps-only --format json # 排除测试文件和特定 CWE crp-scan --exclude test/** --exclude-cwe CWE-79,CWE-89 # CI/CD 模式（JSON 输出，critical 发现时 exit code 为 1） crp-scan --ci # 用于 GitHub/GitLab 集成的 SARIF 输出 crp-scan --format sarif > results.sarif # 将结果上传到 CVERiskPilot dashboard crp-scan --api-key $CRP_API_KEY # 列出所有框架、预设和 aliases crp-scan --list-frameworks # 国防承包商全面扫描 crp-scan --preset defense --fail-on high --verbose # 与上次扫描进行比较（显示新增/修复的 delta） crp-scan --compare # 以 NDJSON 流式传输 findings（用于管道传输至其他工具） crp-scan --stream # 增量扫描——仅扫描自某次 commit 以来更改的文件 crp-scan --since abc1234 # AI 驱动的修复（需要本地 Ollama 或 llama.cpp） crp-scan --ai # 使用特定模型的 AI crp-scan --ai --ai-model mistral # 具有明确 provider 和 URL 的 AI crp-scan --ai --ai-provider llamacpp --ai-url http://127.0.0.1:8080 ``` ## CLI 标志 ### 扫描器控制 | 标志 | 描述 | |------|-------------| | `--deps-only` | 仅运行 SBOM/依赖项扫描器 | | `--secrets-only` | 仅运行机密扫描器 | | `--iac-only` | 仅运行 IaC 扫描器 | ### 框架选择 | 标志 | 描述 | |------|-------------| | `--frameworks ` | 逗号分隔的框架 ID 或别名 | | `--preset ` | 框架预设：`federal`、`defense`、`enterprise`、`startup`、`devsecops`、`all` | | `--list-frameworks` | 显示所有框架、预设和别名 | ### 过滤 | 标志 | 描述 | |------|-------------| | `--severity ` | 最低严重级别：`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFO` | | `--exclude ` | 排除路径（可重复使用） | | `--exclude-cwe ` | 排除 CWE ID，逗号分隔（可重复使用） | ### 增量与比较 | 标志 | 描述 | |------|-------------| | `--since ` | 仅扫描自某个 git commit 以来更改的文件 | | `--compare` | 将结果与上次扫描进行比较并显示差异 | | `--stream` | 以 NDJSON（换行符分隔的 JSON）形式输出发现结果 | ### 输出 | 标志 | 描述 | |------|-------------| | `--format ` | `table`（默认）、`json`、`markdown`、`sarif` | | `--fail-on ` | 如果发现达到或超过指定严重级别则以状态码 1 退出（默认：`critical`） | | `--ci` | `--format json --fail-on critical` 的简写 | | `--verbose` | 显示详细的扫描器输出 | ### AI 丰富（离线 LLM） | 标志 | 描述 | |------|-------------| | `--ai` | 通过本地 LLM 启用 AI 驱动的修复建议 | | `--ai-provider ` | 强制指定提供商：`ollama`、`llamacpp`（默认自动检测） | | `--ai-model ` | 模型名称（默认：`llama3.2`） | | `--ai-url ` | LLM endpoint URL（必须是 localhost） | ### 上传（可选） | 标志 | 描述 | |------|-------------| | `--api-key ` | CVERiskPilot API 密钥（或 `CRP_API_KEY` 环境变量） | | `--api-url ` | API endpoint（或 `CRP_API_URL` 环境变量） | | `--no-upload` | 即使设置了 API 密钥也跳过上传 | ## 离线 AI 丰富 `--ai` 标志启用本地 LLM 驱动的分析。**数据不会离开您的机器。** ### 功能说明 - **修复指导** — 针对每项发现提供可操作的修复建议 - **高管风险摘要** — 供 CISO 查阅的安全态势评估 - **优先级排序** — 根据修复紧迫性对发现结果进行排名 ### 安全架构 - **仅限 Localhost** — 客户端验证所有请求都发送到 `127.0.0.1`、`localhost` 或 `::1`。非回环 URL 将被拒绝。 - **数据最小化** — 在 LLM 推理之前对发现结果进行脱敏处理（路径仅保留基本名称，移除原始观察结果，截断代码片段） - **零依赖** — 使用原生的 `fetch()` (Node.js 20+)，不依赖第三方 HTTP 库 - **时间预算** — AI 阶段有 120 秒的时间限制，超时时返回部分结果 - **零开销** — 动态导入确保在不使用 `--ai` 时不会产生性能影响 ### 支持的 LLM 服务器 | 服务器 | 安装方式 | 默认 URL | |--------|---------|-------------| | [Ollama](https://ollama.com) | `curl -fsSL https://ollama.com/install.sh \| sh && ollama pull llama3.2` | `http://127.0.0.1:11434` | | [llama.cpp](https://github.com/ggerganov/llama.cpp) | 从源代码构建，运行 `./llama-server -m model.gguf` | `http://127.0.0.1:8080` | ### 示例 ``` # 安装并启动 Ollama ollama pull llama3.2 # 使用 AI 增强进行扫描 crp-scan --ai --verbose # 使用不同的模型 crp-scan --ai --ai-model mistral # 在自定义端口上强制使用 llama.cpp crp-scan --ai --ai-provider llamacpp --ai-url http://127.0.0.1:9090 ``` ## 免费风险情报 每次扫描都会自动使用免费的公开数据丰富 CVE 发现 —— 无需 API 密钥，无需账户，完全免费。 ### 您将获得 - **EPSS 评分** — CVE 在未来 30 天内被利用的概率（0-1）及其百分位排名 - **CISA KEV** — CVE 是否在已知被利用漏洞目录中，及其联邦修复期限 - **风险评分** — 综合评分 0-100：`CVSS 基础分 (0-50) + EPSS (0-30) + KEV 加成 (+20)` - **修复工作量** — 启发式估算：补丁更新 = 低，次要更新 = 中，主要更新/无修复 = 高 - **合规计分卡** — 每个框架的控制项覆盖率可视化进度条 - **风险优先级** — 根据综合风险评分排名的前 10 项发现 - **KEV 截止日期警报** — 显示剩余天数的紧急警告 - **POAM 预览** — 针对首要发现结果的行动计划与里程碑 ### 扫描比较 随时跟踪您的安全态势： ``` # 首次扫描保存 baseline crp-scan /path/to/project # 下次扫描显示 delta crp-scan --compare /path/to/project # 输出：Findings: 15 → 12 (-3), Critical: 2 → 1 (-1) ``` ### 增量扫描 仅扫描自特定 commit 以来更改的文件： ``` crp-scan --since HEAD~5 crp-scan --since abc1234 ``` ### 流式输出 以 NDJSON 形式输出发现结果，以便通过管道传递给其他工具： ``` crp-scan --stream | jq 'select(.severity == "CRITICAL")' ``` ### 性能 - **OSV 响应缓存** — 磁盘缓存，24 小时 TTL（干净）/ 1 小时 TTL（有漏洞），避免冗余 API 调用 - **带退避的重试** — 所有网络调用（OSV、EPSS、KEV）在失败时使用指数退避加抖动进行重试 - **非阻塞丰富** — EPSS 和 KEV 并行获取；如果 API 无法访问，丰富过程不会导致致命错误 ## 输出格式 所有格式均打印到 **标准输出**。重定向到文件以保存结果： ``` # 保存 JSON 结果 crp-scan --preset startup --format json > scan-results.json # 保存 SARIF 以用于 GitHub Code Scanning 上传 crp-scan --format sarif > results.sarif # 保存 Markdown 以用于 PR 评论 crp-scan --format markdown > compliance-report.md # 通过管道将 JSON 传给 jq 以进行快速查询 crp-scan --format json | jq '.complianceImpact.frameworkSummary' ``` ### 表格（默认） 带有严重性徽章、每项发现的合规控制映射以及合规影响摘要的彩色终端输出。自动适应您的终端宽度 —— 信息不会被截断。 每项发现显示： - 严重性徽章、判定结果和标题 - 文件位置、CWE ID 和扫描器类型 - 分类判定原因 - 映射的合规控制项（例如，`SOC 2 Type II:CC6.1, OWASP ASVS:V1.2`） ### JSON (`--format json`) 包含完整发现详情（包括 CWE/CVE ID）、严重性摘要、判定明细以及每个框架完整合规影响的结构化输出。非常适合 CI/CD 集成、仪表板和编程分析。 ### SARIF (`--format sarif`) 适用于 GitHub Code Scanning、GitLab SAST、Azure DevOps 和其他 SARIF 兼容工具的 SARIF 2.1.0 格式。 ### Markdown (`--format markdown`) 包含发现、合规影响和摘要的 Markdown 表格 —— 适合用于 PR 评论、Wiki 页面和文档。 ## 合规映射的工作原理 扫描器使用 **CWE 到合规桥接** 架构： 1. 在扫描期间，每项发现都会被标记 CWE ID 2. CWE 映射到 NIST 800-53 控制项（80 多个映射） 3. NIST 800-53 作为规范中枢，桥接到所有其他框架 4. 桥接表将大约 30 个关键 NIST 控制项映射到其对应的 CMMC、SOC 2、FedRAMP 和 ASVS 控制项 这意味着一次 SQL 注入发现 (CWE-89) 会自动体现为： - **NIST 800-53**: SI-10, SA-11 - **SOC 2**: CC8.1 - **CMMC**: SI.L2-3.14.1, CA.L2-3.12.1 - **FedRAMP**: SI-2, SA-11 - **ASVS**: V5.1, V1.1 ## 退出码 | 代码 | 含义 | |------|---------| | `0` | 通过 — 没有达到或超过失败阈值的发现 | | `1` | 失败 — 发现了达到或超过失败阈值的问题 | | `2` | 错误 — 扫描器错误（参数错误、目录缺失等 | ## 系统要求 - Node.js 20+ - 无外部依赖 —— 所有操作均在本地运行 ## GitHub Action ``` # .github/workflows/compliance.yml name: Compliance Scan on: [pull_request] permissions: contents: read pull-requests: write security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: devbrewster/cveriskpilot-scan@main with: preset: all fail-on: critical ``` ### Action 输入 | 输入项 | 描述 | 默认值 | |-------|-------------|---------| | `preset` | 框架预设：`federal`、`defense`、`enterprise`、`startup`、`devsecops`、`all` | `all` | | `fail-on` | 严重性阈值：`critical`、`high`、`medium`、`low` | `critical` | | `scanners` | 限制扫描器：`deps`、`secrets`、`iac`（逗号分隔） | 全部 | | `comment` | 将结果作为 PR 评论发布 | `true` | | `upload-sarif` | 将 SARIF 上传到 GitHub 安全选项卡 | `true` | | `exclude` | 要排除的 Glob 模式（逗号分隔） | | | `api-key` | 用于仪表板上传的 CVERiskPilot API 密钥 | | | `github-token` | 用于 PR 评论的 token（自动提供） | `GITHUB_TOKEN` | ### Action 输出 | 输出项 | 描述 | |--------|-------------| | `exit-code` | `0` = 通过，`1` = 失败 | | `total-findings` | 发现总数 | | `critical-count` | 严重级别计数 | | `controls-affected` | 受影响的合规控制项 | | `comment-id` | PR 评论 ID（如果已发布） | ## GitHub 安全选项卡 (SARIF) 当启用 `upload-sarif` 时，发现结果会自动显示在您仓库的 **Security > Code scanning**（安全 > 代码扫描）选项卡中。无需额外设置。 ## 合规徽章 将实时合规状态徽章添加到您的项目 README 中。该徽章会查询您组织的扫描结果并显示通过/失败状态。 ### 徽章示例 | 状态 | 徽章 | Markdown | |--------|-------|----------| | 通过 |  | `` | | 3 个高危 |  | `` | | 5 个严重 |  | `` | ### 用法 ```      ``` ### 查询参数 | 参数 | 值 | 默认值 | 描述 | |-----------|--------|---------|-------------| | `framework` | `nist`、`soc2`、`cmmc`、`fedramp`、`asvs`、`ssdf` | `all` | 过滤特定的合规框架 | | `style` | `flat`、`flat-square`、`for-the-badge`、`plastic` | `flat` | 徽章视觉样式 | ### 工作原理 1. 徽章 endpoint 根据严重性查询您组织未解决的发现结果 2. 返回 302 重定向到 shields.io 的 SVG 徽章 3. 徽章缓存 5 分钟以提升性能 4. 仅公开通过/失败状态 —— 不会泄露具体的发现详情 ## 预设 | 预设 | 框架 | |--------|-----------| | `federal` | NIST 800-53, FedRAMP | | `defense` | NIST 800-53, CMMC, FedRAMP | | `enterprise` | NIST 800-53, SOC 2, ASVS, SSDF | | `startup` | SOC 2, ASVS | | `devsecops` | ASVS, SSDF | | `all` | 所有 6 个框架 | ## 示例工作流 请参阅 [`action/examples/`](./action/examples/) 获取开箱即用的工作流文件： - **compliance-scan.yml** — 基础的 PR 合规关卡 - **defense-contractor.yml** — 使用严格阈值的 CMMC/国防预设 - **scheduled-audit.yml** — 每周自动审计并创建 Issue ## 文档 有关架构、扫描器、合规映射、CI/CD 模式和常见问题解答的完整深入指南，请参阅 **[完整指南](./docs/GUIDE.md)**。 ## 关于 由 [CVERiskPilot LLC](https://cveriskpilot.com) 构建 —— 100% 退伍军人创立，位于德克萨斯州。 Apache-2.0 许可证。

标签：AI风险缓解, API密钥检测, API密钥泄露, API路由安全, ASVS, CI/CD安全, CISA项目, CloudFormation, CMMC, CSRF防护, CVE, DevSecOps, Dockerfile, ECS, FedRAMP, GNU通用公共许可证, GPT, IaC安全, Llama, LNA, MITM代理, NIST 800-53, Node.js, npm包, SBOM, SOC 2, SSDF, StruQ, Terraform, TypeScript, 上游代理, 代码安全, 依赖扫描, 合规映射, 安全插件, 对抗攻击, 敏感信息检测, 数字签名, 暗色界面, 模型提供商, 漏洞枚举, 漏洞管理, 硬件无关, 硬编码密码, 离线优先, 管道合规扫描器, 自动化攻击, 输入验证, 配置缺陷, 零配置