cbomkit/sonar-cryptography
GitHub: cbomkit/sonar-cryptography
一个 SonarQube 插件，用于检测源代码中的加密资产并生成 CBOM（加密材料清单）。
Stars: 59 | Forks: 19
# Sonar 加密插件 (CBOMkit-hyperion)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/cbomkit/sonar-cryptography/releases)
此仓库包含一个 SonarQube 插件，用于检测源代码中的加密资产并生成 [CBOM](https://cyclonedx.org/capabilities/cbom/)。
它是 **[CBOMKit](https://github.com/cbomkit) 工具集**的一部分。
## 目录
- [版本兼容性](#version-compatibility)
- [支持的编程语言和库](#supported-languages-and-libraries)
- [安装](#installation)
- [使用](#using)
- [示例输出](#example-output)
- [构建](#build)
- [帮助和故障排除](#help-and-troubleshooting)
- [贡献指南](#contribution-guidelines)
- [许可证](#license)
## 版本兼容性
| 插件版本 | SonarQube 版本 |
|---------------|--------------------------------|
| 1.3.7 及以上 | SonarQube 9.9 (LTS) 及以上 |
| 1.3.2 和 1.3.6 | SonarQube 9.8 (LTS) 到 10.8 |
| 1.2.0 到 1.3.1 | SonarQube 9.8 (LTS) 到 10.4 |
## 支持的编程语言和库
| 编程语言 | 加密库 | 覆盖率 |
|----------|-------------------------------------------------------------------------------------|-----------------|
| Java | [JCA](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) | 100% |
| | [BouncyCastle](https://github.com/bcgit/bc-java) (*轻量级 API*) | 100%[^1] |
| Python | [pyca/cryptography](https://cryptography.io/en/latest/) | 100% |
| Go | [crypto](https://pkg.go.dev/crypto) (*标准库*) | 100%[^2] |
| | [golang.org/x/crypto](https://pkg.go.dev/golang.org/x/crypto) | 部分[^3] |
| C# | [System.Security.Cryptography](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography) | 开发中[^4] |
[^1]: 我们仅根据[此规范](https://javadoc.io/static/org.bouncycastle/bctls-jdk14/1.80/specifications.html)覆盖 BouncyCastle *轻量级 API*
[^2]: [`crypto`](https://pkg.go.dev/crypto@go1.25.6#section-directories)下的所有包都已覆盖，除了 `crypto/x509`
[^3]: 覆盖 `golang.org/x/crypto/hkdf`、`golang.org/x/crypto/pbkdf2` 和 `golang.org/x/crypto/sha3`
[^4]: C# 支持使用 [ANTLR v7 语法](https://github.com/antlr/grammars-v4/tree/master/csharp) 直接解析源文件。当前的 C# 支持仅涵盖语言支持，不包含除用于验证检测引擎的规则之外的检测规则。**这还不适合主动使用！****检测引擎的已知限制：** 无跨方法变量跟踪（仅单方法作用域），仅适用于 C# v7，基于字符串的匹配（无类型解析）
## 安装
将插件（[最新版本](https://github.com/cbomkit/sonar-cryptography/releases)中的 JAR 文件）复制到 `$SONARQUBE_HOME/extensions/plugins` 并重启
SonarQube（[更多](https://docs.sonarqube.org/latest/setup-and-upgrade/install-a-plugin/)）。
## 使用
该插件提供了新的库存规则（Cbomkit Cryptography Repository），涉及所支持编程语言中加密技术的使用。
如果启用这些规则，源代码扫描将通过创建包含所有加密资产的 [CBOM](https://cyclonedx.org/capabilities/cbom/) 来生成加密清单，并将 `cbom.json` 写入扫描目录。
### 将加密规则添加到您的质量配置文件中
此插件包含专门针对加密的规则。
截至当前版本，该插件包含一条用于创建加密清单的规则。未来更新可能会引入更多规则以扩展功能。
### 扫描源代码
现在您可以按照 [SonarQube 文档](https://docs.sonarqube.org/latest/analyzing-source-code/overview/) 开始您的第一次扫描。
### 可视化您的 CBOM
使用该插件扫描源代码并获得 `cbom.json` 文件后，您可以使用 [CBOMkit](https://github.com/cbomkit/cbomkit) 服务来了解更多相关信息。
它为您提供有关源代码中使用的加密技术及其后量子安全合规性的总体洞察。
它还允许您精确探索每个加密资产及其详细规范，并显示它在代码中的出现位置。
## 示例输出
该插件以 [CycloneDX CBOM 格式](https://cyclonedx.org/capabilities/cbom/) 生成 `cbom.json` 文件。以下是检测到的加密资产的示例：
```
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"version": 1,
"metadata": {
"timestamp": "2026-01-20T10:58:39Z",
"tools": {
"services": [
{
"name": "CBOMkit",
"provider": { "name": "PQCA" }
}
]
}
},
"components": [
{
"name": "SHA256",
"type": "cryptographic-asset",
"bom-ref": "0f4f522b-ef99-43b7-9f98-6e83b3b233ca",
"evidence": {
"occurrences": [
{
"line": 51,
"location": "src/main/java/com/example/EncryptionConfig.java",
"additionalContext": "java.security.MessageDigest#getInstance"
}
]
},
"cryptoProperties": {
"oid": "2.16.840.1.101.3.4.2.1",
"assetType": "algorithm",
"algorithmProperties": {
"primitive": "hash",
"cryptoFunctions": ["digest"],
"parameterSetIdentifier": "256"
}
}
},
{
"name": "AES128-GCM",
"type": "cryptographic-asset",
"bom-ref": "e006c3f1-912a-4de5-8399-79bf0f350cb9",
"evidence": {
"occurrences": [
{
"line": 29,
"location": "src/main/java/com/example/aes/AESGCM.java",
"additionalContext": "javax.crypto.Cipher#getInstance"
}
]
},
"cryptoProperties": {
"oid": "2.16.840.1.101.3.4.1",
"assetType": "algorithm",
"algorithmProperties": {
"mode": "gcm",
"primitive": "ae",
"cryptoFunctions": ["decrypt"],
"parameterSetIdentifier": "128"
}
}
},
{
"name": "RSA-OAEP",
"type": "cryptographic-asset",
"bom-ref": "ff238e09-dd3d-44c4-ad49-34350f1d9cc7",
"cryptoProperties": {
"oid": "1.2.840.113549.1.1.7",
"assetType": "algorithm",
"algorithmProperties": {
"mode": "ecb",
"padding": "oaep",
"primitive": "pke",
"parameterSetIdentifier": "2048"
}
}
}
],
"dependencies": [
{
"ref": "secret-key-ref",
"dependsOn": ["AES128-ref"]
}
]
}
```
CBOM 包括：
- **算法**：哈希函数、密码、密钥交换机制及其参数
- **密钥和密钥材料**：私钥、密钥材料和其他加密材料
- **证据**：检测到每个资产的源文件位置
- **依赖关系**：加密资产之间的关系（例如，密钥材料依赖于算法）
## 构建
```
# 构建（带测试）
mvn clean package
# 构建（不带测试，更快）
mvn clean package -DskipTests
# 构建特定模块
mvn clean package -pl java
# 格式化代码（Google Java Format，AOSP style）
mvn spotless:apply
# 检查格式化
mvn spotless:check
```
" 错误，针对 `crypto/hmac`、`crypto/elliptic` 或 `crypto/ecdsa` 等包，您需要添加缺失的包导出数据。
### 添加包的步骤
1. **生成包导出数据文件**（`.o` 文件）：
```
//go:build ignore
package main
import (
"fmt"
"go/importer"
"go/token"
"os"
"golang.org/x/tools/go/gcexportdata"
)
func main() {
fset := token.NewFileSet()
imp := importer.ForCompiler(fset, "gc", nil)
pkg, err := imp.Import("crypto/hmac") // <-- target package
if err != nil {
fmt.Fprintf(os.Stderr, "Error importing package: %v\n", err)
os.Exit(1)
}
file, err := os.Create("packages/crypto_hmac.o") // <-- output file
if err != nil {
fmt.Fprintf(os.Stderr, "Error creating file: %v\n", err)
os.Exit(1)
}
defer file.Close()
// CRITICAL: Pass nil for fset, NOT the fset used for import
if err := gcexportdata.Write(file, nil, pkg); err != nil {
fmt.Fprintf(os.Stderr, "Error writing export data: %v\n", err)
os.Exit(1)
}
fmt.Printf("Successfully created package export data for %s\n", pkg.Path())
}
```
使用 `go run gen_package.go` 运行，然后删除脚本。
2. **检查依赖关系**：某些包依赖于其他包中的类型。常见依赖：
| 包 | 可能需要 |
|---------|-------------|
| `crypto/hmac` | `hash` |
| `crypto/cipher` | `io` |
| `crypto/*`（大多数）| `io`、`hash` |
3. **按字母顺序添加映射条目**到 `mapping_generated.go`：
```
"crypto/hmac": "crypto_hmac.o",
```
4. **重新构建二进制文件**： `./make.sh build`
### 文件命名约定
| 包路径 | 导出数据文件 |
|--------------|------------------|
| `crypto/hmac` | `crypto_hmac.o` |
| `crypto/elliptic` | `crypto_elliptic.o` |
| `golang.org/x/crypto/bcrypt` | `x_crypto_bcrypt.o` |
## 帮助和故障排除
如果在安装 SonarQube 插件时遇到困难或意外结果，或在尝试扫描仓库时遇到问题，请查看我们的指南[*测试您的配置和故障排除*](docs/TROUBLESHOOTING.md)，按照分步说明运行我们的插件。
## 贡献指南
如果您想为 Sonar 加密插件做出贡献，请查看我们的[贡献指南](CONTRIBUTING.md)。参与即表示您同意遵守我们的[行为准则](CODE_OF_CONDUCT.md)。
我们使用 [GitHub issues](https://github.com/cbomkit/sonar-cryptography/issues) 跟踪请求和错误。如有问题，请使用 [GitHub Discussions](https://github.com/cbomkit/sonar-cryptography/discussions) 开始讨论。
## 许可证
[Apache 许可证 2.0](LICENSE.txt)
向 sonar-go-to-slang 添加包（Go 支持）
Go 加密检测依赖 [sonar-go-to-slang](https://github.com/SonarSource/sonar-go/tree/master/sonar-go-to-slang) 进行类型解析。默认二进制文件包含常见包，但某些加密包可能需要您使用额外的包导出数据重新构建它。 ### 何时需要？ 如果在类型检查期间看到 "undefined: \标签：BouncyCastle, CBOM, GHAS, Go安全, Java安全, JCA, JS文件枚举, Kafka, pyca/cryptography, SBOM, SonarQube插件, 云安全监控, 代码安全分析, 加密材料清单, 加密算法检测, 加密资产识别, 域名枚举, 安全审计工具, 密码学审计, 密码学检测, 日志审计, 硬件无关, 软件供应链安全, 远程方法调用, 逆向工具, 静态分析