Title here
Summary here
Vulnerability (OSV)
| source | condition | target |
|---|---|---|
✔ | ✔ | ✗ |
Description
The vulnerability/osv resource checks a package version against the OSV vulnerability database,
which aggregates advisories such as GitHub Security Advisories, the Go vulnerability database and
the Python Packaging Advisory Database. Each vulnerability is reported under its lowest ID, with
its aliases (for example a GHSA advisory and its CVE) merged into one entry.
- source
Depending on
key, returns either the lowest version, starting fromversion, that has no known vulnerabilities (fixedversion, the default), or the comma-separated IDs of the known vulnerabilities affectingversion(ids).- condition
Passes when the version has no known vulnerabilities, and fails with the list of vulnerabilities otherwise. The version comes from
version, or from the source output whenversionis empty.- target
Not supported, a target fails with
target not supported for the vulnerability/osv plugin. Use the source output in a target of another kind, such as the "File" resource or the "Yaml" resource.
Note | An scm attached to a condition is ignored, with a warning. The lookup always goes to the OSV API. |
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| ecosystem | string | “ecosystem” defines the OSV ecosystem of the package. compatible:
remark:
example:
| |
| ignore | array | “ignore” defines the vulnerability IDs or aliases to disregard. compatible:
example:
| |
| key | string | “key” defines the source output. compatible:
default: fixedversion remark:
example:
| |
| minseverity | string | “minseverity” defines the minimum severity of the vulnerabilities to account for. compatible:
default: empty, so every vulnerability is accounted for. remark:
example:
| |
| name | string | “name” defines the package name within the ecosystem. compatible:
remark:
example:
| |
| purl | string | “purl” defines the package URL, without version. compatible:
remark:
example:
| |
| url | string | “url” defines the OSV API URL. compatible:
default: https://api.osv.dev | |
| version | string | “version” defines the package version to check. compatible:
default: in a condition, the output of the associated source. remark:
|
The generated table above stays empty until the Updatecli JSON schema published with this website
includes the vulnerability/osv resource. Until then, these are the parameters:
| Name | Stage | Description |
|---|---|---|
| source, condition | The OSV ecosystem of the package, such as |
| source, condition | The package name within the ecosystem, such as |
| source, condition | The package URL, without a version, such as |
| source, condition | The package version to check. Required for a source. A condition falls back to the source output when it is empty. |
| source | What the source returns: |
| source, condition | Only account for vulnerabilities at or above this severity: |
| source, condition | Vulnerability IDs or aliases to disregard, such as |
| source, condition | The OSV API URL. Defaults to |
Identifying the package
Set either ecosystem and name, or purl. The resource validates the spec before running and
reports the problems it finds together, for example an unsupported key alongside a bad package:
purltogether withecosystemornamefails withvulnerability/osv purl is mutually exclusive with ecosystem and name.Neither fails with
vulnerability/osv package not defined, set ecosystem and name, or purl.A
purlcarrying a version fails withvulnerability/osv purl "pkg:pypi/jinja2@3.1.2" must not contain a version, use the version field instead.A source without
versionfails withvulnerability/osv source requires a version.
With purl, the ecosystem comes from the package URL type: cargo (crates.io), composer
(Packagist), gem (RubyGems), golang (Go), hex (Hex), maven (Maven), npm (npm), nuget
(NuGet), pub (Pub) and pypi (PyPI). Other package URL types are only matched on the package URL
itself, and fixedversion does not support them.
Severity and ignored vulnerabilities
minseverity relies on the severity of the GitHub advisory. A vulnerability without one is always
accounted for, whatever the threshold. Set it deliberately: with minseverity: HIGH, a version
whose advisories are all rated MODERATE passes the condition.
ignore matches both IDs and aliases, case-insensitively, so a vulnerability can be ignored by its
CVE number even when OSV reports it under a GHSA ID.
The fixed version is a security floor
fixedversion answers "which version fixes the known vulnerabilities?", not "which version is the
latest?". It returns the lowest version, from version onwards, that clears the advisories affecting
version, and returns version itself when it has no known vulnerabilities.
It supports the Go, npm, crates.io, NuGet, Hex, Pub and PyPI ecosystems. Every ecosystem works with
key: idsand with conditions.A pre-release fix is only considered when
versionis itself a pre-release.When no published version fixes every known vulnerability yet, the source is skipped rather than failed, and the pipeline does not update anything.
Combine it with a source such as "PyPI" or "GitHub Release" when you also want to stay on the latest release: the condition example below takes the latest release and only writes it when it has no known vulnerability.
When the source feeds a target that changes something, the pipeline changelog, used in the pull request description, lists the vulnerabilities fixed between the two versions, along with the latest published version of the package, as recorded by deps.dev. The changelog is best effort: a failing lookup leaves it out without failing the pipeline.
Limitations
The answers are only as good as osv.dev and deps.dev, which index published releases with some delay. A very recent release may be missing, or not yet linked to an advisory.
The resource needs network access to the OSV API, or to the mirror set in
url.No authentication is supported.
Examples
Raise a package to its fixed version
The source returns 3.1.6, the lowest jinja2 release that fixes the five known vulnerabilities of
3.1.2, and the target pins it in requirements.txt.
# updatecli.yaml
name: Raise jinja2 to the lowest version without known vulnerabilities
sources:
jinja2:
name: Lowest jinja2 version fixing the vulnerabilities of 3.1.2
kind: vulnerability/osv
spec:
ecosystem: PyPI
name: jinja2
version: 3.1.2
targets:
requirements:
name: Pin jinja2 in requirements.txt
kind: file
sourceid: jinja2
spec:
file: requirements.txt
matchpattern: 'jinja2==.*'
replacepattern: 'jinja2=={{ source "jinja2" }}'
Only bump to a version without known vulnerabilities
The source takes the latest requests release from PyPI, and the condition only lets the target run
when that release has no known vulnerability rated HIGH or CRITICAL.
# updatecli.yaml
name: Only bump requests when the new version has no known high or critical vulnerability
sources:
requests:
name: Latest requests version on PyPI
kind: pypi
spec:
name: requests
conditions:
noVulnerability:
name: The new requests version has no known high or critical vulnerability
kind: vulnerability/osv
sourceid: requests
spec:
purl: pkg:pypi/requests
minseverity: HIGH
targets:
requirements:
name: Pin requests in requirements.txt
kind: file
sourceid: requests
spec:
file: requirements.txt
matchpattern: 'requests==.*'
replacepattern: 'requests=={{ source "requests" }}'
When the condition fails, it lists what it found:
✗ 5 known vulnerabilities for version "3.1.2" of PyPI package "jinja2":
* GHSA-cpwx-vrp4-4pq7 (CVE-2025-27516, PYSEC-2026-1471) [MODERATE] Jinja2 vulnerable to sandbox breakout through attr filter selecting format method - fixed in: 3.1.6
* GHSA-gmj6-6f8f-6699 (CVE-2024-56201, PYSEC-2026-1472) [MODERATE] Jinja has a sandbox breakout through malicious filenames - fixed in: 3.1.5
...List the known vulnerabilities
With key: ids, the source returns the IDs of the known vulnerabilities, here for the Go module
golang.org/x/net at v0.20.0, with one of them ignored.
# updatecli.yaml
name: List the known vulnerabilities of golang.org/x/net v0.20.0
sources:
vulnerabilities:
name: Known vulnerabilities of golang.org/x/net v0.20.0
kind: vulnerability/osv
spec:
ecosystem: Go
name: golang.org/x/net
version: v0.20.0
key: ids
ignore:
- GO-2024-2687
Links
Prev
Tool VersionsNext
XML