138% more reported CVEs per day in 2026 than last year.New: always-on Fixboxes. Vulnerable dependencies, fixed and verified.

PSIRT

Security advisory: how to write one, with a template and a worked example

A security advisory is the document your customers act on when a vulnerability affects your product. A good one answers, without a support ticket, whether they are affected, how badly, and what to do. This guide covers the fields, a complete example, the machine-readable formats, GitHub Security Advisories and when to publish.

Updated

What is a security advisory?

A security advisory is a notice from the supplier of a product that describes a vulnerability in it: which products and versions are affected, how severe it is, what an attacker could do, and how users fix or mitigate it. It is written for the people who run the product, and increasingly also for their tools.

Advisories are the public end of coordinated vulnerability disclosure: a finder reports privately, the supplier fixes, and the advisory is how everyone else learns about it. In most software and device companies the PSIRT writes them, as part of a wider product security program.

Security advisory vs security bulletin, CVE record, VEX and release notes

These documents overlap, and teams often mix them up:

Document Who publishes it What it covers Main reader
Security advisory The product's supplier, or a coordinator One vulnerability, or a few related ones, in your products: affected versions, severity, fix Customers' operators and security teams
Security bulletin The supplier, often on a fixed schedule A roll-up of many fixes in one release or period. Android's security bulletins, for example, come out on the first Monday of each month. Teams that patch on a cycle
CVE record A CVE Numbering Authority (CNA) The global identifier and a minimum description of one vulnerability: affected product, problem type, description and at least one public reference Vulnerability databases and scanners
VEX statement The supplier A machine-readable status per product and vulnerability: affected, not affected, fixed, under investigation Customers' scanners
Release notes The supplier Everything that changed in a release, security fixes among other changes Anyone upgrading

The usual pattern: one advisory per vulnerability, with a CVE ID that links it to the CVE record, linked from the release notes of every fixed version and from the bulletin if you publish one. "Security bulletin" and "security advisory" are sometimes used as synonyms; what matters is that each vulnerability has a stable page customers can cite.

What a security advisory should include

The fields below are what customers look for, and they map one to one onto the machine-readable formats later in this guide. The CVE Program's CNA rules set the floor for the CVE record: at least one affected product and version, the type or cause of the vulnerability (preferably as a CWE), a prose description and a public reference. A useful advisory goes further.

Field What it says Common mistake
Advisory ID Your own stable identifier, such as EXC-2026-007, plus the CVE ID Using only the CVE ID, which you may not have yet on the day you need to publish
Title Product, vulnerability type and impact in one line "Security update for Product X", which says nothing
Affected products and versions Every affected product and version, as ranges per release branch "Versions before 4.2.2", which wrongly includes branches that never had the bug
Not affected Products and versions you checked and found not affected Leaving it out, so every customer on an older version opens a ticket
Fixed versions The first fixed version on each supported branch Naming only the latest release
Severity A rating and the full CVSS vector, with the CVSS version A bare score with no vector, which nobody can check or adjust to their environment
Weakness The CWE ID and name Omitting it; databases and the CVE rules expect it
Description What the flaw is and where, in enough detail to judge exposure, without a working exploit So vague customers cannot tell whether their configuration is exposed
Impact What an attacker gains, and what they need first (access, role, network position) Repeating the CVSS metrics in words instead of explaining consequences
Workarounds and mitigations What to do if you cannot upgrade today, and how to check whether you were exploited "No workarounds" when a configuration change would block the attack
Credits Who found and reported it, with their consent Crediting someone who asked to stay anonymous
Timeline Reported, confirmed, fixed, published Leaving it out, which makes long delays look hidden
References CVE record, release notes, fix commit, machine-readable versions Links to internal tickets customers cannot open
Revision history Every change after first publication, with a date and version Silently editing the affected versions

The hardest field is the affected versions. The vulnerable code was introduced at some point and fixed at another, and every supported branch has its own fix. If the vulnerability came in through a third-party component, the question becomes which of your releases shipped the vulnerable version of that component, directly or as a transitive dependency. See how to assess a new CVE across your builds.

