pqc-scan

pqc-scan

盘点 JavaScript 或 TypeScript 代码库使用的加密算法，以及大型量子计算机能够破解其中哪些算法。

这是一份盘点和指引，不是合规证书。

pqc-scan 会读取源文件、package.json 和锁文件，以及代码库中记录的任何 TLS（传输层安全）配置。它会报告找到的每一种加密算法：使用的接口（Web Crypto、node:crypto 或某个库）、代码中注明的密钥长度、算法在代码中的位置，以及量子计算机能够破解的每种用途的迁移优先级。该报告遵循英国国家网络安全中心（NCSC）在其后量子迁移时间表中要求开展的发现工作：到 2028 年完成发现和计划，到 2031 年完成最高优先级的迁移，到 2035 年完成其余迁移。

它只读文件。它不会运行扫描到的任何内容，不读取环境变量，不会向任何地方发送数据，也没有遥测功能。零依赖；需要 Node 20 或更高版本。免费，命令行工具也始终免费：将来可能会推出托管报告（显示趋势和组织范围的视图），并读取相同的 JSON 文件；目前尚未开发任何相关功能。

安装

pqc-scan 是一个命令行工具。你需要在电脑上准备两样东西：

1. Node.js 20 或更高版本。 在终端中运行 node --version 检查（Windows 上可使用命令提示符、PowerShell 或 Windows 终端；macOS 或 Linux 上使用终端）。如果找不到该命令，或显示的版本低于 20，请从 https://nodejs.org 安装当前的 “LTS” 版本。在 Windows 上，安装程序是一个常规的 .msi 文件；接受默认设置，然后打开一个新的终端窗口，以便加载更改。
2. 扫描器。 最快捷的方式只需要 Node.js：直接从 npm 注册表运行，无需手动下载：

   npx @microtoll/pqc-scan path/to/your/app
   

   或者安装一次，然后就可以在任何位置将其作为 pqc-scan 调用：

   npm install -g @microtoll/pqc-scan
   

   如果你想先阅读代码，或在不使用注册表的情况下操作，可以通过以下两种方式之一从此代码库获取：
   • 下载：在代码库页面选择 Code → Download ZIP，然后将文件解压到方便的位置，例如 Windows 上的 C:\Tools\pqc-scan，或其他系统上的 ~/tools/pqc-scan。
   • 克隆，如果你已安装 git：

     git clone https://github.com/microtoll/pqc-scan.git
     

无需安装其他内容：扫描器没有依赖，因此不需要在其中运行 npm install，也无需配置、账号或网络连接即可运行。

运行

将它指向存放应用代码的文件夹（其中包含 package.json）。

在 Windows（PowerShell 或命令提示符）上，扫描器解压到 C:\Tools\pqc-scan，应用位于 C:\Code\my-app 时：

C:\Tools\pqc-scan\pqc-scan C:\Code\my-app

在 macOS 或 Linux 上：

node ~/tools/pqc-scan/bin/pqc-scan.mjs ~/code/my-app

它会打印简短摘要，并在当前所在文件夹中写入两个文件：pqc-scan.md 是要阅读的报告，pqc-scan.json 则供其他工具使用。摘要会告诉你这两个文件的路径：

pqc-scan: 6 quantum-vulnerable public-key uses in 5 files; 12 libraries; TLS groups not written down.
  272 files read; 1 High, 5 Medium, 0 Low; 2 to check by hand.
  Report: C:\Users\you\pqc-scan.md  (open it; read sections 1 and 3 first)
  JSON:   C:\Users\you\pqc-scan.json

使用任意编辑器或 Markdown 查看器打开 pqc-scan.md（Visual Studio Code 中可按 Ctrl+Shift+V 查看）。先看第 1 节“摘要”，再看第 3 节“优先事项”；其中每个 High 或 Medium 项都会指出对应的代码行，并说明原因。

若要将报告保存到其他位置，请指定文件名：--md C:\Reports\app.md，如果需要，还可指定 --json C:\Reports\app.json。如果你的测试不在名为 test、tests、spec 或 __tests__ 的文件夹中，请告诉扫描器测试文件路径中包含哪些文本，这样报告就能说明发现的代码中有多少是测试代码：--test-files self-check，可重复指定。

扫描中型应用只需几秒钟。如果你当前位于扫描器自己的文件夹中，. 表示“此文件夹”；--help 会列出所有选项：

node bin/pqc-scan.mjs --help
node bin/pqc-scan.mjs . --fail-on high      # exit 1 if anything is High (for CI)

容易让人遇到的问题：

• Windows 上出现“无法识别 node”：未安装 Node.js，或者安装程序运行前就打开了终端。请安装 Node.js，然后打开一个新终端。
• 路径中包含空格时需要加引号："C:\My Projects\app"。
• 什么都没找到？ 扫描器只读取 JavaScript 和 TypeScript（.js、.mjs、.cjs、.ts、.mts、.cts、.jsx、.tsx）、锁文件和 TLS 配置文件。它不会识别其他语言编写的代码（参见“它无法识别的内容”）。
• 它绝不会修改你的文件。 它只会读取这些文件，并且只写入你指定的报告文件。

