# shorproof
[](https://www.npmjs.com/package/shorproof)
[](https://github.com/shorproof/shorproof/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/shorproof)
[](./LICENSE)
[](./package.json)
`shorproof` 旨在找出你项目中的**易受量子攻击的密码学技术** —— 即一旦大规模量子计算机问世，便会被 [Shor's algorithm](https://en.wikipedia.org/wiki/Shor%27s_algorithm) 破解的 RSA、ECDSA、ECDH 及椭圆曲线相关用法 —— 并为你指明 NIST 的后量子替代方案（ML-KEM / FIPS 203，ML-DSA / FIPS 204）。
它会扫描**源代码、依赖项、JWT/JWKS 以及 PEM/X.509 密钥材料**，并以文本、JSON、**SARIF**（GitHub 代码扫描）或 **CycloneDX 1.6 CBOM** 的格式输出检测报告。
**为什么它与众不同：** 优先关注 auth/JWT、**具备绑定感知能力**（追踪真实的 import，而不是仅仅寻找名为 `jwt` 的变量）、**几乎零依赖**（确切地说是两个），且其设计确保每一条发现都能经得起密码学家的审查 —— **不制造恐慌，从设计上杜绝误报。** 它甚至会告诉你哪些方面你*已经*做对了：ML-KEM / ML-DSA 的使用会被报告为 `safe` ✓。
## 快速开始
```
# 无需安装
npx shorproof # scan the current project
npx shorproof ./api # scan a specific directory
# 输出格式
npx shorproof --json # stable machine-readable JSON
npx shorproof --format sarif # SARIF 2.1.0 for GitHub code scanning
npx shorproof --format cbom # CycloneDX 1.6 Cryptographic BOM
# CI gating
npx shorproof --fail-on high # exit 1 on any high+ finding
npx shorproof --strict # shorthand for --fail-on high
```
或者将其添加为 dev dependency：
```
npm install --save-dev shorproof
```
要求 Node.js **≥ 20.12**（已在 20、22、24 版本上测试）。
## 示例
```
shorproof v0.1.0 — post-quantum readiness scanner
Scanned /srv/api
CRITICAL (1)
keys/tls.key RSA-2048
keys/tls.key:1
RSA is broken by Shor's algorithm… This is stored private-key material.
→ Migrate to ML-DSA (FIPS 204) for signatures and ML-KEM (FIPS 203)…
HIGH (2)
sign(payload, key, { algorithm: 'RS256' }) RS256
src/auth/token.ts:42
RS256 signs with RSA, which Shor's algorithm breaks…
→ ML-DSA via jose ≥ v6 or Node 24.7+
SAFE (1)
new SignJWT(...).setProtectedHeader({ alg: 'ML-DSA-65' }) ML-DSA-65
src/auth/pq.ts:8
ML-DSA (FIPS 204) is a NIST post-quantum signature standard — already quantum-safe.
1 critical · 2 high · 1 safe
```
## 扫描范围
| 扫描器 | 检查目标 | 检查方式 |
| --- | --- | --- |
| **deps** | `package.json` 依赖项 | 精选的加密包知识库 |
| **ast** | JS/TS 源码 | 采用 Babel AST，**具备绑定感知能力** —— 以解析出的 import 为基准（涵盖任何别名、`require`、命名空间、动态 `import()`），并在报告前确认是否存在易受攻击的*实际使用* |
| **artifacts** | JWKS/JWK、PEM 密钥、X.509 证书 | 使用原生的 `node:crypto` 解析；有效期超过 ~2030 年的证书会被提升风险等级 |
AST 扫描器覆盖了 Node `crypto`（sign/verify、`generateKeyPair`、ECDH、DH、`publicEncrypt`/`privateDecrypt`）、**WebCrypto** `crypto.subtle.*`，以及 JWT 技术栈 —— `jsonwebtoken`、`jose`（包括 `SignJWT` 构建器）和 `express-jwt` —— 它通过常量传播来解析算法选项，并能识别出 **ML-DSA-44/65/87 已经属于后量子密码**。仅仅导入一个加密库本身绝不会被视为一项发现。
## GitHub Action（代码扫描）
上传 SARIF，以便将检测结果直接显示在仓库的 **Security → Code scanning（安全性 → 代码扫描）** 标签页以及 PR 中。在 [`examples/github-action.yml`](./examples/github-action.yml) 中提供了一个可以直接复制的工作流：
```
name: shorproof
on: [push, pull_request]
permissions:
security-events: write # required to upload SARIF
contents: read
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: npx shorproof@0.1 . --format sarif > shorproof.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: shorproof.sarif
```
## 将 shorproof 与 AI 编程代理结合使用
shorproof 的设计初衷不仅是供终端前的人类使用，还可以由 AI 编程代理（Claude Code、Cursor、Copilot、Aider 等）来驱动。当你要求你的代理执行类似 *"check this project for quantum-vulnerable crypto"（检查该项目中是否存在易受量子攻击的加密技术）* 的操作时，它可以运行一条命令并解析出稳定且机器可读的结果 —— 无需插件、无需 API 密钥、无需配置。
```
npx shorproof . --json
```
`--json` 输出是一个**有文档支持的稳定 schema**（参见 [JSON schema](#json-schema)）—— 代理可以读取 `summary` 获取审查结论，遍历 `findings` 查看每项检测结果的 `severity` / `file` / `line` / `why` / `migration`，并检查 `skipped` 以了解任何无法分析的内容。对于 CI 风格的强制门禁，代理可以依赖退出代码（`--fail-on high` → 退出代码 `1`）。
这是一个非常有效的 prompt（提示词）：
由于检测过程是**具备绑定感知且经过实际使用确认的**，因此代理获得的是有效信号而非噪音：导入 JWT 库不算是发现，`ML-DSA` 的使用会被判定为 `safe`，而注释中随意出现的 `"RS256"` 会被忽略。这可以防止代理去“修复”那些并没有损坏的东西。此外，在 [`llms.txt`](./llms.txt) 中还提供了一份单页的、机器可读的能力摘要。
## 严重性判定原则（求真务实部分）
严重性的判定基于**生命周期以及“先收割后解密”（HNDL）的暴露风险**，而不是刻意制造危机。同样容易被 Shor 算法破解的漏洞，其所带来的严重性可能截然不同：
- **critical** —— 保护着长效机密/签名的易受 Shor 算法破解的加密技术：存储数据的加密、有效期超过 2030 年的证书、JWKS 密钥、私钥文件。
- **high** —— 具有典型暴露风险的易受 Shor 算法破解的用法：JWT 签名（RS/ES/EdDSA）、与 TLS 相关的密钥材料。
- **medium** —— 受到量子*削弱*但仍可控的技术（例如由于 Grover 算法受到削弱的 AES-128 —— 请使用 AES-256），或者本身在传统意义上就已经很脆弱的算法（MD5/SHA-1 —— 实事求是地说：它们如今已经被破解了，这不是量子计算带来的问题）。裸露的 EC 密钥生成也归为此类。
- **review** —— 具备加密能力，但无法通过静态分析确认其实际使用情况的代码面。
- **safe** —— AES-256、SHA-256/SHA-3、bcrypt/argon2，以及 **ML-KEM/ML-DSA/SLH-DSA** —— 这些会被肯定地报告为“已经是后量子安全的 ✓”。
SHA-256 绝不会被标记为风险，对称加密也绝不会被视为已被 Shor 算法破解。每一项发现的 `why` 都是一句实事求是的话，且能够得到密码学家的认可。
## 输出格式
- **text**（默认）—— 按严重性分组，包含 file:line（文件:行号）、诚实的 `why` 以及具体的迁移提示。在非 TTY 环境或设置了 `NO_COLOR` 时会自动禁用颜色。
- **json** —— 稳定、有文档支持的 schema（见下文）；你可以将其视为公共 API。
- **sarif** —— SARIF 2.1.0 标准格式，便于 GitHub 代码扫描在 PR 上呈现检测结果。严重性会映射到 SARIF level 和 GitHub 的 `security-severity`；后量子/资产清单的检测结果仅作为参考信息，而非警报。
- **cbom** —— CycloneDX 1.6 加密物料清单 (Cryptographic Bill of Materials)：一份包含了 `algorithmProperties` 和 NIST 量子安全级别的完整清单（涵盖易受攻击的与后量子安全的算法）。已通过 CycloneDX 1.6 schema 的验证。
### JSON schema
```
{
"tool": "shorproof",
"version": "0.1.0",
"root": "/abs/scan/root",
"scanners": ["deps", "ast", "artifacts"],
"summary": { "critical": 0, "high": 2, "medium": 1, "review": 0, "safe": 1, "info": 0 },
"findings": [
{
"source": "ast", // "deps" | "ast" | "artifact"
"ruleId": "jsonwebtoken/rs256",
"severity": "high",
"category": "signature", // signature|kem|key-exchange|hash|symmetric|artifact
"algorithm": "RS256",
"title": "…", "why": "…", "migration": "…",
"confidence": "high", // high|medium|low
"lifetimeSensitive": true,
"location": { "file": "src/auth.ts", "line": 12, "column": 3 }
// source-specific: deps → package,range | ast → snippet | artifact → detail
}
],
// Files that could not be analyzed — unparseable, or a traversal error.
// Reported, never silently dropped; empty array when none.
"skipped": [{ "file": "vendor/bundle.js", "reason": "analysis error: Duplicate declaration \"x\"" }]
}
```
无法解析的文件，或者在进行 AST 遍历时抛出异常（例如在第三方或拼接打包的 bundle 中存在重复声明）的文件，都会被记录在 `skipped` 中并被明确展示出来 —— 体现在文本输出的页脚和这个 JSON 数组中 —— **绝不静默丢弃，也绝不导致扫描中止。** 一个无法分析的文件绝不能掩盖目录树中其他部分的检测结果。
## 退出代码
- `0` —— 检测干净，或者报告了检测结果但未达到 `--fail-on` / `--strict` 的阈值。
- `1` —— 发现了达到或超过 `--fail-on` 严重级别的检测结果（`--strict` = `--fail-on high`）。`safe` / `info` 级别永远不会导致运行失败。
- `2` —— 使用或 I/O 错误（比如错误的目录、未知的 `--format` / `--fail-on` 参数）。
## 为什么叫 "shorproof"？
Peter Shor 在 1994 年提出的算法是后量子密码学存在的根本原因：在足够大规模的量子计算机上，它能破解 RSA、Diffie-Hellman 以及椭圆曲线密码学 —— 而这正是当今大多数 TLS、JWT 和数字签名背后的数学基础。NIST 的替代标准（FIPS 203/204/205）已经定稿，迁移的最后期限也已确定（RSA/ECC 预计在 ~2030 年被弃用，~2035 年被彻底禁用），而每一次迁移都始于了解你项目中的脆弱加密技术究竟潜伏在何处。
这个工具正是为了迈出这第一步而生的。让你的代码做到 Shor-proof（防范 Shor 算法）。
## 更新日志
参见 [CHANGELOG.md](./CHANGELOG.md)。
## 许可证
[MIT](./LICENSE) © Usama Amjid