A worked example

Here is a complete advisory for a fictional product: Example Gateway, a self-hosted API gateway from Example Corp, with two supported branches, 3.9 and 4.x. The vulnerable endpoint was added in 3.9.0, so 3.8 and earlier are not affected. All names, IDs and dates are made up; the CVSS 4.0 score is computed from the vector shown.

Example Corp Security Advisory EXC-2026-007
Path traversal in Example Gateway export API allows reading server files

Advisory ID:    EXC-2026-007
CVE ID:         CVE-2026-XXXXX
Published:      2026-09-01
Last updated:   2026-09-15 (version 1.1)
Severity:       High, CVSS 4.0 base score 7.1
CVSS vector:    CVSS:4.0/AV:N/AC:L/AT:N/PR:L/UI:N/VC:H/VI:N/VA:N/SC:N/SI:N/SA:N
Weakness:       CWE-22, Improper Limitation of a Pathname to a
                Restricted Directory ('Path Traversal')

Affected products
  Example Gateway 4.x    4.0.0 up to and including 4.2.1
  Example Gateway 3.9    3.9.0 up to and including 3.9.6

Fixed versions
  Example Gateway 4.2.2
  Example Gateway 3.9.7

Not affected
  Example Gateway 3.8 and earlier (the export API was added in 3.9.0)
  Example Gateway Cloud (patched on 2026-08-28; no action needed)

Description
  The export endpoint of the admin API (/api/v1/export) does not
  normalize the file name parameter. A request containing "../"
  sequences can read any file the gateway process can read.

Impact
  An authenticated user with any role, including the read-only
  "viewer" role, can read files on the gateway host. These include
  gateway.yaml, which holds the database password and the signing key
  for admin sessions. With that key an attacker can forge an admin
  session. Unauthenticated users cannot exploit this vulnerability.

Workarounds
  If you cannot upgrade right away:
  1. Remove the viewer role from accounts that do not need it.
  2. Block requests to /api/v1/export at your reverse proxy.
  After upgrading, rotate the database password and the session
  signing key if untrusted users held any admin API role.

Detection
  Requests to /api/v1/export with "..", "%2e%2e" or "%2f" in the
  file parameter appear in the gateway access log.

Credits
  Example Corp thanks A. Researcher of Example Security Lab for
  reporting this vulnerability through coordinated disclosure.

Timeline
  2026-08-04  Reported to [email protected]
  2026-08-05  Report acknowledged
  2026-08-08  Vulnerability confirmed, CVE ID requested
  2026-08-28  Example Gateway Cloud patched
  2026-09-01  4.2.2 and 3.9.7 released, advisory published
  2026-09-15  Advisory updated (version 1.1)

References
  CVE record:            https://www.cve.org/CVERecord?id=CVE-2026-XXXXX
  Release notes 4.2.2:   https://example.com/gateway/releases/4.2.2
  Release notes 3.9.7:   https://example.com/gateway/releases/3.9.7
  CSAF version:          https://example.com/security/csaf/2026/exc-2026-007.json

Revision history
  1.0  2026-09-01  Initial publication
  1.1  2026-09-15  Added 3.8 and earlier as not affected; added the
                   reverse proxy workaround

Three things make this advisory work:

  • Ranges per branch. "4.0.0 to 4.2.1" and "3.9.0 to 3.9.6" are exact. "Before 4.2.2" would have told every 3.8 customer they were affected.
  • The impact names the precondition. A customer with no viewer accounts knows their real exposure is low; one with hundreds of contractors in the viewer role knows it is not.
  • The workaround includes the follow-up. Upgrading closes the hole but does not undo a leaked secret, so the advisory says what to rotate.

A security advisory template you can copy

Replace the bracketed parts. Delete a section only if it truly does not apply, and say so rather than leave it blank where customers expect it (for example "No workarounds are available").