全部选项：

选项	含义
dir	要扫描的文件夹（默认：当前文件夹）。
--write	将 pqc-scan.md 和 pqc-scan.json 写入当前文件夹：这是在终端中运行时的默认行为。
--md <file>	改为将人类可读的报告写入此文件。
--json <file>	将机器可读的报告（架构版本 1）写入此文件。
--cbom <file>	将 CycloneDX 1.6 加密物料清单（CBOM）写入此文件。
--test-files <text>	将路径中包含此文本的文件视为测试代码。可重复指定。
--fail-on high	如果存在任何 High 项，则以状态码 1 退出。
--fail-on medium	如果存在任何 High 或 Medium 项，则以状态码 1 退出。
--exclude <name>	跳过目录名或文件名，或跳过相对于 dir 的路径。可重复指定。绝不会读取 node_modules 和 .git。

在脚本或管道中，如果未指定 --json、--md 或 --cbom，Markdown 会输出到标准输出，不会写入磁盘；在终端中则会写入 pqc-scan.md 和 pqc-scan.json（只有在要求时才会写入物料清单）。退出代码：0 表示完成，1 表示达到 --fail-on 阈值，2 表示用法错误或读取错误。阈值会统计报告中的所有内容，包括测试代码；使用 --exclude 可排除某个目录。

在 GitHub Actions 中

permissions:
  contents: read
steps:
  - uses: actions/checkout@<commit>
  - uses: microtoll/pqc-scan@<commit>   # pin a full commit SHA
    with:
      fail-on: high                      # optional; empty never fails

此操作会在工作区中运行扫描器，将 Markdown 报告添加到作业摘要中，并将两份报告和物料清单作为名为 pqc-scan 的制品上传；然后，如果设置了 fail-on 且达到阈值，就会使作业失败。输入项：path、fail-on、exclude（每行一个名称）、json、md、cbom、job-summary、upload、artifact-name。输出项：high、medium、low、verdict、json、cbom。 运行器需要 Node 20 或更高版本；GitHub 托管的运行器已预装。

扫描内容

• Web Crypto：扫描 crypto.subtle 调用，并从最近的字面量中读取算法，包括后量子和混合算法名称 （ML-KEM-768、ML-DSA-65、X25519MLKEM768、MLKEM768-X25519）。
• node:crypto：哈希、HMAC、密码、密钥对、签名、Diffie– Hellman、公钥加密、PBKDF2、scrypt、HKDF 和随机数。
• 库：近 60 个已编目软件包（tweetnacl、libsodium、@noble 系列、jose、jsonwebtoken、bcrypt、crypto-js、web-push、openpgp 等），从 package.json、package-lock.json、yarn.lock 和 pnpm-lock.yaml 中识别；目录中有映射的库还会扫描其调用，以及 JSON Web Token（JWT）算法名称，例如 RS256。
• TLS：nginx、Apache、Caddy，以及 Node 的 tls 和 https 选项；检查是否启用了混合后量子密钥交换组。

无法读取的值（例如存储在变量中的算法名称）会报告为动态 — 请手动检查，绝不猜测。

优先级

只有公钥用途才会标记优先级：大型量子计算机可以破解 RSA、椭圆曲线和 Diffie–Hellman 密码学，但只能削弱对称密码和哈希。

• 高：用于封装数据的密钥协商或公钥加密。有人现在可以记录密文，以后再解密（“现在窃取，以后解密”）。考虑为新数据采用混合封装。
• 中：签名。只有在此类计算机出现后才能伪造，因此风险在于长期有效的签名。应制定计划，不要仓促行动。
• 低：会话密钥交换，包括未使用混合组的 TLS。暴露的是会话，而不是存档。

优先级是根据调用附近的词语（seal、encrypt、store 等与 session、tls、handshake 等）作出的启发式判断。若没有明显提示用途的词语，则标记为“高”，直至有人检查。每条记录都会说明是哪个词语决定了优先级。应由人员复核每条“高”优先级记录。

报告

• pqc-scan.json：清单，格式由 schema/pqc-scan.schema.json 描述（版本 1）。 路径为相对路径，使用正斜杠；扫描目录仅显示名称；对同一目录树进行两次扫描，结果只会在 scannedAt 上有所不同。
• pqc-scan.md：摘要、清单、优先级及建议考虑的替代方案、关于对称密码和哈希的说明（AES-128、SHA-1、MD5、3DES、ECB 模式、较弱的 PBKDF2 迭代次数）、依赖项、TLS、NCSC 三个里程碑中的后续步骤，以及扫描无法看到的内容。
• --cbom <file>：以 CycloneDX 1.6 格式输出同一份清单，作为密码材料清单，其格式适用于中央清单、供应商问卷或此类文件的查看器。

加密物料清单

