Tags

Tags are labels that you define once and attach to entries and to release package URLs (PURLs). Typical tags name the parts of your software, such as a server, a user interface, or a container image. Commands filter by tag. OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability, use tags to link entries to release PURLs.

Synopsis

tags:
  - id: backend
    description: Java server application

releases:
  - id: 4.3.0
    published_at: 2026-06-15
    purls:
      - purl: "pkg:maven/com.acme/acme-shop-server@4.3.0"
        tags: [backend]

vulnerabilities:

  - id: CVE-2022-42889
    releases: [4.3.0]
    packages: ["pkg:maven/org.apache.commons/commons-text@1.9"]
    reports:
      - reporter: dependency-check
    tags: [backend]

tags

tags is an optional top-level list of tag definitions.

Field Type Required Default Description

id

String

Yes

None

Name of the tag. It can contain spaces, for example dev dependency.

description

String

No

None

What the tag stands for.

Where you use tags

Field Effect

tags on an entry

Filters with --tag select the entry. See Vulnerabilities.

tags on a release PURL

An OpenVEX statement for an entry names the release PURLs that share at least one tag with the entry. See Project and releases and vulnlog vex openvex.

Without --tag, commands include every entry, tagged or not. For the commands that accept --tag and how it selects entries, see Filter options.

An entry without tags gets no OpenVEX statement. A release PURL without tags appears in no OpenVEX statement.

Rules

vulnlog validate checks these rules.

Rule Level Message

Each tag id is unique.

Error

Duplicate tag ID 'backend'.

Each tag on an entry or a release PURL is defined in tags.

Error

References undefined tags 'backend'. Defined tags: container, frontend, worker

Each defined tag is used on an entry or a release PURL.

Info

Unreferenced tag ID 'backend'.

A --tag value that the file doesn’t define fails with Tag not found, or with tags not defined in the file in vulnlog modify add. For the exit codes, see Exit codes.

Examples

A tag definition with an id and a description:

tags:
  - id: container
    description: Container image that bundles all components

Acme Shop defines four tags:

tags:
  - id: backend
    description: Java server application
  - id: frontend
    description: Web user interface
  - id: worker
    description: Python report worker
  - id: container
    description: Container image that bundles all components

Each Acme Shop release has two PURLs, one tagged backend and one tagged container:

  - id: 4.3.0
    published_at: 2026-06-15
    purls:
      - purl: "pkg:maven/com.acme/acme-shop-server@4.3.0"
        tags: [backend]
      - purl: "pkg:oci/acme-shop@sha256:23a5bff22a95119dc4bcef9422a20038eb3c2fd355f03928b02791273ff1cc27"
        tags: [container]

The Text4Shell entry is in the server, so it carries backend and container. OpenVEX statements for it name both PURLs of each release:

  - id: CVE-2022-42889
    name: Text4Shell
    description: Remote code execution through string interpolation in Apache Commons Text
    releases:
      - 4.2.0
      - 4.3.0
    packages: ["pkg:maven/org.apache.commons/commons-text@1.9"]
    reports:
      - reporter: dependency-check
        at: 2026-05-20
    tags:
      - backend
      - container
    analysis: >-
      Acme Shop only uses StringEscapeUtils from Commons Text. The server never calls StringSubstitutor, which performs the vulnerable
      interpolation.
    analyzed_at: 2026-05-21
    verdict: not affected
    justification: vulnerable code not in execute path