MarianoFacundoArch/nist-csf-evidence-gap-analysis-tool

# NIST CSF 2.0 — AI 辅助证据与差距分析工具 一个免费的开源工具，帮助任何组织衡量其 现有的安全实践在多大程度上符合美国国家网络安全 标准 —— NIST Cybersecurity Framework (CSF) 2.0 —— 并准确指出 差距所在。 ## 目的与意义 网络安全是美国公认的国家优先事项：对 企业、医院、学校、公用事业和地方政府的攻击会造成严重的 经济和公共损害。为了帮助组织管理这一风险，美国 政府的 National Institute of Standards and Technology (NIST) 发布了 Cybersecurity Framework (CSF) 2.0 —— 这是一个通用的、广泛使用的国家标准， 定义了组织应当实现的 106 项网络安全结果。（“结果” 是组织应当能够展示的具体成果 —— 例如， 保持其硬件清单的最新状态。） 在实践中，组织实际如何保护自身的证据 散布在数十或数百份文档中 —— 安全策略、程序、 审计报告、标准和内部记录，通常分散在不同的 团队和系统中。即使对于受过培训的专家来说，手工阅读所有这些内容并将每项证据与 NIST 框架中正确的结果进行匹配也是费时费力、缓慢且 容易出错的。这是采用该标准的 主要实际障碍。 本项目旨在解决这一障碍。它会根据 NIST CSF 2.0 定义的所有 106 项结果，自动审查组织 自己的文档，定位 支持性证据和差距，并生成清晰的报告 —— 从而加速即使是经验丰富的安全专家也感到 繁重的工作。由于它是免费的、 对所有人开放，并且可以完全在用户自己的计算机上运行，敏感 文档永远不必离开内部场所。这使得任何组织都能切实可行地生成一份严谨的、基于证据的概况，说明其目前相对于该标准所处的位置 —— 即框架所称的“Current Profile” —— 并使执行此项工作的专家的工作 更快、更一致。 更广泛、更一致地采用通用的网络安全基线，可以增强 更广泛的经济和关键公共服务的韧性。 为了保持其结果的可信度，该工具绝不会让 AI 拥有最终决定权： 每项发现都必须得到组织自己文档中确切引用的支持， 并且需要由人工逐一审查和确认。 ## 目录 - [目的与意义](#purpose-and-significance) - [功能说明](#what-it-does) - [工作原理](#how-it-works) - [安装说明](#install) - [快速开始（离线，无 API key）](#quick-start-offline-no-api-key) - [用法](#usage) - [Providers、隐私与离线模式](#providers-privacy-and-offline-mode) - [输出结果](#outputs) - [如何支持 CSF 2.0](#how-this-supports-csf-20) - [防幻觉保障](#anti-hallucination-safeguards) - [配置](#configuration) - [数据源（CPRT）](#data-source-cprt) - [局限性](#limitations) - [项目文档](#project-documentation) - [开源协议](#license) ## 功能说明 将该工具指向包含您的文档（安全策略、SOC 2 报告、 ISO 27001 文档、内部程序）的文件夹。随后它将： 1. **摄取**文档 —— 解析它们，将其拆分为重叠的 chunk， 计算 embeddings，并将所有内容存储在本地磁盘索引中。 2. **分析**覆盖情况 —— 对于 106 个 CSF 2.0 Subcategories 中的**每一个**， 它会检索最相关的文档 chunk，并询问 AI 引擎该证据是否表明该结果已实际达成。 3. **审查** —— 这是一个 human-in-the-loop（人工干预）步骤，您可以接受、推翻或批注 每项 AI 判断及其支持性证据。 4. **报告** —— 将审查后的评估结果转换为 Current Profile (JSON)、一份 差距分析报告（Markdown）和一张证据映射图（CSV）。 有关完整的分步演练，请参阅 **[使用指南](docs/GUIDE.md)**。 ## 工作原理 ### “反转 RAG” 与用户提问的方式不同，该工具会遍历所有 Subcategories，并且 针对每一个 Subcategory，检索距离最近的 top-k 个文档 chunk，并要求 AI **仅针对检索到的证据** 评估覆盖情况。Embeddings 经过 L2-normalized 处理，因此余弦相似度即为普通的点积，并且检索过程是 精确的内存扫描 —— 语料库仅为单个组织的文档，因此不需要外部 数据库或向量服务。 ### 关注结果，而非主题 CSF 2.0 Subcategories 是*结果*，而非控制项或主题。该工具会判断 证据是否表明某个结果已实际达成 —— 而不仅仅是提到了 该主题。规定某事“必须”发生的策略被视为 较弱的证据，低于表明其实际发生的记录。 ## 安装说明 要求 **Node.js >= 20.10**。 ``` git clone https://github.com/MarianoFacundoArch/nist-csf-evidence-gap-analysis-tool.git cd nist-csf-evidence-gap-analysis-tool npm install ``` `npm install` 会拉取两个必需的轻量级依赖（用于 schema 验证的 `ajv`， 以及用于交互式菜单的 `@clack/prompts`）。较重的 provider/解析器 依赖（`openai`、`@huggingface/transformers`、`mammoth`、`pdfjs-dist`）被 声明为**可选**，并且仅在实际使用相应的 provider 或 文件类型时才会加载。 要将该命令作为 `csf-tool` 全局运行，请执行 `npm link`。以下示例使用 `node bin/csf-tool.js`。 ## 快速开始（离线，无 API key） 使用确定性的 **mock** 引擎针对内置的示例文档运行整个 pipeline —— 无需网络，也无需 API key： ``` node bin/csf-tool.js all \ --docs examples/sample-docs \ --embed-provider mock --llm-provider mock \ --work-dir ./output --accept-all ``` 然后打开 `./output/reports/gap-analysis.md`。代码库中包含一份提交的参考副本，位于 `examples/worked-example/`，可以使用 `npm run example` 逐字节重新生成。 （`--accept-all` 会自动接受所有 AI 提议，以便演示能够无人值守运行； 真正的评估会改用人工审查步骤 —— 请参阅 [用法](#usage)。） ## 用法 有两种方式可以驱动该工具，它们共享**相同**的底层代码。 **交互式菜单**（不带命令运行 —— 它会引导您完成每个步骤）： ``` node bin/csf-tool.js ``` **命令模式：** ``` node bin/csf-tool.js init # scaffold a config file, .env, and working dir node bin/csf-tool.js ingest # parse + chunk + embed + index your documents node bin/csf-tool.js analyze # AI coverage judgments for all 106 Subcategories node bin/csf-tool.js review # human-in-the-loop validation node bin/csf-tool.js report # generate the three deliverables node bin/csf-tool.js all # run the whole pipeline end-to-end ``` 每个阶段都会保留其输出，因此您可以在任何阶段之后停止并在稍后恢复。 `analyze` 是可恢复的 —— 已经评估过的项目会被跳过，除非它们的输入 发生了更改（或者您传递了 `--force`）。运行 `--help` 查看所有 flag，并参阅 **[使用指南](docs/GUIDE.md)** 获取详细的演练。 ## Providers、隐私与离线模式 该工具是可插拔的。没有任何内容是硬编码的；您可以自行选择进行 embeddings 和 推理的位置。 - **Embeddings：** `local-transformers`（在设备端 —— 文档永远不会离开您的 机器）、`openai`（云端）或 `mock`（确定性，用于测试）。 - **推理 LLM：** `openai`（云端）、`ollama`（您自己机器上的完全本地模型）或 `mock`。 默认设置是云端优先（在 `.env` 中设置 `OPENAI_API_KEY`）。传递 **`--local`** 进行 完全离线运行（设备端 embeddings + 本地 Ollama 模型）；任何文档或 prompt 都不会离开该机器。离线路径需要 [Ollama](https://ollama.com)： 安装它，使用 `ollama serve` 启动，并首先拉取一个模型（例如 `ollama pull llama3.2`）。模型名称是可配置的；如果您未设置模型， 每个 provider 会自行解析出一个合理的默认值，并且 OpenAI provider 会自动适应不同代际的模型（例如 GPT-5 系列的参数 规范）。 ## 输出结果 写入至 `/reports/`： - **`current-profile.json`** —— 与 CSF 2.0 Organizational Profile 概念对齐的、机器可读的 Current Profile：每个 Subcategory 对应一个条目，包含覆盖情况 （`none` / `partial` / `substantial` / `full`）、置信度、证据引用、 AI 与人工的数值，以及审查状态。 - **`gap-analysis.md`** —— 按 Function 分组的人类可读报告，包含 覆盖情况摘要，并且**优先列出差距**。 - **`evidence-map.csv`** —— 将每个 Subcategory 链接到其源文件和逐字 引用（RFC-4180 引用格式，带有电子表格公式注入保护）。 差距分析报告的示例摘录： ``` ## 按功能的覆盖率 | Function | Total | None | Partial | Substantial | Full | % addressed | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | GOVERN | 31 | 16 | 15 | 0 | 0 | 0% | | IDENTIFY | 21 | 13 | 7 | 1 | 0 | 5% | ... ## 差距和部分覆盖（优先解决这些） ### IDENTIFY - **ID.RA-01** — _none_ - Outcome: Vulnerabilities in assets are identified, validated, and recorded - Rationale: The evidence shows asset inventory and access reviews, but does not demonstrate that vulnerabilities are identified, validated, and recorded. ``` ## 如何支持 CSF 2.0 - **全面覆盖 Framework Core。** 它评估完整的 CSF 2.0 Core —— 包括所有 6 个 Functions、22 个 Categories 和 106 个 Subcategories —— 并生成 Current Profile，这是 CSF 2.0 推荐用于了解当前 网络安全态势的产出物。 - **设计上确保准确性。** Subcategory 文本完全取自 官方的 NIST CPRT 导出文件（可通过 `npm run build-csf-core` 复现），每一项 AI 覆盖情况声明都必须有在代码中针对源证据逐字验证过的引用作为支持， 并且在人工验证之前，一切都不是最终结果。 - **免费且可重用。** MIT 许可协议；可根据需要在完全离线状态下运行；无需账户、 订阅或付费服务即可使用。 ## 防幻觉保障 AI 受到其 prompt 的约束，更重要的是受到代码的约束： - **受证据约束的 prompt。** 模型只能使用传递给它的证据， 绝不假设存在未见过的控制项，并将缺乏证据视为 `none`。 - **必须提供引用，否则无效。** 任何高于 `none` 的覆盖情况都必须包含至少 一段从证据中逐字复制的引用。 - **逐字验证（在代码中）。** 模型响应后，该工具会检查 每段引用是否确实作为检索到的证据的子串存在 （已进行空格/大小写规范化处理）且具有实质内容。如果高于 `none` 的覆盖情况声明没有可验证的引用，它将被**降级为 `none`** 并被标记。 这是权威的检查 —— 模型的引用绝不会在没有验证的情况下被盲目信任。 - **置信度阈值**会标记低置信度的判断以供审查。 - **schema 验证与优雅降级。** 模型输出会经过验证；遇到无效 输出时，该工具会重试一次，然后降级为 `none` + needs-review —— 它 绝不会崩溃。 - **强制人工审查。** 在每项交付物中都会清楚标记未审查/过时的项目，并且 **strict mode** 会拒绝输出最终 profile，直到每个 项目都经过审查。 ## 配置 优先级（从低到高）：内置默认值 < `csf-tool.config.json` < CLI flags。 密钥/endpoint 仅来源于 `.env`。运行 `csf-tool init` 以生成配置脚手架。 有关完整参考，请参阅 [使用指南](docs/GUIDE.md#11-configuration-reference)。关键字段：`csfCorePath`、`docsPath`、`workDir`、`chunk.size`/`overlap`、 `embeddings.provider`/`model`、`llm.provider`/`model`、`retrieval.topK`、 `analysis.confidenceThreshold`、`analysis.critique`、`analysis.strict`、 `review.showAll`。 ## 数据源（CPRT） `data/csf-core.json` 包含完整的 CSF 2.0 Core —— 涵盖 6 个 Functions 和 22 个 Categories 的所有 106 个 Subcategory 结果 —— 这是根据官方 NIST Cyberbersecurity and Privacy Reference Tool (CPRT) 导出文件生成的。CSF 2.0 Core 文本属于 公共领域。从源文件重新生成它（需要网络和 `unzip`）： ``` npm run build-csf-core ``` 要使用您自己的导出文件，请将 `csfCorePath` 指向一个具有相同结构的 JSON 文件 （请参阅 [使用指南](docs/GUIDE.md#10-use-the-full-framework--your-own-csf-export)）。 ## 局限性 - **无 OCR 功能（v1）。** 仅支持包含真实文本层的 PDF。 检测到扫描/纯图像 PDF 时会跳过并发出警告。 - **AI 是建议性的。** 其输出仅为建议；人工审查步骤是 强制性的。不要将未经审查的 profile 视为权威。 - **`mock` provider 并非真正的模型。** 它是确定性的，仅用于 测试和可重现的演示示例。 - **模型能力很重要。** 非常小的本地模型往往过于保守， 主要返回 `none`/`partial`；请使用较大的本地模型或当前的云端 模型以获得校准良好的覆盖情况。人工审查是确认覆盖情况的地方。 - **Embedding 模型一致性。** 如果您更改了 embedding 模型，请重新运行 `ingest` —— 不同模型的向量不能混合使用。 ## 项目文档 - [使用指南](docs/GUIDE.md) — 详细带有解释的演练。 - [CONTRIBUTING](CONTRIBUTING.md) — 开发环境设置及如何贡献。 - [CHANGELOG](CHANGELOG.md) — 发布说明。 - [AUTHORS](AUTHORS) — 维护者和贡献者。 - [NOTICE](NOTICE) — 数据来源和第三方许可协议。 ## 开源协议 MIT — 请参阅 [LICENSE](LICENSE)。免费且开源。

标签：AI风险缓解, MITM代理, NIST CSF, Petitpotam, 人工智能, 安全合规, 差距分析, 文档分析, 用户模式Hook绕过, 离线部署, 网络代理, 自定义脚本