Gradle plugin
The Vulnlog Gradle plugin runs the Vulnlog commands as Gradle tasks. The tasks read the same files and run the same checks as the Vulnlog CLI, with the differences listed in Differences from the CLI. To add the plugin to a build, see Install Vulnlog.
Extension
The vulnlog block of build.gradle.kts configures the tasks:
vulnlog {
files.from("acme-shop.vl.yaml")
}
| Property | Type | Default | Description |
|---|---|---|---|
|
File collection |
empty |
The Vulnlog files the tasks read. Every task except |
The settings of each task go in a nested block of vulnlog, shown in the Settings column of Tasks.
Tasks
The plugin registers these tasks in the vulnlog group:
| Task | Settings | CLI command |
|---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
none |
The plugin also provides a task type for vulnlog modify copy, which you register yourself.
See Copy task.
Values such as reporters, states, and verdicts are the same as for the CLI. Each CLI command page describes what the values do.
vulnlogOpenVex and vulnlogOpenVexUpdate write OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability.
OpenVEX output is incubating.
|
Filter properties
vulnlogSuppress, vulnlogImpactReport, and vulnlogChangelogReport accept these properties to select entries.
For what they do, see Filter options.
| Property | Type | Default | Description |
|---|---|---|---|
|
String |
all reporters |
As for |
|
String |
all releases |
As for |
|
Set of strings |
all entries, tagged or not |
As for |
vulnlogInit
Creates a Vulnlog file. It takes its values from project properties:
| Property | Required | Default | Description |
|---|---|---|---|
|
yes |
none |
Written to |
|
yes |
none |
Written to |
|
yes |
none |
Written to |
|
yes |
none |
File to create, relative to the project directory. |
|
no |
|
Replace the file if it exists. The task option |
$ ./gradlew vulnlogInit -Pvulnlog.organization="Acme Corp" -Pvulnlog.name="Acme Shop" \
-Pvulnlog.author="Acme Product Security Team" -Pvulnlog.output=acme-shop.vl.yaml
vulnlogValidate
Validates every file in files.
| Property | Type | Default | Description |
|---|---|---|---|
|
Boolean |
|
Treat warnings as errors, so a warning fails the build. |
vulnlog {
validate {
strict = true
}
}
vulnlogFormat
Formats every file in files in place.
| Property | Type | Default | Description |
|---|---|---|---|
|
Boolean |
|
Don’t write anything, and fail the build if a file isn’t in the canonical style.
The task option |
$ ./gradlew vulnlogFormat --check
vulnlogSuppress
Writes the suppression files of one Vulnlog file, one file for each reporter.
| Property | Type | Default | Description |
|---|---|---|---|
|
Directory |
|
Directory to write the files to. It’s created if it doesn’t exist. |
|
String |
|
|
The task also accepts the properties in Filter properties.
vulnlog {
suppress {
outputDir = layout.projectDirectory.dir("suppressions")
asOf = "4.3.0"
}
}
vulnlogImpactReport
Writes the HTML impact report of every file in files, merged into one report.
| Property | Type | Default | Description |
|---|---|---|---|
|
File |
|
File to write. |
|
Set of strings |
all states |
As for |
|
Set of strings |
all verdicts |
As for |
|
Set of strings |
all entries |
As for |
The task also accepts the properties in Filter properties.
vulnlog {
report {
impact {
asOf = "4.3.0"
states = setOf("open", "accepted")
}
}
}
vulnlogChangelogReport
Writes the changelog report of every file in files, merged into one report.
| Property | Type | Default | Description |
|---|---|---|---|
|
File |
|
File to write. |
|
String |
|
|
|
Boolean |
|
As for |
|
String |
all releases |
As for |
The task also accepts the properties in Filter properties.
Unlike the CLI, the task also writes the file when no entry qualifies.
The file is then empty for markdown, and holds only the organisation and project name for text.
vulnlog {
report {
changelog {
format = "markdown"
fixedIn = "4.4.0"
}
}
}
vulnlogOpenVex
Writes one OpenVEX document from one Vulnlog file in each run.
| Property | Type | Default | Description |
|---|---|---|---|
|
File |
|
File to write. |
|
String |
every published release |
As for |
|
Set of strings |
all tags |
As for |
|
File |
none |
Document to continue, as for |
The task writes only to outputFile.
vulnlogOpenVexUpdate copies the result over the baseline.
vulnlog {
vex {
openvex {
release = "4.3.0"
tags = setOf("container")
baseline = layout.projectDirectory.file("vex/acme-shop-4.3.0-container.json")
}
}
}
vulnlogOpenVexUpdate
Runs vulnlogOpenVex and copies its document over the baseline of the vex { openvex { } } block.
If the content is the same, the file stays as it is.
The task fails if baseline isn’t set.
One document per release and artifact needs one registered task of each type per document. For an example, see One document per release and artifact.
Tasks you register yourself
A task you register yourself doesn’t take its settings from the vulnlog block.
It needs these properties set:
| Task type | Properties to set |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The task types are in the package dev.vulnlog.gradle.
With group = "vulnlog", a registered task is listed with the other Vulnlog tasks.
Copy task
The task type dev.vulnlog.gradle.VulnlogCopyTask copies entries as vulnlog modify copy does.
No task of this type is registered by default.
| Property | Type | Default | Description |
|---|---|---|---|
|
File |
none |
Vulnlog file to copy from. |
|
File collection |
empty |
Vulnlog files to copy into. |
|
Set of strings |
empty |
IDs of the entries to copy. |
import dev.vulnlog.gradle.VulnlogCopyTask
tasks.register<VulnlogCopyTask>("copySpring4Shell") {
sourceFile = layout.projectDirectory.file("acme-shop.vl.yaml")
destinationFiles.from("acme-shop-3.vl.yaml")
vulnIds = setOf("CVE-2022-22965")
}
Messages and failures
The tasks log status lines at the lifecycle level and warnings at the warning level.
The detail the CLI prints as verbose: and debug: lines goes to the info and debug levels, without those prefixes.
Gradle’s --info and --debug take the place of the CLI’s -v and -vv.
A task fails the build where the CLI exits with a code other than 0, except in the cases listed in Differences from the CLI.
For the conditions, see the exit codes on each CLI command page.
Differences from the CLI
-
The tasks don’t check file names, so a file such as
acme-shop.yamlis accepted. -
A task reports a failure as a Gradle build failure, with the message and the hint in one text, for example
Release not found: 4.5.0. Known releases: 4.2.0, 4.3.0, 4.4.0.It doesn’t printerror:andhint:lines for it. Validation findings still print aserror:,warning:, andinfo:lines. -
Status lines show absolute paths, for example
Wrote: /home/me/acme-shop/build/vulnlog/vex.json.Validated:shows the file name, as in the CLI. -
If the
baselinefile ofvulnlogOpenVexdoesn’t exist, the task issues a new document. The CLI exits with code5. -
vulnlogChangelogReportwrites its file even when no entry qualifies. See vulnlogChangelogReport. -
The tasks don’t read from stdin or write to stdout.
-
The tasks create output directories that don’t exist. The CLI exits with code
1.