CycloneDX 1.6 物料清单会将扫描发现的每种算法变体列为一个 cryptographic-asset 组件（AES-256-GCM、ECDH P-256、ML-KEM-768……），并填写名称所能确定的 CycloneDX 自有字段（原语、密钥大小或曲线、模式、所用函数、经典安全级别和 NIST 后量子安全级别），同时为每次使用记录一个出现项：文件、行、接口和调用，以及带有优先级的源代码行。Web Crypto API、node:crypto 和每个已编目的软件包都会作为 library 组件出现，并 提供 通过它们发现的资产；组件中包含软件包 URL（pkg:npm/…）和锁文件中记录的版本。每项 TLS 配置都是一个引用其密钥交换组的 protocol 资产，因此，服务器组列表中的 X25519 和 Web Crypto 调用中的 X25519 指向同一个资产。CycloneDX 没有对应字段的信息（扫描器的类别和类型、迁移优先级及其原因、迭代次数等字面参数、备注）会存放在名为 microtoll:pqc-scan:* 的属性中。物料清单不会包含 JSON 报告中没有的信息：它仅根据报告生成，其序列号根据自身内容计算得出（对同一代码树进行两次扫描，除时间戳和序列号外，物料清单完全相同），并会在元数据中保留这句话：这是清单和索引，并非合规证书。映射定义见 DESIGN.md §8.14，且每项输出都会在测试中根据已发布的 CycloneDX 架构进行验证。

面向编码 Agent

pqc-scan mcp 会通过标准输入和输出将扫描器作为模型上下文协议（MCP）服务运行，这样，Claude Code、Cursor 或任何其他 MCP 宿主中的编码 Agent 都能检查刚刚编写的加密代码。使用以下命令将其添加到 Claude Code，适用于每个项目：

claude mcp add pqc-scan --scope user -- npx -y @microtoll/pqc-scan mcp

如果不使用 --scope user，Claude Code 只会为运行该命令的文件夹注册此服务。新对话会使用它；已经打开的对话则不会。

其他任何宿主都可以将同一命令（npx -y @microtoll/pqc-scan mcp）作为 stdio 服务使用。它提供一个工具：

工具	功能
pqc_scan({ directory, exclude?, testFiles?, detail? })	扫描文件夹（绝对路径，或相对于宿主启动服务时所在的位置），并以紧凑 JSON 格式返回报告摘要。设置 detail: "full" 后，会返回 JSON 报告本身，即 --json 写入的同一份文档，但不带缩进。exclude 和 testFiles 均为列表，与同名选项相同。

摘要包含报告中的计数；按算法分组的所有待审查用法（具有优先级、无法识别算法，或带有备注的用法），以及针对这些用法的处理建议，并列出相应文件和行号，最紧急的排在最前；还会按算法统计其他所有用法。这是 Agent 实际处理的内容；在典型应用中，其大小约为完整报告的二十分之一，而完整报告可能会超过宿主对工具结果的限制（Claude Code 的限制约为 25,000 个 token）。如需获取大型代码库的完整报告，请扫描你修改过的文件夹，或使用 exclude。

该工具只读取文件：不会写入报告文件，也不会运行它扫描的任何内容；扫描器也不会向任何地方发送信息。结果会返回给发起请求的宿主，再由宿主传入 Agent 的上下文，而这些内容通常会到达 Agent 的模型提供商；完整报告包含它找到的源代码行作为证据，这些行本来就可由 Agent 读取；摘要则只包含文件和行号。若要扫描名称本身为 mcp 的文件夹，请运行 pqc-scan ./mcp。详情见 DESIGN.md §8.15。

该工具会通过规范中的行为提示（annotations）告知宿主相同信息：只读、不破坏任何内容、可安全重复调用、不会使用网络。它还带有一个简单标题：“列出代码库使用的加密技术”。宿主可以据此判断是否要在调用前征求用户同意（DESIGN.md §8.17）。

它无法看到的内容

• 任何不是 JavaScript、TypeScript、锁文件或 TLS 配置文件的内容：其他语言、二进制文件、操作系统、云密钥服务，以及网络调用背后的任何内容。
• 哪些文件实际运行。仅由服务从未加载的文件导入的库仍会出现在报告中。
• 框架自身的密码学实现，除非该框架已列入目录。
• 它查找位置没有写明的值：它会跟踪同一代码块中的 const，或追踪一次相对导入（不会通过工作区包的名称导入），除此之外不会追踪其他内容。函数参数遮蔽同名模块级常量，是已知的唯一一种可能导致误导的情况。
• 证据会按原样复制。 与密码学调用位于同一行的密钥会出现在报告中。请像对待报告所描述的代码那样对待这份报告。

开发

npm test

使用 node:test，没有框架，也没有依赖项。每个发现的误报都会成为 test/fixtures/ 下的一个测试样例，并添加一条测试。设计和所有已确定的细节都记录在 DESIGN.md 中；安全问题请通过 SECURITY.md 报告。

构建方式与支持

该扫描器由 Claude Code（Anthropic 的编码 Agent）根据创始人编写并确定的设计构建；创始人阅读并接受了每一项更改。检查内容均可在此查阅：设计、真实代码形式的测试样例、测试，以及 DESIGN.md §8 中记录的真实代码库人工审查。审查发现的每个误报都已转化为一项测试。

命令行工具免费使用，并将一直免费。如果它为你节省了时间，可以在 GitHub 上赞助这项工作。

许可证

Apache-2.0。请参阅 LICENSE。