[Company] Security Advisory [ADVISORY-ID]
[Vulnerability type] in [product] [component] allows [impact]

Advisory ID:    [ADVISORY-ID]
CVE ID:         [CVE-YYYY-NNNNN, or "requested"]
Published:      [YYYY-MM-DD]
Last updated:   [YYYY-MM-DD] (version [1.0])
Severity:       [Critical/High/Medium/Low], CVSS [4.0] base score [N.N]
CVSS vector:    [CVSS:4.0/AV:_/AC:_/AT:_/PR:_/UI:_/VC:_/VI:_/VA:_/SC:_/SI:_/SA:_]
Weakness:       [CWE-NNN, CWE name]

Affected products
  [Product] [branch]    [first affected] up to and including [last affected]
  [Product] [branch]    [first affected] up to and including [last affected]

Fixed versions
  [Product] [fixed version]
  [Product] [fixed version]

Not affected
  [Products and versions checked and not affected, and why]

Description
  [What the flaw is and where it is. Enough detail to judge exposure;
  no exploit code.]

Impact
  [What an attacker can do, and what they need first: network access,
  an account, a role, user interaction, a non-default setting.]

Workarounds
  [Steps to reduce risk until users can upgrade, or "No workarounds
  are available." Also anything to do after upgrading, such as
  rotating secrets.]

Detection
  [How users can tell whether they were attacked, if known.]

Credits
  [Name and affiliation of the reporter, with their consent.]

Timeline
  [YYYY-MM-DD]  Reported
  [YYYY-MM-DD]  Confirmed
  [YYYY-MM-DD]  Fixed versions released, advisory published

References
  CVE record:          [URL]
  Release notes:       [URL]
  Machine-readable:    [CSAF, OSV or VEX URL]
  Disclosure policy:   [URL]

Revision history
  1.0  [YYYY-MM-DD]  Initial publication

Human-readable vs machine-readable advisories

A web page is enough for people. It is not enough for a customer with thousands of devices or hundreds of services, whose tools need to match your advisory against what they run. Three families of formats do that, and they answer different needs:

Format What it is Use it when
Web page (and PDF) The advisory as people read it Always. Every other format links back to it.
CSAF 2.0 The OASIS standard for advisories as JSON, with a product tree, product status lists, remediations, a revision history and rules for distribution You sell products such as firmware, appliances or enterprise software to customers who automate advisory intake, often industrial and enterprise buyers
OSV The Open Source Vulnerability format: JSON entries for packages in a named ecosystem, with version ranges. The GitHub Advisory Database publishes its advisories in it. You ship open-source packages through npm, PyPI, Maven, Go modules and similar ecosystems
VEX (CSAF VEX, CycloneDX VEX, OpenVEX) Statements that a product is or is not affected by a known vulnerability, and why Customers scan your SBOM and ask about CVEs in components that do not affect your product

The worked example in CSAF 2.0 becomes a csaf_security_advisory document: the advisory ID goes in document/tracking/id, the revision history in document/tracking/revision_history, the affected and fixed versions in each vulnerability's product_status lists, the CWE in its cwe object and the workarounds in remediations. One catch: CSAF 2.0 scores take CVSS v2 and v3.x only. CVSS v4.0 support comes with CSAF 2.1, which is still a draft, so a CSAF 2.0 advisory either carries a CVSS 3.1 vector or gives the 4.0 vector in a note.

The same advisory as an OSV entry, for teams that also ship the gateway as an npm package (excerpt):

