https://github.com/cbomkit/sonar-cryptography
This repository contains a SonarQube Plugin that detects cryptographic assets in source code and generates CBOM.
https://github.com/cbomkit/sonar-cryptography
cbom cbom-tool cbomkit crypto-scanner cryptographic-inventory cryptography cryptography-bom post-quantum post-quantum-cryptography quantum-safe sbom sbom-tool sonar sonarqube
Last synced: about 1 month ago
JSON representation
This repository contains a SonarQube Plugin that detects cryptographic assets in source code and generates CBOM.
- Host: GitHub
- URL: https://github.com/cbomkit/sonar-cryptography
- Owner: cbomkit
- License: apache-2.0
- Created: 2024-06-10T07:41:48.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-26T21:56:09.000Z (about 2 months ago)
- Last Synced: 2026-01-28T04:46:28.639Z (about 2 months ago)
- Topics: cbom, cbom-tool, cbomkit, crypto-scanner, cryptographic-inventory, cryptography, cryptography-bom, post-quantum, post-quantum-cryptography, quantum-safe, sbom, sbom-tool, sonar, sonarqube
- Language: Java
- Homepage:
- Size: 37.7 MB
- Stars: 53
- Watchers: 5
- Forks: 17
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Sonar Cryptography Plugin (CBOMkit-hyperion)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/cbomkit/sonar-cryptography/releases)
This repository contains a SonarQube Plugin that detects cryptographic assets
in source code and generates [CBOM](https://cyclonedx.org/capabilities/cbom/).
It is part of **the [CBOMKit](https://github.com/cbomkit) toolset**.
## Table of Contents
- [Version compatibility](#version-compatibility)
- [Supported languages and libraries](#supported-languages-and-libraries)
- [Installation](#installation)
- [Using](#using)
- [Example Output](#example-output)
- [Build](#build)
- [Help and troubleshooting](#help-and-troubleshooting)
- [Contribution Guidelines](#contribution-guidelines)
- [License](#license)
## Version compatibility
| Plugin Version | SonarQube Version |
|-----------------|--------------------------------|
| 1.3.7 and up | SonarQube 9.9 (LTS) and up |
| 1.3.2 and 1.3.6 | SonarQube 9.8 (LTS) up to 10.8 |
| 1.2.0 to 1.3.1 | SonarQube 9.8 (LTS) up to 10.4 |
## Supported languages and libraries
| Language | Cryptographic Library | Coverage |
|----------|-----------------------------------------------------------------------------------------------|-------------|
| Java | [JCA](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) | 100% |
| | [BouncyCastle](https://github.com/bcgit/bc-java) (*light-weight API*) | 100%[^1] |
| Python | [pyca/cryptography](https://cryptography.io/en/latest/) | 100% |
| Go | [crypto](https://pkg.go.dev/crypto) (*standard library*) | 100%[^2] |
| | [golang.org/x/crypto](https://pkg.go.dev/golang.org/x/crypto) | Partial[^3] |
[^1]: We only cover the BouncyCastle *light-weight API* according to [this specification](https://javadoc.io/static/org.bouncycastle/bctls-jdk14/1.80/specifications.html)
[^2]: All packages under [`crypto`](https://pkg.go.dev/crypto@go1.25.6#section-directories) are covered except `crypto/x509`
[^3]: Covers `golang.org/x/crypto/hkdf`, `golang.org/x/crypto/pbkdf2`, and `golang.org/x/crypto/sha3`
> [!NOTE]
> The plugin is designed in a modular way so that it can be extended to support additional languages and recognition rules to support more libraries.
> - To add support for another language or cryptography library, see [*Extending the Sonar Cryptography Plugin to add support for another language or cryptography library*](./docs/LANGUAGE_SUPPORT.md)
> - If you just want to know more about the syntax for writing new detection rules, see [*Writing new detection rules for the Sonar Cryptography Plugin*](./docs/DETECTION_RULE_STRUCTURE.md)
## Installation
> [!NOTE]
> To run the plugin, you need a running SonarQube instance with one of the supported
> versions. If you don't have one but want to try the plugin, you can use the
> included Docker Compose to set up a development environment. See
> [here](CONTRIBUTING.md#build) for instructions.
Copy the plugin (the JAR file from the [latest releases](https://github.com/cbomkit/sonar-cryptography/releases))
to `$SONARQUBE_HOME/extensions/plugins` and restart
SonarQube ([more](https://docs.sonarqube.org/latest/setup-and-upgrade/install-a-plugin/)).
## Using
The plugin provides new inventory rules (Cbomkit Cryptography Repository) regarding the use of cryptography for
the supported languages.
If you enable these rules, a source code scan creates a cryptographic inventory by creating a
[CBOM](https://cyclonedx.org/capabilities/cbom/) with all cryptographic assets and writing
a `cbom.json` to the scan directory.
### Add Cryptography Rules to your Quality Profile
This plugin incorporates rules specifically focused on cryptography.
> To generate a Cryptography Bill of Materials (CBOM), it is mandatory to activate at
> least one of these cryptography-related rules.
As of the current version, the plugin contains one single rule for creating a cryptographic inventory.
Future updates may introduce additional rules to expand functionality.
### Scan Source Code
Now you can follow the [SonarQube documentation](https://docs.sonarqube.org/latest/analyzing-source-code/overview/)
to start your first scan.
### Visualizing your CBOM
Once you have scanned your source code with the plugin, and obtained a `cbom.json` file, you can use [CBOMkit](https://github.com/cbomkit/cbomkit) service to know more about it.
It provides you with general insights about the cryptography used in your source code and its compliance with post-quantum safety.
It also allows you to explore precisely each cryptography asset and its detailed specification, and displays where it appears in your code.
## Example Output
The plugin generates a `cbom.json` file in [CycloneDX CBOM format](https://cyclonedx.org/capabilities/cbom/). Here's an example showing detected cryptographic assets:
```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"]
}
]
}
```
The CBOM includes:
- **Algorithms**: Hash functions, ciphers, key exchange mechanisms with their parameters
- **Keys and secrets**: Private keys, secret keys, and other cryptographic materials
- **Evidence**: Source file locations where each asset was detected
- **Dependencies**: Relationships between cryptographic assets (e.g., a secret key depending on an algorithm)
## Build
```bash
# Build with tests
mvn clean package
# Build without tests (faster)
mvn clean package -DskipTests
# Build specific module
mvn clean package -pl java
# Format code (Google Java Format, AOSP style)
mvn spotless:apply
# Check formatting
mvn spotless:check
```
Adding packages to sonar-go-to-slang (Go support)
Go cryptographic detection relies on [sonar-go-to-slang](https://github.com/SonarSource/sonar-go/tree/master/sonar-go-to-slang) for type resolution. The default binary includes common packages, but some cryptographic packages may require you to rebuild it with additional package export data.
### When is this needed?
If you see "undefined: \" errors during type checking for packages like `crypto/hmac`, `crypto/elliptic`, or `crypto/ecdsa`, you need to add the missing package export data.
### Steps to add a package
1. **Generate the package export data file** (`.o` file):
```go
//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())
}
```
Run with `go run gen_package.go`, then delete the script.
> **CRITICAL**: The `gcexportdata.Write` call must pass `nil` for the `fset` parameter. Passing the same fset used for import will embed absolute file paths, causing runtime errors.
2. **Check for dependencies**: Some packages depend on types from other packages. Common dependencies:
| Package | May require |
|---------|-------------|
| `crypto/hmac` | `hash` |
| `crypto/cipher` | `io` |
| `crypto/*` (most) | `io`, `hash` |
3. **Add mapping entry** to `mapping_generated.go` in alphabetical order:
```go
"crypto/hmac": "crypto_hmac.o",
```
4. **Rebuild the binary**: `./make.sh build`
### File naming convention
| Package Path | Export Data File |
|--------------|------------------|
| `crypto/hmac` | `crypto_hmac.o` |
| `crypto/elliptic` | `crypto_elliptic.o` |
| `golang.org/x/crypto/bcrypt` | `x_crypto_bcrypt.o` |
## Help and troubleshooting
If you encounter difficulties or unexpected results while installing the plugin with SonarQube, or when trying to scan a repository, please check out our guide [*Testing your configuration and troubleshooting*](docs/TROUBLESHOOTING.md) to run our plugin with step-by-step instructions.
## Contribution Guidelines
If you'd like to contribute to Sonar Cryptography Plugin, please take a look at our
[contribution guidelines](CONTRIBUTING.md). By participating, you are expected to uphold our [code of conduct](CODE_OF_CONDUCT.md).
We use [GitHub issues](https://github.com/cbomkit/sonar-cryptography/issues) for tracking requests and bugs. For questions
start a discussion using [GitHub Discussions](https://github.com/cbomkit/sonar-cryptography/discussions).
## License
[Apache License 2.0](LICENSE.txt)