bdd-cucumber-gherkin-lib-security-cve-core
The CVE scan of the dependencies of an application, without Cucumber.
This module scans archives (jar, war, ear) for libraries with known vulnerabilities and fails the build from a
given severity. It contains the scanner abstraction, the gate, the configuration objects, the Testcontainers based
Trivy implementation and a jUnit 5 extension. It has no dependency on Cucumber, on Spring, on
Spring Boot or on any other module of this library - the DAST scan (-security-core) included.
Projects that use the Gherkin sentences take bdd-cucumber-gherkin-lib-security-cve instead; this module comes in transitively.
Prerequisites
- Docker (Testcontainers pulls the scanner image)
- Network access to the vulnerability databases of the scanner - or another source for them, see Database sources
- JDK 25 - the published class files target the toolchain of this repository
Nothing else: no build plugin, no SBOM, no lock file. The archives come from the classpath of the running test JVM.
Gradle
dependencies {
testImplementation "io.github.ragin-lundf:bdd-cucumber-gherkin-lib-security-cve-core:${version.bdd-cucumber-gherkin-lib}"
}
Published dependencies: Jackson 3 jackson-databind, Testcontainers and kotlin-logging. junit-jupiter-api is
compileOnly and is not published, so the extension runs against whatever jUnit version the project already has.
How a scan runs
- Collect the archives: by default every archive on the classpath of the test JVM (
ScanArtifacts.classpath()), which are the dependencies of the application under test plus the test tooling. A pathing jar - the manifestClass-Paththat Maven Surefire and IntelliJ use for long classpaths - is followed. Directories are skipped.ScanArtifacts.resolve(paths)takes given archives or searches given directories instead, e.g.build/libs. - Start a short-lived Trivy container, copy the archives in and let it scan them. The vulnerability databases are downloaded into a named Docker volume, so only the first run pays for that.
- Copy Trivy’s raw JSON report out to the report directory.
- Drop ignored ids, excluded packages and - on request - unfixed vulnerabilities.
- Write the HTML report, then fail when a remaining vulnerability has a severity at or above the threshold. The report is written first, so a failing build has it too.
Severities: UNKNOWN < LOW < MEDIUM < HIGH < CRITICAL. UNKNOWN is an entry the database has not rated yet.
jUnit 5 extension
VulnerabilityScanExtension scans after the last test of the class and fails the class when a relevant
vulnerability reaches the threshold:
internal class DependencyVulnerabilityTests {
companion object {
private val properties = VulnerabilityScanProperties(
enabled = true,
// hand the report directory over - nothing in this module reads system properties
report = VulnerabilityReportProperties(outputDir = "build/reports/cve-scan")
)
@JvmField
@RegisterExtension
val cveScan = VulnerabilityScanExtension(
properties = properties,
scanner = TrivyVulnerabilityScanner(properties.scanner),
failFrom = VulnerabilitySeverity.HIGH
// artifacts = Supplier { ScanArtifacts.resolve(listOf(Path.of("build/libs"))) }
)
}
@Test
fun `dependencies are scanned after this class`() = Unit
}
The threshold is a constructor argument and not a property on purpose, so no profile can silently weaken the gate.
Without the extension, the same call is VulnerabilityScan(properties, scanner).scanAndVerify(artifacts, failFrom).
Configuration
VulnerabilityScanProperties - a plain data class. The Cucumber module binds it from cucumbertest.security.cve.
| Property | Default | Meaning |
|---|---|---|
enabled |
false |
Master switch; the scan is a no-op while false |
scanner.image |
aquasec/trivy:latest |
Scanner image |
scanner.timeout |
10m |
Budget for one scan, including the database download on a cold cache |
scanner.cache-volume |
bdd-cucumber-trivy-cache |
Docker volume that keeps the vulnerability databases between runs; empty mounts none - see Databases built into the image |
scanner.database.* |
public registries | Source of the vulnerability database - see Database sources |
scanner.java-database.* |
public registries | Source of the Java database - same keys |
scanner.registry-username / -password |
none | Login for private registries in repositories |
scanner.https-proxy |
none | HTTP(S) proxy for the scanner’s downloads; must be reachable from the container |
scanner.no-proxy |
none | Hosts reached without the proxy, comma separated |
vulnerabilities.ignored-ids |
empty | Advisory ids (CVE, GHSA) assessed as not exploitable |
vulnerabilities.ignore-unfixed |
false |
Ignore vulnerabilities without a released fix |
vulnerabilities.excluded-packages |
empty | group:artifact patterns, * matches any text - e.g. org.junit*:* |
report.output-dir |
. |
Directory of the reports - hand it over; nothing here reads system properties |
report.name-prefix |
vulnerability-report |
Start of every report file name |
Reports
Every scan has a name - dependencies by default, scanName on VulnerabilityScan.scanAndVerify and on the
extension - and writes two files named after it, so the scans of one run do not overwrite each other:
| File | Content |
|---|---|
<name-prefix>-<scan name>.json |
the scanner’s raw report, every finding |
<name-prefix>-<scan name>.html |
verdict, counts per severity, the findings that fail the build, those below the threshold, and the ignored ones with the reason - one self-contained file |
The HTML report is a single file with its styles embedded and no JavaScript, so uploading or archiving that one file is enough:
// Jenkinsfile
post {
always {
publishHTML(target: [
reportName : 'Vulnerability report',
reportDir : 'build/reports/cve-scan',
reportFiles: 'vulnerability-report-dependencies.html, vulnerability-report-artifacts-build-libs.html',
keepAll : true,
alwaysLinkToLastBuild: true,
allowMissing: true
])
archiveArtifacts artifacts: 'build/reports/cve-scan/*', allowEmptyArchive: true
}
}
Jenkins serves published HTML with style-src 'self' by default, which drops embedded styles. The report stays
complete and readable without them - verdict and severities are words, the findings are plain tables. For the styled
view, allow inline styles for published reports (Script Console or -D on the controller):
System.setProperty("hudson.model.DirectoryBrowserSupport.CSP",
"sandbox allow-same-origin; default-src 'none'; img-src 'self'; style-src 'self' 'unsafe-inline';")
The report needs no JavaScript, so script-src stays closed.
Database sources
Trivy needs two databases: the vulnerability database and the Java database, which maps archives to Maven
coordinates. By default it downloads both from public registries (mirror.gcr.io, ghcr.io) into the cache volume
and keeps them up to date. Each can come from somewhere else instead, configured separately under
scanner.database and scanner.java-database:
| Key | Meaning |
|---|---|
repositories |
OCI registries in order of priority - a registry mirror or a pull-through cache (Nexus, Artifactory, Harbor). Trivy keeps the database up to date from there |
archive |
http(s) URL or file path of the database as .tar.gz, in a storage that is updated e.g. daily. Takes precedence over repositories; Trivy then never downloads this database itself |
archive-headers |
HTTP headers for downloading archive, e.g. Authorization |
max-age |
How old the loaded archive may get before it is loaded again (default 24h) |
A pull-through cache in front of the public registries:
cucumbertest.security.cve.scanner:
database:
repositories: [ "nexus.example.com/aquasec/trivy-db:2", "mirror.gcr.io/aquasec/trivy-db:2" ]
java-database:
repositories: [ "nexus.example.com/aquasec/trivy-java-db:1" ]
registry-username: ci
registry-password: ${NEXUS_PASSWORD}
A daily updated storage - a web server, S3, an Artifactory generic repository or a mounted share:
cucumbertest.security.cve.scanner:
database:
archive: https://artifacts.example.com/trivy/db.tar.gz
archive-headers:
Authorization: Bearer ${ARTIFACTS_TOKEN}
java-database:
archive: /mnt/security/trivy/javadb.tar.gz
max-age: 7d
An archive is loaded into the cache volume only when the copy there is missing or older than max-age, so a daily
updated storage costs one download a day, not one per scan. It is unpacked next to the current copy and swapped in
only when complete; a broken archive fails the scan and leaves the previous database in place. The archive is the
layer the database image consists of - fill the storage e.g. with a daily job, see
Downloading the databases.
An archive URL is downloaded by the test JVM, through its own proxy settings (https.proxyHost); https-proxy
applies to downloads of the scanner in the container.
Downloading the databases
Both databases are OCI artifacts with a single layer, and that layer is the archive. Two curl calls per database
fetch it - the manifest names the layer’s digest, the blob is the .tar.gz. Needs curl and jq:
REGISTRY=https://mirror.gcr.io/v2
ACCEPT='Accept: application/vnd.oci.image.manifest.v1+json'
# vulnerability database, ~120 MB -> db.tar.gz (trivy.db, metadata.json)
DIGEST=$(curl -fsS -H "$ACCEPT" "$REGISTRY/aquasec/trivy-db/manifests/2" | jq -r '.layers[0].digest')
curl -fL -o db.tar.gz "$REGISTRY/aquasec/trivy-db/blobs/$DIGEST"
# Java database, ~1 GB -> javadb.tar.gz (trivy-java.db, metadata.json)
DIGEST=$(curl -fsS -H "$ACCEPT" "$REGISTRY/aquasec/trivy-java-db/manifests/1" | jq -r '.layers[0].digest')
curl -fL -o javadb.tar.gz "$REGISTRY/aquasec/trivy-java-db/blobs/$DIGEST"
mirror.gcr.io needs no login. The same databases are on ghcr.io (aquasecurity/trivy-db,
aquasecurity/trivy-java-db), which wants an anonymous token on every call:
TOKEN=$(curl -fsS "https://ghcr.io/token?scope=repository:aquasecurity/trivy-db:pull" | jq -r .token)
DIGEST=$(curl -fsS -H "Authorization: Bearer $TOKEN" -H "$ACCEPT" \
"https://ghcr.io/v2/aquasecurity/trivy-db/manifests/2" | jq -r '.layers[0].digest')
curl -fL -H "Authorization: Bearer $TOKEN" -o db.tar.gz "https://ghcr.io/v2/aquasecurity/trivy-db/blobs/$DIGEST"
Behind a registry mirror or pull-through cache, use its URL and credentials instead. With
oras it is one command each: oras pull mirror.gcr.io/aquasec/trivy-db:2 and
oras pull mirror.gcr.io/aquasec/trivy-java-db:1.
For archive, upload db.tar.gz and javadb.tar.gz as they are.
Databases built into the image
A company can build its own scanner image that already contains both databases, e.g. once a day, and push it to its own registry. Build agents then need nothing but that image: no access to the public registries, no storage for archives, no download at scan time - and the image can be pinned by tag or digest like any other.
The daily job downloads the databases as in Downloading the databases and unpacks them
into the layout Trivy expects - db/ and java-db/ below its cache directory:
mkdir -p cache/db cache/java-db
tar -xzf db.tar.gz -C cache/db # -> cache/db/trivy.db, cache/db/metadata.json
tar -xzf javadb.tar.gz -C cache/java-db # -> cache/java-db/trivy-java.db, cache/java-db/metadata.json
docker build --pull -t registry.example.com/security/trivy:$(date +%F) -t registry.example.com/security/trivy:latest .
docker push --all-tags registry.example.com/security/trivy
FROM aquasec/trivy:0.74.0
# /cache is where the scan looks for the databases; its own layer, so only this one changes from day to day
COPY cache/ /cache/
# the databases come with the image, Trivy must not replace them at scan time
ENV TRIVY_SKIP_DB_UPDATE=true \
TRIVY_SKIP_JAVA_DB_UPDATE=true
Configure the image and no cache volume:
cucumbertest.security.cve.scanner:
image: registry.example.com/security/trivy:latest
cache-volume: ""
The cache volume has to be switched off: Docker copies the content of the image into a named volume only when the
volume is created, afterwards the volume hides it - every agent would keep scanning with the databases of its first
run. Without a volume the databases are read straight from the image. A database archive needs the volume and is
refused without one.
An agent pulls the changed layer once a day - about as much as the two downloads (~1.1 GB compressed, mostly the Java
database), like it would download the databases otherwise. Unpacked, the databases take several GB on the agent (the
vulnerability database alone ~1.4 GB), with or without the image. Check a built image with
docker run --rm --entrypoint ls registry.example.com/security/trivy:latest -lR /cache.
Pinning the image
The default follows latest, so the scanner is updated without a release of this library. A tag can be repointed: in
March 2026 the Docker Hub tags 0.69.4, 0.69.5, 0.69.6 and latest of aquasec/trivy were replaced for a while
by images that stole CI secrets (GHSA-69fq-xp46-6x23).
If you want reproducible builds or to rule that out, set scanner.image to a digest
(aquasec/trivy@sha256:…) or an image from your own registry.
Replacing the scanner
Implement VulnerabilityScanner - one function that scans a list of archives, writes a report and returns the
findings - and pass it instead of TrivyVulnerabilityScanner. Nothing else changes.