Quickstart

Creating a Vulnlog File

vulnlog init --name "My App" --organization "Acme Corp" --author "Security Team" -o my-app.vl.yaml
File Name Convention

For simple projects, vulnlog.yaml is the recommended file name. For multiple Vulnlog files, use <project-name>.vl.yaml.

See also Branching Strategy

A Minimal Example

# $schema: https://vulnlog.dev/schema/vulnlog-v1.json
---
schemaVersion: "1"

project:
  organization: Acme Corp
  name: Acme Web App
  author: Acme Corp Security Team

releases:
  - id: 1.0.0
    published_at: 2026-01-15

vulnerabilities:

  - id: CVE-2026-1234
    releases: [ 1.0.0 ]
    description: Remote code execution in example-lib
    packages: [ "pkg:npm/example-lib@2.3.0" ]
    reports:
      - reporter: trivy
    analysis: >
      The vulnerable code path is not reachable in our application
      because we only use the safe subset of the API.
    verdict: not affected
    justification: vulnerable code not in execute path

IDE Setup

Vulnlog’s JSON Schema is published on vulnlog.dev. IDEs with YAML support can automatically provide validation and autocompletion for .vl.yaml and vulnlog.yaml files.

To reference a local schema, add the following as the first line of the Vulnlog file:

# $schema: https://vulnlog.dev/schema/vulnlog-v1.json

Common Workflows

New finding — triage later

Record a finding as a stub entry for later analysis. Without a verdict, the entry is tracked as under investigation.

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
    tags: [ webapp ]

Finding does not affect us

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    tags: [ webapp ]
    analysis: >
      The vulnerable code path requires SVG input processing.
      Our application only accepts PNG and JPEG formats.
    analyzed_at: 2026-03-02
    verdict: not affected
    justification: vulnerable code not in execute path

Not affected, but dependency updated anyway

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    tags: [ webapp ]
    analysis: >
      The vulnerable code path requires SVG input processing.
      Our application only accepts PNG and JPEG formats.
    verdict: not affected
    justification: vulnerable code not in execute path
    resolution:
      in: 2.0.1
      note: "Updated image-lib from 3.1.0 to 3.2.0 during routine upgrade"

Affected and fixed in the next release

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    tags: [ webapp ]
    analysis: >
      Confirmed exploitable via crafted PNG uploads.
    analyzed_at: 2026-03-02
    severity: high
    verdict: affected
    resolution:
      in: 2.0.1
      at: 2026-03-03
      ref: "https://jira.example.com/browse/SEC-99"
      note: "Updated image-lib from 3.1.0 to 3.2.0"

Risk accepted with permanent suppression

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        suppress: {}
    tags: [ webapp ]
    analysis: >
      Vulnerability confirmed but only exploitable with
      specially crafted input that our validation layer rejects.
    severity: medium
    verdict: risk acceptable
    comment: >
      Risk accepted by project lead. Revisit when upstream
      releases a stable fix.

Evolving an entry over time

A vulnerability entry typically starts as a stub and is refined as the analysis progresses. The following example shows the same entry at each stage.

Stage 1 — Stub entry during initial triage:

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01

Stage 2 — Analysis complete, verdict recorded:

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    analysis: >
      Confirmed exploitable via crafted PNG uploads.
    analyzed_at: 2026-03-02
    severity: high
    verdict: affected

Stage 3 — Resolution recorded after fix:

  - id: CVE-2026-5678
    releases: [ 2.0.0 ]
    description: Memory corruption in image-lib
    packages: [ "pkg:npm/image-lib@3.1.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    analysis: >
      Confirmed exploitable via crafted PNG uploads.
    analyzed_at: 2026-03-02
    severity: high
    verdict: affected
    resolution:
      in: 2.0.1
      at: 2026-03-03
      note: "Updated image-lib from 3.1.0 to 3.2.0"

Once a resolution is recorded with verdict: affected, the entry is automatically excluded from generated suppression files. The scanner is expected to no longer report the finding after the dependency update.

False positive

When a scanner reports a finding that does not actually apply, record it as not affected with a justification that captures why the report is incorrect.

  - id: CVE-2026-4321
    releases: [ 2.0.0 ]
    description: Remote code execution in logging-framework
    packages: [ "pkg:npm/logging-framework@2.0.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-15
    analysis: >
      False positive. The scanner flagged logging-framework as a
      runtime dependency, but it is only present in the test scope
      and not included in the deliverable.
    analyzed_at: 2026-03-16
    verdict: not affected
    justification: component not present

Internal dependency, no customer impact

  - id: CVE-2026-9999
    releases: [ 2.0.0 ]
    description: Command injection in build-tool
    packages: [ "pkg:npm/build-tool@5.0.0" ]
    reports:
      - reporter: trivy
        at: 2026-03-01
    tags: [ build-dep ]
    analysis: >
      Affects the build pipeline only. The vulnerable command
      injection requires untrusted input which the CI environment
      does not expose.
    verdict: not affected
    justification: vulnerable code cannot be controlled by adversary

Next Steps