jimbo111/open-quantum-secure
GitHub: jimbo111/open-quantum-secure
一款后量子密码学扫描器，用于检测代码库中的量子脆弱算法，生成量子准备度评分和 CBOM，并验证 CNSA 2.0 合规性。
Stars: 2 | Forks: 1
# Open Quantum Secure (OQS Scanner)
一款后量子密码学扫描器，用于查找代码库中的密码学算法使用情况，并告知在量子计算机破解之前需要更改的内容。
它会生成量子准备度评分 (0-100)，输出 CycloneDX 1.7 CBOM，并检查是否符合 CNSA 2.0 标准。
无需后端支持。完全离线运行。
## 入门指南
### 步骤 1：安装扫描器
```
# 下载预构建二进制文件 (推荐)
curl -sSL https://raw.githubusercontent.com/jimbo111/open-quantum-secure/main/install.sh | sh
# 或使用 Go 安装
go install github.com/jimbo111/open-quantum-secure/cmd/oqs-scanner@latest
# 或从源代码构建
git clone https://github.com/jimbo111/open-quantum-secure.git
cd open-quantum-secure
go build -o oqs-scanner ./cmd/oqs-scanner/
```
### 步骤 2：检查可用功能
```
oqs-scanner engines doctor
```
开箱即用，您将获得编译进二进制文件的 **2 个内置引擎**：
| 引擎 | 扫描内容 | 始终可用 |
|--------|--------------|-----------------|
| **config-scanner** | YAML, JSON, .env, .properties, TOML, XML, INI, HCL 配置文件 | 是（嵌入式） |
| **binary-scanner** | JAR/WAR, Go 二进制文件, Python wheels, ELF/PE/Mach-O, .NET assemblies | 是（嵌入式） |
这两个引擎无需安装其他任何东西即可扫描配置文件和二进制制品。
### 步骤 3：安装额外引擎（可选）
为了进行源代码扫描，您需要外部引擎。这些是扫描器调用的**独立开源工具** —— 由于许可限制，它们并未打包在内。
```
# 安装 ast-grep (基于 Rust，支持 12 种语言的模式匹配)
cargo install ast-grep
# 或：npm install -g @ast-grep/cli
# 安装 semgrep (基于 Python，污点/数据流分析)
pip install semgrep
# 安装 syft (基于 Go，容器/二进制 SBOM 生成)
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh
# 安装 cdxgen (基于 Node.js，CycloneDX SBOM 生成)
npm install -g @cyclonedx/cdxgen
```
再次运行 `oqs-scanner engines doctor` 进行验证。您不需要安装所有引擎 —— 只需安装适合您技术栈的即可。
### 步骤 4：扫描
```
oqs-scanner scan --path .
```
输出：
```
Scanning /your/project with 4 engine(s)...
• ast-grep (tier pattern)
• semgrep (tier flow)
• binary-scanner (tier binary)
• config-scanner (tier pattern)
Scan completed in 1.2s — 37 findings
Total: 37 findings (28 algorithms, 8 dependencies)
Quantum: 6 vulnerable, 0 weakened, 10 safe/resistant, 0 deprecated
Quantum Readiness Score: 88/100 (Grade: A)
```
## 引擎工作原理
扫描器是一个 **orchestrator（编排器）** —— 它协调外部工具，并通过一个 12 阶段的流水线（标准化、去重、分类、影响分析、评分）合并它们的结果。
```
┌──────────────────────────────────┐
│ oqs-scanner CLI │
│ (orchestrator, Go, MIT license) │
└──────────┬───────────────────────┘
│ calls via subprocess
┌────────────────────┼────────────────────────┐
│ │ │
┌──────┴──────┐ ┌────────┴──────┐ ┌────────────┴────────────┐
│ Built-in │ │ Optional │ │ Optional │
│ (embedded) │ │ (install) │ │ (install) │
├─────────────┤ ├───────────────┤ ├─────────────────────────┤
│config-scanner│ │ cipherscope │ │ semgrep (taint/flow) │
│binary-scanner│ │ cryptoscan │ │ cdxgen (SBOM) │
│ │ │ ast-grep │ │ cbomkit-theia(artifacts)│
│ │ │ syft │ │ │
│ │ │ cryptodeps │ │ │
└─────────────┘ └───────────────┘ └─────────────────────────┘
```
每个引擎都是具有独立许可证的独立项目。扫描器从不打包或重新分发它们 —— 而是在运行时从 PATH 或 `~/.oqs/cache/engines/` 发现它们。
## 理解量子准备度评分 (QRS)
QRS 范围从 0 到 100：
| 分数 | 等级 | 含义 |
|-------|-------|---------|
| 95-100 | A+ | 完全具备量子准备度，无易受攻击算法 |
| 85-94 | A | 极少量子风险 |
| 70-84 | B | 存在部分易受攻击算法，迁移进行中 |
| 50-69 | C | 重大量子风险，需要迁移 |
| 30-49 | D | 高量子风险，许多易受攻击算法 |
| 0-29 | F | 关键量子风险，需立即采取行动 |
惩罚基于量子风险类别和严重性按发现项应用。经证实的发现项（被多个引擎检测到）会受到更高的惩罚。PQC 安全算法会带来少量加分。
## 输出格式
```
oqs-scanner scan --path . --format table # Human-readable table (default)
oqs-scanner scan --path . --format json # Machine-readable JSON
oqs-scanner scan --path . --format sarif # GitHub Code Scanning / IDE integration
oqs-scanner scan --path . --format cbom # CycloneDX 1.7 CBOM
oqs-scanner scan --path . --format html # Self-contained HTML report
```
## CNSA 2.0 合规性
根据 NSA 的 CNSA 2.0 要求检查您的代码库：
```
oqs-scanner scan --path . --compliance cnsa-2.0
```
这将标记不符合 CNSA 2.0 的算法：
- SLH-DSA（尽管是 NIST 标准但仍被排除）
- 低于 1024 的 ML-KEM，低于 87 的 ML-DSA
- SHA-256（要求最低 SHA-384）
- 低于 256 的 AES，任何非 AES 密码
- HQC（尚未获 CNSA 2.0 批准）
生成正式的合规报告：
```
oqs-scanner compliance-report --path . --output report.md
```
## CI/CD
### GitHub Actions
```
name: PQC Scan
on: [pull_request]
permissions:
security-events: write
pull-requests: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: jimbo111/open-quantum-secure@main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
path: '.'
format: 'sarif'
upload-sarif: 'true'
pr-comment: 'true'
compliance: 'cnsa-2.0'
ci-mode: 'advisory'
```
### GitLab CI
```
include:
- remote: 'https://raw.githubusercontent.com/jimbo111/open-quantum-secure/main/.gitlab-ci-template.yml'
oqs-scan:
extends: .oqs-scanner
variables:
OQS_FORMAT: "sarif"
OQS_COMPLIANCE: "cnsa-2.0"
```
### CI 模式
- `blocking` — 出现策略违规时退出码为 1（默认）
- `advisory` — 打印警告但始终退出码为 0（用于在不破坏 CI 的情况下进行导入）
- `silent` — 无策略输出，始终退出码为 0
## 仪表板
在本地查看扫描历史和趋势：
```
oqs-scanner dashboard
# 打开 http://localhost:8899
```
显示 QRS 随时间变化的趋势、发现项细目、HNDL 紧迫性、合规状态、迁移工作量估算，以及带有文件路径和行号的逐项发现详情。所有数据本地存储在 `~/.oqs/history/` 中。
## CBOM 生成
生成签名后的 CycloneDX 1.7 密码学物料清单 (CBOM)：
```
oqs-scanner scan --path . --format cbom --output cbom.json
# 使用 Ed25519 签名 (用于来源/审计)
oqs-scanner scan --path . --format cbom --sign-cbom --output signed-cbom.json
```
## 关键标志
| 标志 | 描述 |
|------|-------------|
| `--compliance cnsa-2.0` | CNSA 2.0 合规性评估 |
| `--ci-mode advisory` | 非阻塞 CI 模式 |
| `--sign-cbom` | Ed25519 CBOM 签名用于来源验证 |
| `--data-lifetime-years 30` | 针对长效数据调整 HNDL 紧迫性（医疗保健=30，金融=7） |
| `--webhook-url https://...` | 将结果 POST 到 ITSM（Jira, ServiceNow） |
| `--fail-on critical` | 如果发现项达到或超过指定严重级别则退出码为 1 |
| `--scan-type binary` | 仅扫描二进制制品 |
| `--incremental` | 使用本地缓存跳过未更改的文件 |
| `--exclude "vendor/**"` | 通过 glob 模式跳过目录 |
| `--remote-cache` | 跨 CI 运行共享扫描缓存（需要平台支持） |
## 其他命令
```
oqs-scanner diff --path . --base main # Scan only changed files (PR mode)
oqs-scanner trends --project my-org/my-repo # QRS trend analysis
oqs-scanner history --project my-org/my-repo # Scan history
oqs-scanner compliance-report --path . --output report.md # CNSA 2.0 report
oqs-scanner engines list # List all engines
oqs-scanner engines doctor # Check engine availability
oqs-scanner version # Version and engine status
```
## 支持的标准
- NIST CNSA 2.0（2030 年前完成密钥交换，2035 年前完成签名）
- FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), FIPS 205 (SLH-DSA)
- HQC（NIST 第 5 个 PQC 标准，2025 年 3 月）
- KCMVP（韩语：ARIA, SEED, LEA, KCDSA, HAS-160, LSH）
- K-PQC 第 4 轮（SMAUG-T, HAETAE, AIMer, NTRU+）
- CycloneDX 1.7 CBOM
- SARIF 2.1.0
## 贡献
欢迎提交 Pull Request。提交前请运行 `go test -race ./...`。需要 Go 1.25+。
## 许可证
MIT
标签：CBOM, CNSA 2.0, CycloneDX, DevSecOps, ECC, EVTX分析, Go, Golang, PQC, RSA, Ruby工具, SBOM, Semgrep, Syft, WordPress安全扫描, 上游代理, 二进制分析, 云安全监控, 云安全运维, 代码扫描器, 加密算法识别, 后量子密码学, 域名收集, 安全编程, 密码学漏洞检测, 开源安全工具, 日志审计, 硬件无关, 离线安全工具, 网络安全, 跌倒检测, 软件物料清单, 逆向工程平台, 配置文件扫描, 量子安全, 量子计算, 隐私保护, 静态分析