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.

Plugin ID

plugins {
    id("dev.vulnlog.plugin") version "0.19.0"
}

Extension

The vulnlog block of build.gradle.kts configures the tasks:

vulnlog {
    files.from("acme-shop.vl.yaml")
}
Property Type Default Description

files

File collection

empty

The Vulnlog files the tasks read. Every task except vulnlogInit and vulnlogOpenVexUpdate reads it, and fails if it’s empty. vulnlogSuppress and vulnlogOpenVex accept one file only.

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

vulnlogInit

-P project properties

vulnlog init

vulnlogValidate

validate { }

vulnlog validate

vulnlogFormat

fmt { }

vulnlog fmt

vulnlogSuppress

suppress { }

vulnlog suppress

vulnlogImpactReport

report { impact { } }

vulnlog report impact

vulnlogChangelogReport

report { changelog { } }

vulnlog report changelog

vulnlogOpenVex

vex { openvex { } }

vulnlog vex openvex

vulnlogOpenVexUpdate

vex { openvex { } }

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

reporter

String

all reporters

As for --reporter.

asOf

String

all releases

As for --as-of.

tags

Set of strings

all entries, tagged or not

As for --tag.

vulnlogInit

Creates a Vulnlog file. It takes its values from project properties:

Property Required Default Description

vulnlog.organization

yes

none

Written to project.organization.

vulnlog.name

yes

none

Written to project.name.

vulnlog.author

yes

none

Written to project.author.

vulnlog.output

yes

none

File to create, relative to the project directory.

vulnlog.force

no

false

Replace the file if it exists. The task option --force does the same.

$ ./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

strict

Boolean

false

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

check

Boolean

false

Don’t write anything, and fail the build if a file isn’t in the canonical style. The task option --check does the same.

$ ./gradlew vulnlogFormat --check

vulnlogSuppress

Writes the suppression files of one Vulnlog file, one file for each reporter.

Property Type Default Description

outputDir

Directory

build/vulnlog/suppressions

Directory to write the files to. It’s created if it doesn’t exist.

format

String

auto

auto or generic.

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

outputFile

File

build/vulnlog/vulnlog-impact-report.html

File to write.

states

Set of strings

all states

As for --state.

verdicts

Set of strings

all verdicts

As for --verdict.

dispositions

Set of strings

all entries

As for --disposition.

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

outputFile

File

build/vulnlog/vulnlog-changelog.txt, or .md for markdown

File to write.

format

String

text

text or markdown.

brief

Boolean

false

As for --brief.

fixedIn

String

all releases

As for --fixed-in.

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

outputFile

File

build/vulnlog/vex.json

File to write.

release

String

every published release

As for --release.

tags

Set of strings

all tags

As for --tag.

baseline

File

none

Document to continue, as for --baseline. If the file doesn’t exist yet, the task issues a new document. It must not be the same file as outputFile.

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

VulnlogInitTask

organization, projectName, author, outputFile

VulnlogValidateTask

files, strict

VulnlogFmtTask

files

VulnlogSuppressTask

files, outputDir

VulnlogImpactReportTask

files, outputFile

VulnlogChangelogReportTask

files, brief, outputFile

VulnlogOpenVexTask

files, outputFile

VulnlogOpenVexUpdateTask

generatedFile, baseline

VulnlogCopyTask

sourceFile, destinationFiles, vulnIds

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

sourceFile

File

none

Vulnlog file to copy from.

destinationFiles

File collection

empty

Vulnlog files to copy into.

vulnIds

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.yaml is 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 print error: and hint: lines for it. Validation findings still print as error:, warning:, and info: 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 baseline file of vulnlogOpenVex doesn’t exist, the task issues a new document. The CLI exits with code 5.

  • vulnlogChangelogReport writes 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.