Plumb

Provides a security policy

Checks whether the repository tells people how to report a security problem privately, usually through a SECURITY.md file.
category
security
weight
3

How Plumb checks this

What is inspected, and how the result is decided.

When someone finds a vulnerability in a package, they need to know where to report it. Without a documented process, many people never report it at all, and others post it in a public issue where attackers can read it before a fix exists. A security policy gives researchers a private place to send reports.

Plumb looks for a SECURITY.md file in the repository root, in .github/, or in docs/. A package registered with Plumb can also supply a security policy during registration, which counts the same way; this is how private repositories satisfy the check.

The check passes when a policy is found in any of those places and fails when none is found. It only checks that a policy exists. It does not judge the writing or test whether the contact address works. If the repository files cannot be read and no registered policy exists, the check is unassessable rather than failed.

Doing it well

Why this matters

Sooner or later someone will find a security problem in your code. What happens next depends on whether they know where to send it. With no instructions, some people give up. Others open a public issue, which tells attackers about the problem before you have a fix. A security policy is a short document that tells people how to reach you privately.

What good looks like

  • A SECURITY.md file in the repository root, or in .github/ or docs/.
  • A private way to report: an email address, a GitHub private vulnerability report link, or a form.
  • A sentence about what the reporter can expect: how quickly you will reply and which versions you fix.

How to do it

  1. Create SECURITY.md at the root of your repository.
  2. Write down how to report a problem privately. Keep it short; a few lines is plenty.
  3. If your repository is on GitHub, turn on private vulnerability reporting under Settings, then Code security. Link to the "Report a vulnerability" button from your policy.
  4. Commit the file to your default branch.

A complete policy can be as simple as this:

# Security Policy

## Supported versions

| Version | Supported                            |
| ------- | ------------------------------------ |
| 3.x     | Yes                                  |
| 2.x     | Security fixes only until 2027-01-01 |
| < 2.0   | No                                   |

## Reporting a vulnerability

Please do not open a public issue. Email [email protected], or use
"Report a vulnerability" on the Security tab of this repository.

You will get a reply within 3 working days. Once a fix is ready we will
release it, publish an advisory, and credit you unless you prefer otherwise.

Things to watch for

  • A policy that points to a public channel. "Open an issue" defeats the purpose. Give a private route.
  • An address nobody reads. Use a mailbox that is monitored, or the platform's built-in private reporting.
  • Putting the policy only in the README. Tooling and GitHub's Security tab look for a dedicated SECURITY.md file. Keep the README link if you like, but have the file too.
  • Forgetting to say which versions you support. Reporters need to know whether an old version still counts.

Further reading