config.yml

Advisory sources

Which advisory databases Argus reads, in what order, and what happens when one fails. Two sources today: OSV.dev and the advisories you declare yourself.

What it is for

Argus reasons from OSV.dev. Advisory databases differ in what they map to package coordinates and when: an advisory whose upstream record carries only git commit ranges is invisible to a coordinate query until someone maps it, even though your GitLab dependency-scanning dashboard may already show it. declare_advisories closes that gap: you state the advisory, the package and the fixed version, and Argus treats it like any other finding until OSV publishes it.

advisory_sources names which of these Argus queries and in what order. Everything downstream of the merge (planning, families, staging, reports, SARIF, merge requests) reads the same finding model, so the list changes what is found, not how it is fixed.

The shape of the block

advisory_sources is a list. Each entry is a source enum, either as a bare string or as an object carrying per-source policy.

Property	Default	Description
`name` string	`none`	The source enum: `osv` or `config`. Required. A bare string (`- osv`) is the same as `- name: osv`. An unknown value is a load error, and so is `gitlab`, which was removed in 4.0.0.
`optional` boolean	`false`	When `true`, a failure of this source is logged and recorded in the report, and the run continues on the other sources. Default `false`: a failing source fails the run, because a report missing a source’s findings must not read as clean.

config.yml

# config.yml, Argus 4.0
version: 3

# Order is precedence. An absent or empty block means [osv, config].
advisory_sources:
  - osv
  - config

# config.yml, Argus 4.0
version: 3

# Order is precedence. An absent or empty block means [osv, config].
advisory_sources:
  - osv
  - config

The sources

osv: OSV.dev, first in the default list. OSV is never optional unless you say so explicitly.
config: the declare_advisories block. It is implied whenever that block is non-empty, so listing it here is optional; list it only to place it in the precedence order deliberately.

Precedence and merging

List order is precedence. Findings are deduplicated by identifier set, an advisory’s id plus every alias, compared case-insensitively, so a declared CVE and OSV’s GHSA record for the same advisory become one finding, and OSV supersedes the declaration as soon as it publishes. When sources disagree on a field that must have one value (severity, summary), the earlier source wins. When they disagree on the fixed version for a coordinate, the highest stated fix wins, reconciled per release line. The merged list is sorted by coordinate then id, so report.json and the run journal are byte-stable across runs.

Optional sources and failure

A source that errors fails the run by default. A security tool’s silence reads as “clean”, so a report missing one source’s findings must not look like a report. Mark a source optional: true only when you are willing to lose it: its failure is logged, recorded in the report’s advisory_sources block, and the run continues on the other sources. A merge request produced while an optional source failed says so, naming the source and the reason. Transient failures (5xx, 429, network errors) are retried with backoff before the policy applies.

The GitLab source (removed in 4.0.0)

From 3.7.0 to 3.8.x, gitlab read the project’s own GitLab vulnerability report as a source. It was removed in 4.0.0 (ADR-055). The report describes the project’s current state, not facts about versions: once an Argus pin fixed a finding, the finding stopped being detected and left the report, and the next cleanup read that silence as “the pin is no longer needed”, removed it, and a later run put it back.

A config.yml that still lists gitlab refuses to load with a message naming the entry. Delete the entry, and in the same change declare every advisory you relied on it for, or the next cleanup may judge those pins unnecessary on OSV data alone:

config.yml

advisory_sources:
  - osv
  # - name: gitlab        <- delete this entry
  #   optional: true
  - config

# Declare what you relied on the GitLab report for, in the same change.
declare_advisories:
  - { id: CVE-2026-12802, package: org.bouncycastle:bcpkix-jdk18on, fixed: "1.85" }

advisory_sources:
  - osv
  # - name: gitlab        <- delete this entry
  #   optional: true
  - config

# Declare what you relied on the GitLab report for, in the same change.
declare_advisories:
  - { id: CVE-2026-12802, package: org.bouncycastle:bcpkix-jdk18on, fixed: "1.85" }

Where the provenance shows

Each finding in report.json carries a sources list (and fixed_version_source when sources disagreed on the fix); the report has a top-level advisory_sources block with each source’s count, duration and any error; SARIF results carry the list under an advisorySources property. A declared advisory is marked (declared in config.yml) in merge requests and links to NVD for a CVE or GitHub for a GHSA, since osv.dev has no page for it yet.