Gradle plugin

The Vulnlog Gradle plugin integrates Vulnlog commands into your Gradle build.

Installation

Apply the plugin in your build.gradle.kts:

plugins {
    id("dev.vulnlog") version "0.17.0"
}

Configuration

The plugin is configured via the vulnlog extension block. The top-level files property is shared across tasks; per-task settings live in nested blocks documented under each task.

vulnlog {
    files.from("vulnlog.yaml", "other.vl.yaml")
}
Property Description

files

File collection of Vulnlog YAML files to operate on. Used by all tasks except vulnlogInit.

report

Container for the report tasks. Each report type has its own nested block: report { impact { } } and report { changelog { } }.

Diagnostics

The tasks emit the same diagnostics as the CLI’s -v and -vv flags through the Gradle logger. Run with gradle --info to see parsed inputs, validation summaries, filter resolution, written outputs, and skipped suppression entries; gradle --debug adds debug detail such as included suppression entries and report entry counts.

Tasks

All tasks are registered in the vulnlog task group.

vulnlogInit

Scaffolds a minimal Vulnlog file. See vulnlog init for the generated structure.

vulnlogInit is configured via project properties (-P) since it is a one-shot bootstrapping command.

Property Required Description

vulnlog.organization

Yes

Organization name for the Vulnlog project.

vulnlog.name

Yes

Project name.

vulnlog.author

Yes

Author name.

vulnlog.output

Yes

Output file path, relative to the project directory.
Example
./gradlew vulnlogInit \
  -Pvulnlog.organization="Acme Corp" \
  -Pvulnlog.name="Widget" \
  -Pvulnlog.author="Alice" \
  -Pvulnlog.output=vulnlog.yaml

vulnlogValidate

Validates the configured Vulnlog files. See vulnlog validate for validation rules.

vulnlog {
    validate {
        strict = true  // optional
    }
}
Property Default Description

strict

false

Treats warnings as errors and fails the build.

The task uses Gradle’s up-to-date checking via @InputFiles and @Input, so it is skipped when neither the files nor strict have changed.

Example
./gradlew vulnlogValidate

vulnlogFormat

Formats the configured Vulnlog files to the canonical style, rewriting them in place. See vulnlog fmt for the formatting rules.

vulnlog {
    fmt {
        check = true  // optional
    }
}
Property Default Description

check

false

Do not write changes; fail the build if any file is not already formatted. Also available as the --check task option.
Example
./gradlew vulnlogFormat
./gradlew vulnlogFormat --check   # CI: fail if any file is unformatted

vulnlogSuppress

Generates suppression files for downstream scanners. See vulnlog suppress for supported reporters.

vulnlog {
    suppress {
        outputDir = layout.projectDirectory.dir("suppressions")  // optional
        reporter = "trivy"                                       // optional
        asOf = "1.0.0"                                           // optional
        tags = setOf("frontend")                                 // optional
    }
}
Property Default Description

outputDir

build/vulnlog/suppressions/

Directory where suppression files are written.

reporter

All reporters

Filter on reporter.

asOf

All releases

Report as of this release, including all releases up to and including it.

tags

All tags

Filter on tags.
Example
./gradlew vulnlogSuppress

vulnlogImpactReport

Generates an HTML impact report from the configured Vulnlog files. Multiple files are merged and must share the same project metadata. See vulnlog report impact for details.

Settings live under report { impact { } }, so each report type keeps its own block.

vulnlog {
    report {
        impact {
            outputFile.set(layout.buildDirectory.file("vulnlog/vulnlog-impact-report.html"))  // optional
            reporter = "trivy"                                                                // optional
            asOf = "1.0.0"                                                                    // optional
            tags = setOf("frontend")                                                          // optional
            states = setOf("open", "accepted")                                                // optional
            verdicts = setOf("affected")                                                      // optional
            dispositions = setOf("wont fix")                                                  // optional
        }
    }
}
Property Default Description

outputFile

build/vulnlog/vulnlog-impact-report.html

File where the HTML report is written.

reporter

All reporters

Filter on reporter.

asOf

All releases

Report as of this release, including all releases up to and including it.

tags

All tags

Filter on tags.

states

All states

Filter on vulnerability state: under investigation, open, accepted, resolved, not applicable. Combined with asOf, each entry is reported in the state it was in at that release.

verdicts

All verdicts

Filter on triage verdict: under investigation, affected, not affected. A verdict is what you recorded, so it does not change with asOf.

dispositions

All dispositions

Filter on the remediation intent recorded for affected entries: will fix, wont fix. Affected entries that state no intent are not selected by either value.

The task is cacheable and uses Gradle’s up-to-date checking, so it is skipped when neither the files nor the filter settings have changed.

The task never fails because the report contains vulnerabilities. It fails the build only on invalid input, for example an unknown asOf or input files with different project metadata.

Example
./gradlew vulnlogImpactReport

vulnlogChangelogReport

Reports which vulnerabilities each release fixed, newest release first. Multiple files are merged and must share the same project metadata. See vulnlog report changelog for the report contents and for what it leaves out.

Settings live under report { changelog { } }.

vulnlog {
    report {
        changelog {
            outputFile.set(layout.buildDirectory.file("vulnlog/vulnlog-changelog.md"))  // optional
            format = "markdown"                                                         // optional
            brief = false                                                               // optional
            fixedIn = "1.2.0"                                                           // optional
            reporter = "trivy"                                                          // optional
            asOf = "1.1.0"                                                              // optional
            tags = setOf("frontend")                                                    // optional
        }
    }
}
Property Default Description

outputFile

build/vulnlog/vulnlog-changelog.<ext>

File where the report is written. The default file name follows format, so it ends in .txt for text and .md for markdown.

format

text

Output format: text or markdown. markdown renders one section per release in the Keep a Changelog layout, ready to paste under a heading the changelog file already has.

brief

false

List identifiers and severity only. Descriptions, resolution notes, and references are left out.

fixedIn

All releases

Report only the vulnerabilities this release shipped a fix for.

reporter

All reporters

Filter on reporter.

asOf

All releases

Report as of this release, including all releases up to and including it. A fix that ships later is left out.

tags

All tags

Filter on tags.

The report holds no timestamp, so the output depends only on the inputs and the settings. The task is cacheable and is skipped when neither has changed.

The task always writes its output file. When no entry records a resolution it writes the report for zero releases and logs info: no fixed vulnerabilities to report.

It fails the build only on invalid input, for example an unknown fixedIn or input files with different project metadata.

Example
./gradlew vulnlogChangelogReport

VulnlogCopyTask

Copies vulnerability entries from a source Vulnlog file into one or more target files. See vulnlog modify copy for the underlying behavior, including merge semantics for entries that already exist in a target.

The task type is provided but no task is registered by default, since the source, targets, and IDs to copy depend on the project. Register a task in your build script for each propagation you want to perform:

import dev.vulnlog.gradle.VulnlogCopyTask

tasks.register<VulnlogCopyTask>("vulnlogCopyToBranches") {
    group = "vulnlog"
    description = "Copy a vulnerability analysis into branch files."
    sourceFile.set(layout.projectDirectory.file("source.vl.yaml"))
    destinationFiles.from("target1.vl.yaml", "target2.vl.yaml")
    vulnIds.set(setOf("CVE-2026-002"))
}
Property Description

sourceFile

Vulnlog file to copy entries from.

destinationFiles

File collection of target Vulnlog files to copy entries into.

vulnIds

Set of vulnerability IDs to copy. Each ID must exist in the source file.
Example
./gradlew vulnlogCopyToBranches