bdd-cucumber-gherkin-lib-security-cve-core

Cucumber library for simpler e2e tests with predefined sentences for API and basic database access for Spring.


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

  1. 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 manifest Class-Path that 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.
  2. 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.
  3. Copy Trivy’s raw JSON report out to the report directory.
  4. Drop ignored ids, excluded packages and - on request - unfixed vulnerabilities.
  5. 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.