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:
- On the repository's main page, click Settings.
- In the Security and quality section of the sidebar, click Advanced Security.
- Click Enable next to Private vulnerability reporting.
Then link to it from your SECURITY.md and your disclosure policy.
Create a draft advisory
- On the repository's main page, open the Security and quality tab.
- In the sidebar, under Reporting, click Advisories, then New draft security advisory.
- Enter a title. Under CVE identifier, enter an existing CVE ID or choose to request one from GitHub later.
- Write the description: the vulnerability, its impact, patches, workarounds and references.
- Under Affected products, set the ecosystem, package name, affected versions and patched versions. Add a product for each package.
- Set the severity, or select Assess severity using CVSS and fill in the calculator.
- Add the CWE under Weaknesses and the reporter under Credits.
- 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
- Open the draft from Security and quality, then Advisories.
- 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.
- Release the fixed versions, and make sure the advisory names them as patched versions.
- 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:
- 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.
- 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.
- Release: the fixed versions go out.
- 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.
- 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.jsonfile 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
Policyfield links your disclosure policy, and the CSAF standard defines aCSAFfield 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