{
  "id": "EXC-2026-007",
  "aliases": ["CVE-2026-XXXXX"],
  "summary": "Path traversal in export API allows reading server files",
  "published": "2026-09-01T09:00:00Z",
  "modified": "2026-09-15T09:00:00Z",
  "severity": [
    {
      "type": "CVSS_V4",
      "score": "CVSS:4.0/AV:N/AC:L/AT:N/PR:L/UI:N/VC:H/VI:N/VA:N/SC:N/SI:N/SA:N"
    }
  ],
  "affected": [
    {
      "package": { "ecosystem": "npm", "name": "@example/gateway" },
      "ranges": [
        {
          "type": "SEMVER",
          "events": [
            { "introduced": "3.9.0" },
            { "fixed": "3.9.7" },
            { "introduced": "4.0.0" },
            { "fixed": "4.2.2" }
          ]
        }
      ]
    }
  ],
  "credits": [{ "name": "A. Researcher", "type": "FINDER" }]
}

Note how the range carries two introduced-fixed pairs. The OSV schema treats a version as affected if it falls in any range or appears in the explicit versions list, and recommends fixed over last_affected because a last-affected bound can cause missed matches.

Decision rule: always publish the web page and a CVE. Add OSV, usually by publishing through GitHub, if you ship open-source packages. Add CSAF if you sell products to organizations that ask for machine-readable advisories or work under the EU Cyber Resilience Act, whose Article 14(8) asks for a structured, machine-readable format where appropriate when informing users about actively exploited vulnerabilities. Add VEX once customers start sending you scanner output about your components. Generate every format from one record so they never disagree.

GitHub Security Advisories

If your project is a public repository on GitHub, GitHub's repository security advisories give you the whole flow in one place: a private draft to discuss the vulnerability, a temporary private fork to fix it, a CVE request, and publication. Four pieces fit together:

  • Repository security advisories: drafts and published advisories that belong to your repository.
  • Private vulnerability reporting: a "Report a vulnerability" button on the repository's Advisories page, so researchers can report to you privately instead of opening a public issue.
  • CVE IDs from GitHub: GitHub is a CNA and can assign a CVE ID to your advisory, unless your project is covered by another CNA.
  • The GitHub Advisory Database: for supported ecosystems, GitHub publishes your advisory there, in OSV format, and may use it to send Dependabot alerts to repositories that depend on your package.

Turn on private vulnerability reporting

Owners and administrators of a public repository can enable it:

  1. On the repository's main page, click Settings.
  2. In the Security and quality section of the sidebar, click Advanced Security.
  3. Click Enable next to Private vulnerability reporting.

Then link to it from your SECURITY.md and your disclosure policy.

Create a draft advisory

  1. On the repository's main page, open the Security and quality tab.
  2. In the sidebar, under Reporting, click Advisories, then New draft security advisory.
  3. Enter a title. Under CVE identifier, enter an existing CVE ID or choose to request one from GitHub later.
  4. Write the description: the vulnerability, its impact, patches, workarounds and references.
  5. Under Affected products, set the ecosystem, package name, affected versions and patched versions. Add a product for each package.
  6. Set the severity, or select Assess severity using CVSS and fill in the calculator.
  7. Add the CWE under Weaknesses and the reporter under Credits.
  8. Click Create draft security advisory.

The draft stays private. From it you can add collaborators, start a temporary private fork to prepare the fix, and discuss the details with the reporter.

Request a CVE and publish

  1. Open the draft from Security and quality, then Advisories.
  2. At the bottom of the form, click Request CVE. Requesting a CVE does not make the advisory public, and GitHub says it usually reviews requests within 72 hours, so request early.
  3. Release the fixed versions, and make sure the advisory names them as patched versions.
  4. Click Publish advisory. The temporary private fork is deleted, GitHub publishes the CVE details, and for supported ecosystems the advisory reaches the GitHub Advisory Database. Dependabot alerts can take up to 72 hours.

If you publish without a patched version, GitHub warns that Dependabot alerts users without suggesting a safe version. GitHub's advisory database supports both CVSS 3.1 and 4.0. Steps follow GitHub Docs as of November 2026; labels in the GitHub interface change from time to time.

GitHub advisories fit open-source packages in the ecosystems GitHub supports. For firmware, appliances or closed-source products, publish on your own site, in CSAF where customers expect it, and get the CVE from your own CNA or one whose scope covers you.

When to publish: timing and embargo

