Project and releases

project names who publishes the software and who answers for the analysis. releases lists the versions of the software that the file tracks. Reports take their author and product information from these two sections, and so do OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability.

Synopsis

project:
  organization: Acme Corp
  name: Acme Shop
  author: Acme Product Security Team
  contact: security@acme.example

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

project

Field Type Required Default Description

organization

String

Yes

None

Name of the organisation or vendor that publishes the software.

name

String

Yes

None

Name of the software project.

author

String

Yes

None

Name of the team or person responsible for the analysis. OpenVEX documents name it as their author.

contact

String, email address

No

None

Email address of the security team. OpenVEX documents name it as the author contact.

releases

A list of release objects, oldest first.

Field Type Required Default Description

id

String

Yes

None

Release identifier, for example 4.3.0 or 2.0.0-SNAPSHOT. Entries and resolutions refer to a release by this value.

published_at

Date, YYYY-MM-DD

No

Not published

Date the release was published. A release without published_at isn’t published.

purls

List of PURL entries

No

No PURLs

The artifacts that make up the release, each identified by a package URL (PURL). OpenVEX documents use them as product identifiers. See vulnlog vex openvex.

PURL entry

A PURL identifies a software package in a standard format, pkg:<type>/<namespace>/<name>@<version>. See the PURL specification.

Field Type Required Default Description

purl

String, PURL

Yes

None

PURL of the artifact in this release, including its version.

tags

List of tag IDs

No

No tags

Tags that link the artifact to entries with the same tag. Each tag must be defined in tags. See Tags.

Rules

vulnlog validate checks these rules.

Rule Level Message

organization, name, and author are present.

Error

YAML parse error: …​ missing (therefore NULL) value for creator parameter author …​

No project field is blank.

Error

Project 'organization' must not be blank.

Each release id is unique.

Error

Duplicate release ID '4.2.0'.

Each purl is a valid PURL.

Error

Unsupported PURL: acme-shop

Each tag on a release PURL is defined in tags.

Error

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

Releases with published_at are listed oldest first.

Warning

Release '4.3.0' published '2026-01-01' is declared after '4.2.0' published '2026-03-02'. Declare releases oldest first, because a release filter follows this order.

A release PURL includes a version.

Warning

Release purl 'pkg:maven/com.acme/acme-shop-server' has no version, so its VEX statements apply to every version of the artifact.

If any release declares PURLs, every release does.

Warning

Release '4.3.0' declares no purls and is left out of VEX documents.

Every release is used by an entry or a resolution.

Info

Unreferenced release ID '4.4.0'.

The order of releases matters. With --as-of, the selection includes the given release and every release listed before it. See Filter options.

A release ID that YAML reads as a number must be quoted to keep its value. YAML reads the unquoted ID 5.10 as the number 5.1, and Vulnlog uses 5.1 as the ID. vulnlog fmt quotes such an ID, but it keeps the value YAML read, so 5.10 becomes "5.1".

Examples

A minimal project and release:

project:
  organization: Acme Corp
  name: Acme Shop
  author: Acme Product Security Team

releases:
  - id: 4.2.0

Acme Shop has two published releases and one that isn’t published yet. Each release has a Maven artifact for the server and a container image:

project:
  organization: Acme Corp
  name: Acme Shop
  author: Acme Product Security Team
  contact: security@acme.example

releases:
  - id: 4.2.0
    published_at: 2026-03-02
    purls:
      - purl: "pkg:maven/com.acme/acme-shop-server@4.2.0"
        tags: [backend]
      - purl: "pkg:oci/acme-shop@sha256:cf9066b0fcef66d545007bd33b5d8d59e7434e37c2a23d19a3075fdb6f0b48b9"
        tags: [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]
  - id: 4.4.0
    purls:
      - purl: "pkg:maven/com.acme/acme-shop-server@4.4.0"
        tags: [backend]
      - purl: "pkg:oci/acme-shop@sha256:350f97615163b67cbff8b015e60c77c2cbb954b4d9ffa9d48254e216e54899c8"
        tags: [container]