Open with one paragraph of 40 to 60 words that answers three questions: who is affected, what they should do, and by when. Put the product and version range in the first sentence. Save background, credit and root cause for later sections, where people who want them can find them.
Why the first paragraph carries the page
Most readers decide in seconds whether an advisory concerns them. Support staff paste the opening into tickets. Assistants and search tools often quote the first clear answer they find. A first paragraph that says "we take security seriously" wastes all three.
The goal is a paragraph that stands alone. If it is the only thing a customer reads, they should still know what to do.
The formula
- Name the product and the affected versions.
- Say what the flaw allows, in plain words.
- State the fix or workaround and the fixed version.
- State exploitation status with a date, if you know it.
- Give the date of the advisory.
Aim for two or three sentences. Count the words.
Three weak openings and their fixes
| Weak opening | Why it fails | Better |
|---|---|---|
| "We recently became aware of an issue." | No product, no action | "Versions 2.1 to 2.4 of the export service allow an unauthenticated user to read files. Upgrade to 2.4.1." |
| "A researcher reported a critical flaw." | Credit before help | Lead with who is affected, credit later |
| "Please read the details below." | Pushes the answer away | Put the action first |
A worked example
"Versions 2.1 to 2.4 of the export service let an unauthenticated user read files on the host. Upgrade to 2.4.1 or disable the export endpoint. We are not aware of exploitation as of the date of this advisory. Versions before 2.1 are not affected."
That is about 50 words. It answers who, what and by when, and it makes one clear statement about what is not affected.
Checklist before you publish
- Does the paragraph survive being copied alone into a support ticket?
- Does it include the version range and the fixed version?
- Does it avoid words like "may" where you do know the answer?
- Does it say what you do not know yet, such as "we are still checking version 1.x"?
- Is every claim something you could defend with evidence?
If you cannot answer one of these, say so openly in the paragraph. "We are checking whether earlier versions are affected and will update by a stated time" is a better opening than a guess.
Things to keep out
Skip apologies in the first paragraph, marketing language, and adjectives such as "sophisticated". Keep the tone calm. The next sections can carry the detail: timeline, technical description, credit and a short FAQ. For the full list of fields, see our post on what to include in a security advisory.
Quick check
Why 40 to 60 words?
It is long enough to carry product, versions, action and status, and short enough to quote or paste whole. The range is a working guideline, not a rule from a standard.
What if we do not yet know the full scope?
Say so, name what you are checking, and give a time for the next update.
Safeguard's SBOM and dependency scanning help teams find which products and versions a library issue touches, so the first paragraph can be specific. Try the free scan at gold.safeguard.sh/scan.
Last reviewed: 19 October 2026.