The embargo, the period between the private report and publication, and how long it should last belong in your disclosure policy. The advisory's job is to land at the right moment within it. A typical publication day runs like this:

  1. Before the day: fixes are ready on every supported branch, the CVE ID is reserved, and the advisory and every machine-readable version are written and reviewed.
  2. Advance notice, if you give it: large customers, downstream vendors that embed your product and coordinators get the advisory under embargo a few days early, so they are ready to answer their own customers.
  3. Release: the fixed versions go out.
  4. Publish: the advisory page, the CVE record, the CSAF or OSV documents and the feed entry go live together, ideally within the same hour as the release.
  5. Notify: mailing list and direct notices to affected customers.

The order matters. Publishing the fix first without the advisory lets attackers diff the release while defenders do not know to upgrade. Publishing the advisory without a fix is right only when the vulnerability is already public or exploited: then publish what you know with mitigations, and update it when the fix ships.

Under the Cyber Resilience Act, an actively exploited vulnerability also triggers a separate duty to report to authorities: an early warning within 24 hours through the Single Reporting Platform, then a notification and a final report. That is not your advisory, and it is not public. Annex I of the CRA also asks manufacturers to publicly disclose information about fixed vulnerabilities once a security update is available, which is what an advisory does. See what the CRA requires.

Publishing: where advisories live

  • A stable page per advisory, at a URL that never changes, such as /security/advisories/exc-2026-007, plus an index page that lists every advisory with its products, severity and dates.
  • A feed. An RSS or Atom feed of the index lets people subscribe without a mailing list.
  • CSAF provider metadata, if you publish CSAF: a provider-metadata.json file and a directory or ROLIE feed of the documents, so tools find every advisory without scraping. See CSAF for the roles and requirements.
  • A pointer in security.txt. The Policy field links your disclosure policy, and the CSAF standard defines a CSAF field that points tools to your provider metadata:
Contact: mailto:[email protected]
Expires: 2027-09-30T23:00:00.000Z
Policy: https://example.com/security/disclosure-policy
CSAF: https://example.com/.well-known/csaf/provider-metadata.json

Never delete a published advisory. If it turns out to be wrong, publish a revision that says what changed; if the vulnerability was not real, mark the advisory withdrawn and say why.

Notifying customers

Publishing is not the same as being read. Customers who do not subscribe to your feed will not see the advisory until their scanner flags the CVE, or until someone asks them about it. For high and critical advisories:

  • Email the customers who run affected versions, not your whole list, with the advisory link and the one action they need to take.
  • Brief your support and sales teams before publication, with the advisory and a short FAQ, so their answers match it.
  • Tell downstream vendors who embed your product, so their own advisories can follow quickly.
  • Follow up with customers who stay on affected versions.

Emailing only the affected customers requires knowing which product versions each one runs. For a vulnerability in a third-party component that hit many vendors at once, see how to answer customers after a supply chain attack, which includes templates.

Should you become a CNA?

A CVE Numbering Authority (CNA) assigns CVE IDs and publishes CVE records for vulnerabilities in an agreed scope, usually its own products. Becoming one lets you control when the CVE record appears, assign IDs without sharing embargoed details with another CNA, and write the record yourself.

According to the CVE Program, there is no fee and no contract. A CNA must have a public vulnerability disclosure policy, a public source for new vulnerability disclosures (your advisory page) and agree to the program's terms of use. Onboarding runs through a registration form, an introductory session and practice examples. In the EU, ENISA acts as a Root for organizations in its scope, including technology vendors and open source projects.

  • It fits a vendor that publishes CVEs regularly for its own products, already runs a PSIRT and an advisory page, and wants control over timing.
  • It does not need to be your first step if you publish a handful of CVEs a year, or if your products are open-source packages on GitHub, where GitHub can assign the IDs as part of the advisory.

For CVE IDs without being a CNA, see coordinated vulnerability disclosure.

Where CRACI fits: the affected versions

