Skip to content

Advisories

Advisories are how you tell end customers that a product they own is affected and what to do about it. They sit downstream of triage: an advisory is drafted only once a decision exists that the product is genuinely affected, and there is a fix, a mitigation, or a documented reason to inform without one.

This is a different duty from exploit reporting. Reporting goes to CSIRT and ENISA on a 24h/72h clock. Advisories go to customers, later, on your schedule.

Where it lives

Page Path
Advisory queue (org-wide) /advisories
Advisory editor /advisories/:advisoryId
Per-product advisories /products/:productId/advisories
Public portal (unauthenticated) /o/:orgSlug/advisories
ID scheme, public portal toggle, alert emails /settings/notifications

Advisory IDs

Every advisory gets a human-facing public ID that your organisation controls:

{PREFIX}-YYYY-MM-NNN     e.g. ADV-2026-08-001, PSIRT-2026-08-014
  • Prefix: 2–16 characters, letters and digits, must start with a letter. Defaults to ADV.
  • Year and month segments are each optional; turn them off for a flat PSIRT-001 scheme.
  • Sequence restarts per year/month bucket.

You can preview the next ID before committing, so it can be reserved or referenced in other systems. IDs are unique per organisation, not globally.

The lifecycle

Two orthogonal state axes. This trips people up, so it is worth stating plainly:

Axis Values Question it answers
status draft → sent Have we delivered this to recipients?
is_published false / true Is it visible on the public portal?

An advisory can be published without ever being emailed, and emailed without being published. Publishing increments the document version, rendered as 1.0, 2.0, … and recorded in the revision history shown on the public page.

1. Draft

Create an advisory against a release, either from the queue or directly from a finding. Prefill populates the document from what alloy-it already knows: the release, its findings, affected components and versions, and available fixed versions.

2. Write the document

The advisory is a structured document, not a single text blob. Each section is markdown and maps onto the shape a CSAF consumer expects:

Section Purpose
Summary What happened, in two sentences
Affected products Which products and releases are in scope
Vulnerable products The subset actually vulnerable
Not vulnerable Explicitly out of scope, as valuable as the affected list
Details Technical description
Workarounds What to do before the fix lands
Fixed software Where the patched version is
Exploitation Known exploitation status
Source Credit and references

Alongside these, a CVE entries table carries per-CVE rows: CVE ID, CVSS score, severity, summary, affected component name and version, and fixed version.

Operational fields (separate from the document) are recommended version, apply by date, and guidance markdown.

3. Notify customers

Notification sends to your PSIRT alert addresses and, when customer notification is enabled, to the organisation's configured recipients (deduplicated against the alert list).

Customer notification is gated

The send is refused unless both hold:

  • a recommended version is set, or delayed-inform is explicitly chosen, the documented case where you inform without a fix; and
  • at least one linked finding resolves to an exploitable analysis state.

The second condition means an advisory cannot be sent on the strength of an untriaged scan result. If triage has not concluded the product is exploitable, there is nothing to tell a customer yet.

On success, status becomes sent and per-recipient delivery records are marked.

4. Publish to the public portal

Publishing makes the advisory readable at /o/:orgSlug/advisories/:publicId with no login. Unpublish removes it again; the revision history keeps the record that a version existed.

The public portal

Off by default. Enable it with public advisories under Settings → PSIRT alerts.

While disabled, every public route for the organisation, including the logo, returns 404 rather than an "access denied" that would confirm the organisation exists.

Route Returns
GET /api/v1/public/orgs/:slug/advisories Published advisory list
GET /api/v1/public/orgs/:slug/advisories/:publicId One advisory
GET /api/v1/public/orgs/:slug/advisories/:publicId/csaf CSAF JSON
GET /api/v1/public/orgs/:slug/advisories/:publicId/pdf Rendered PDF
GET /api/v1/public/orgs/:slug/logo Organisation logo

All are unauthenticated, GET-only, and rate-limited per client IP: 60 requests/minute for list, detail, CSAF, and logo; 10 requests/minute for PDF, which is CPU-heavy to generate. Exceeding the budget returns 429 with Retry-After: 60.

Upload your logo under Settings → Organization profile; it brands the public page.

CSAF export

The CSAF document is generated from the structured sections above. This matters for two reasons: downstream consumers can ingest it automatically, and CRA Annex I Part II expects machine-readable vulnerability information rather than a PDF a human has to read.

A published portal with a CSAF feed is also what satisfies the disclosure policy and security contact item on the conformity checklist.

Practical sequence

  1. A scan produces findings on a release.
  2. Triage decides the component is exploitable in this product.
  3. A fix ships as a new release, or you decide to inform without one.
  4. Draft the advisory, prefill, write the sections, set recommended version and apply-by.
  5. Publish to the portal, notify customers, or both.
  6. If the document changes materially, publish again: the version increments and the revision history shows it.