Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Badges

A project’s badge is a small image of the open findings of one of its versions, for a README. It is off by default; admins, owners and instance administrators turn it on, give it a new address and turn it off from the project page (Show a badge in a README, permissions).

Endpoints

PathReturns
GET /badges/{key}.svgThe badge as an SVG image
GET /badges/{key}.jsonThe badge in the shields.io endpoint format

{key} is 32 lowercase hexadecimal digits (128 random bits), drawn when the badge is turned on and again for each new address. The key is the only authorization: no session or token is needed, and none is read. The address names neither the organization nor the project.

ParameterMeaning
versionThe name of the version to show (case-sensitive). Without it, the latest version. Empty (version=) names the unnamed version

HEAD is answered like GET, without a body.

Messages and colours

The label is always vulnerabilities, in English whatever the interface language. The message counts the open findings of the version, as the project page’s summary does: ignored and fixed findings do not count. The colour is that of the worst open finding.

Open findingsMessageColour
Nonenonegreen #1f883d
Some known exploited (CISA KEV)N exploited, then the counts belowred #cf222e
Worst is criticalthe counts, e.g. 1 critical, 2 highred #cf222e
Worst is highe.g. 2 high, 3 mediumorange #bc4c00
Worst is mediume.g. 3 mediumyellow #d4a72c, dark text
Worst is lowe.g. 1 lowyellow-green #a2b82c, dark text
Only unknown severitye.g. 1 unknowngrey #6e7781
The version never received an SBOMno SBOMgrey #6e7781

Counts are listed from the worst severity to the least (critical, high, medium, low, unknown), zero counts left out, separated by , . A known exploited finding is also counted under its severity.

The JSON document:

{"schemaVersion":1,"label":"vulnerabilities","message":"1 critical, 2 high","color":"cf222e"}

Responses

StatusWhen
200The badge
304If-None-Match names the badge’s current ETag (or is *)
404The key is unknown, was replaced by a new address, or the badge is off; the version is unknown; the extension is neither .svg nor .json; the query string is malformed (such as version given twice). The body is empty and does not say which

Headers of a 200:

HeaderValue
Content-Typeimage/svg+xml; charset=utf-8 or application/json
Cache-Controlpublic, max-age=300: image proxies, such as GitHub’s, may serve a badge up to five minutes old
ETagA strong tag of the body; badges are never compressed, so it names the bytes sent
X-Content-Type-Optionsnosniff
Content-Security-PolicySVG only: default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none', so the image opened on its own runs nothing

A 304 carries the ETag and Cache-Control headers.

What a badge exposes

To anyone with its address:

  • the open findings of a version, by severity, and how many are known exploited;
  • whether the version has received an SBOM;
  • with ?version=, whether a version of that name exists.

Not the project’s or the organization’s name, the findings themselves, the components or anything else. The Markdown snippet of the project page links the image to the project page, which only members can open, or to the project’s public page while it is on. The badge’s key never opens the public page, which has a key of its own.

The key is stored in clear in the database, unlike API tokens, so the project page can show the snippet again. Request logs write badge paths as /badges/…, without the key, at debug level (Metrics, health and logs).