Most of an advisory is writing. The field that needs evidence is the affected versions, and for vulnerabilities in third-party components it is also the hardest to get right: which of your releases shipped the vulnerable version, including as a transitive dependency, and since when.

CRACI runs your GitHub Actions builds on its own runners and records the packages each job actually fetched, including transitive dependencies and packages restored from CI caches. Each package shows its advisories (CVE, GHSA and other IDs) with severity. Build history shows every past build and its SBOM, and which builds contained a vulnerable dependency, so you know the period you were affected, within your retention period (180 days by default, custom on Enterprise). Security teams triage the findings and send them to the teams that own the fix, and CRACI notifies the relevant people of a vulnerability and its severity. See vulnerability tracking.

When an actively exploited vulnerability triggers the CRA's reporting duty, CRACI prepares the content of the notifications (early warning, notification and final report); a person at your company submits them through the Single Reporting Platform.

When CRACI is not the answer

  • Writing and publishing the advisory. CRACI does not write or publish security advisories, in CSAF or any other format. Use your own site, GitHub Security Advisories or a CSAF tool for that.
  • Receiving reports. CRACI does not take in vulnerability reports from researchers or customers, or track them as cases. Use your disclosure inbox, GitHub private vulnerability reporting or a case tracker.
  • Vulnerabilities in your own code. CRACI matches advisories against the packages your builds fetched. A flaw like the path traversal in the example, in your own code, needs code review to find when it was introduced.
  • Builds outside GitHub Actions. CRACI supports GitHub Actions today; GitLab CI and Jenkins are on the roadmap.
  • Releases older than your retention period. Build history covers the builds CRACI has recorded and kept.

Security advisories: frequently asked questions

What is a security advisory?

A security advisory is a notice from a product's supplier that describes a vulnerability in the product: which products and versions are affected, how severe it is, what an attacker could do, and how to fix or mitigate it. It usually carries a CVE ID and is published once a fix is available.

What is the difference between a security advisory and a security bulletin?

An advisory usually covers one vulnerability, or a few related ones, in detail. A bulletin rolls up many fixes for one release or period, often on a fixed schedule; Android, for example, publishes its security bulletins monthly. Some vendors use the two words interchangeably.

What should a security advisory include?

An advisory ID and CVE ID, a title, affected products and versions as ranges per branch, products checked and not affected, fixed versions, severity with the full CVSS vector, the CWE, a description, the impact and its preconditions, workarounds, credits, a timeline, references and a revision history.

How do I create a GitHub security advisory?

In a public repository, open the Security and quality tab, click Advisories under Reporting, then New draft security advisory. Fill in the title, description, affected products, severity, CWE and credits, and save the draft. When the fix is released, request a CVE if you need one and click Publish advisory.

Can GitHub assign a CVE ID to my advisory?

Yes, if your project is not covered by another CNA. GitHub is a CVE Numbering Authority. Request the CVE from the draft advisory; the request does not make the advisory public, and GitHub says it usually reviews requests within 72 hours. GitHub publishes the CVE details once the advisory is public.

Should security advisories be machine-readable?

Increasingly, yes. Publish a web page for people, and add a machine-readable version for customers who automate: CSAF for products sold to enterprises and industry, OSV for open-source packages, and VEX to say which known vulnerabilities do not affect your product. Generate them from the same record.

When should a security advisory be published?

At the same time as the fixed versions, after any advance notice to key customers and downstream vendors under embargo. Publish earlier, with mitigations, only if the vulnerability is already public or being exploited, and update the advisory when the fix ships.

Do I need to be a CNA to publish a security advisory?

No. Anyone can publish an advisory. Being a CVE Numbering Authority only means you can assign CVE IDs yourself. Without it, a CNA whose scope covers your product, GitHub for open-source projects on GitHub, or a CNA of Last Resort can assign the ID.

Know which releases to list as affected

An advisory is only as accurate as its affected versions. Book a demo to see which of your GitHub Actions builds contained a vulnerable package.

Book a demo