The release watch

The release watch tells you within the hour when a security advisory affects a release that you run.

Hangar knows which release ran, which components built it and which customer ran it. Every release has a bill of materials, which is the list of software inside the release. Hangar matches the bill against published advisories when the release enters, and again whenever the advisory mirror changes. Hangar then tells the vendor and the customer within the hour.

At the start of each job, Hangar applies the advisory policy that you set. The certificate shows what Hangar knew at that time.

1. What the watch does

The bill of materials. A release names its bill by SHA-384, in SPDX JSON. Hangar reads the bill when the release is submitted. Hangar keeps the packages with their ecosystem and version. If the bill lists no package data, or lists packages without a version, Hangar marks the bill partial and gives the reason. Hangar still admits the release.
The advisory mirror. Hangar keeps a local mirror of OSV, the GitHub Advisory Database, RustSec and the NVD feed. Each mirror snapshot has a digest and a time. The match reads only the mirror. It calls no outside service.
The match. Hangar matches each release that has a bill at admission, and within the hour of every mirror update. The match uses the package name, the ecosystem and the version range. GET /v1/releases/{id}/advisories returns the snapshot, every match and the count by severity. Each match gives the advisory id, the component, the installed and fixed versions, the severity, and whether the advisory lists a working exploit.
The notice. Hangar sends the notice "A component of your release has a published vulnerability" in two cases: a new match of critical or high severity, or any match that lists an exploit. The notice goes to the vendor and to each customer organisation that runs the release. Each notice is a record on the chain of the organisation that receives it.
The policy. Each organisation sets what its jobs do when a release has a match: record, hold for a named approver, or refuse. The default is record. The government profile holds at critical over 48 hours and high over 14 days.
The certificate. The compiled record of a job includes the snapshot digest and time, the counts and the decision of the policy. hangar verify therefore shows what Hangar knew when the job started.

2. The advisory policy

An owner uses PUT /v1/advisory-policy to set one of these:

Body	Meaning
`{"profile": "government"}`	Hold at critical over 48 hours and high over 14 days.
`{"mode": "record"}`	Jobs go ahead. The certificate states the snapshot and the counts.
`{"mode": "hold", "rules": [...], "approvers": [...]}`	A job waits for an approver when a match breaks a rule.
`{"mode": "refuse", "rules": [...]}`	Hangar refuses a job with `release_advisory_refused`.

A rule is a severity and a number of hours: {"severity": "high", "after_hours": 336}. A match breaks a rule when two things are true. The severity of the match is at least the severity of the rule. The match has been on the release for longer than the hours of the rule. An advisory that lists an exploit counts as critical. The clock for a match starts when Hangar first finds the match on the release.

A held job returns release_advisory_held with the approval to decide. GET /v1/approvals lists the approval with the release and the advisories. The decision of the approver is a record on your chain. The certificate of every job that relies on the decision includes that record.

3. Vendors

hangar release advisories shows every match across your releases, oldest first. For each match, it shows only the number of customers affected. To clear a match, publish a new release with the fixed component. Hangar never changes the image of a vendor.

hangar release sbom DIR builds the bill of an unpacked image on your machine. It uses the same stager that builds the bill of Hangar itself. It reads these files:

var/lib/dpkg/status
lib/apk/db/installed
Cargo.lock
package-lock.json
Python METADATA files
pinned requirements.txt files

4. Customer-controlled sites

Each runtime release ships the mirror snapshot as a file in the release manifest. The release signature therefore covers the digest of the snapshot. A site matches against its own copy of the snapshot, with no network:

hangar release advisories --snapshot advisories.json --sbom sbom.spdx.json --expect sha384:...

The command prints the age of the snapshot. Add --max-age-days N with --refuse-stale to end the command with an error when the snapshot is older than N days. The revocation list uses the same rule.

5. The limits of the match

The match is only as complete as the advisory sources and the bill of materials. The match does not find a package that the bill does not list. The match does not find a vulnerability that no source lists. Version order is exact for semver and close for the other ecosystems. The watch states what Hangar found, on which snapshot. It does not state that a release has no vulnerabilities.

Read this page as Markdown