security.txt is a small text file on your website, defined in RFC 9116, that tells researchers how to report vulnerabilities. SECURITY.md is a file in your repository that does the same for code contributors and users. An SDK publisher benefits from both, pointing at the same contact and policy.
Definitions
security.txt is a plain text file with fields such as Contact, Expires, Policy, Encryption and Preferred-Languages. RFC 9116 says it is meant to help organizations describe their vulnerability disclosure practices so that researchers can find how to contact them.
SECURITY.md is a Markdown file in a repository. GitHub's documentation says to put information about supported versions and how to report a vulnerability in it, so it appears in the repository's security view.
They serve different readers. A researcher scanning a company domain looks for the first. A developer reading your SDK's repository or package page looks for the second.
What RFC 9116 requires
| Field | Status in the RFC | Notes |
|---|---|---|
| Contact | Must be present | May appear several times: email, web form or phone link |
| Expires | Must be present, once | Recommended less than a year ahead to avoid staleness |
| Policy | Optional | Link to your disclosure policy |
| Encryption | Optional | Link or fingerprint of a key for encrypted reports |
| Canonical | Optional | Where the file is meant to live |
| Preferred-Languages | Optional | Languages you can handle |
Web URIs in these fields must begin with https. The file belongs under the well-known path on your site, at a path ending in /.well-known/security.txt. The RFC allows a legacy copy at the top level of the site, and says that if both exist the well-known one must be used. It also recommends that the file be digitally signed.
Steps to set both up
- Create a monitored mailbox or form for security reports and test it. A contact nobody reads is worse than none.
- Write the disclosure policy: what you will do, how fast you aim to acknowledge, and what researchers can expect. Keep promises you can keep.
- Publish /.well-known/security.txt with Contact, Expires, Policy and Canonical. Put a calendar reminder to renew Expires, because an expired file is considered stale.
- Add SECURITY.md to the SDK repository with supported versions and reporting steps, following the support policy template.
- Make both files use the same contact and link each other, so there is one source of truth.
- Turn on private vulnerability reporting in your code host if it offers it, so reports do not arrive as public issues.
- Link the policy from the package registry listing and the README.
- Rehearse: send a test report and time the acknowledgement.
Common mistakes
- An Expires date in the past, which makes tools treat the file as stale.
- Different contacts in the two files, so reports go to someone who left.
- A policy that asks researchers to sign a long agreement before reporting.
- No supported versions table, which leaves reporters guessing whether an old release matters.
- Publishing the file only on the marketing site and not on the API domain customers actually use. Check which hostnames your SDK talks to.
How this helps customers
Procurement and security teams look for a working disclosure channel when they assess a vendor. CISA's Secure by Design guidance describes transparency and accountability as principles for software makers, and a published reporting path is a visible, low cost example of both.
Quick check
Is security.txt mandatory?
No, it is a convention. Within the file, though, the RFC says Contact and Expires must be present.
Where does security.txt go?
At /.well-known/security.txt on your domain. A copy at the top level path is allowed for legacy reasons, but the well-known one wins if both exist.
Safeguard's compliance and evidence automation can help you keep proof of disclosure processes alongside other controls, and its SBOM and dependency scanning shows what your SDK ships. There is a free scan.
Sources
- RFC 9116: A File Format to Aid in Security Vulnerability Disclosure
- GitHub Docs: Adding a security policy to your repository
- CISA Secure by Design
Last reviewed: 19 October 2026.
