How to write a SECURITY.md that researchers can actually use

A SECURITY.md file tells people how to report a vulnerability and which versions you support. GitHub recommends including both. Scorecard also checks for it, expecting contact details and disclosure guidance. Keep it short, name a private channel, and state what the reporter can expect in reply.

Why it matters

Without a stated channel, a researcher who finds a flaw has two bad options: open a public issue, which discloses it to everyone, or guess at an email address. A clear file removes that guesswork. GitHub's documentation says to include the supported versions of your project and how to report a vulnerability.

Scorecard's Security-Policy check, rated Medium, looks for a SECURITY.md with contact details, descriptive text and vulnerability and disclosure guidance. The remediation is to add the file in the root directory.

What to put in it

1. A private reporting channel. An email address that more than one person reads, or GitHub's private vulnerability reporting. See how to enable it.
2. Supported versions. A short table saying which release lines get security fixes.
3. What to include in a report. Affected version, steps to reproduce, impact, and any proof of concept.
4. Response expectations. When you will acknowledge a report. Pick a number you can keep, because a promise you miss is worse than none.
5. Disclosure approach. Whether you coordinate a public date with the reporter, and how credit is handled.
6. A request not to file public issues for vulnerabilities.

A starter template

# Security Policy

## Supported versions
| Version | Supported |
| ------- | --------- |
| 2.x     | yes       |
| 1.x     | security fixes only |

## Reporting a vulnerability
Please do not open a public issue. Use the "Report a vulnerability"
button on the Security tab, or email security at example.org.

We aim to acknowledge reports within five business days and will
agree a disclosure date with you. We credit reporters who want it.

Replace the contact details and the timing with ones you will honor.

Adding it on GitHub

Open the repository's Security tab, choose Security policy under Reporting, and click Start setup. GitHub creates SECURITY.md and asks you to commit it, opening a pull request if you are on the default branch.

Common mistakes

• A dead or unmonitored mailbox.
• Listing every version ever released as supported.
• Promising fixes within a fixed time that a volunteer team cannot meet.
• Burying the file in a docs folder where tools and people will not find it. The GitHub page I read only describes the root location, so keep it there.

For a longer treatment of the policy itself, see our guide on writing a vulnerability disclosure policy.

Quick check

Sources

• GitHub: adding a security policy
• Scorecard checks documentation

Last reviewed: 19 October 2026.