security.txt: a machine-readable vulnerability reporting channel

What it is

RFC 9116 specifies a text file that tells security researchers how to report vulnerabilities. For web services it must be placed at /.well-known/security.txt, retrieved over HTTPS and served as text/plain in UTF-8; a legacy copy at the top level may redirect to it. The format is Field: value lines with # comments. Contact (one or more mailto:, tel: or https:// URIs, listed in order of preference) and Expires (exactly one RFC 3339 timestamp, recommended less than a year ahead) are required. Optional fields: Encryption (where to fetch an OpenPGP key), Canonical (the URIs where the file legitimately lives), Policy (the disclosure policy), Acknowledgments, Preferred-Languages and Hiring. The RFC recommends an OpenPGP cleartext signature over the file, together with Canonical, so that a reader can check it was not planted. The file applies only to the host it was retrieved from, not to subdomains or parent domains.

Why it matters

The OWASP Vulnerability Disclosure cheat sheet asks organisations to publish contact details so that reporting is easy, to acknowledge reports and give a timeline for triage, and lists a security.txt file at the well-known path among the ways to publish those details. Reports that land in a contact form or a marketing inbox are delayed or lost; a stale file (expired, dead mailbox) is worse than none because it signals that nobody is home. For scanners and agents the well-known path is a deterministic place to look.

How to apply

• Create the mailbox or form first and name the person who reads it; then write the file.
• Set Expires about a year out and a reminder to renew it; update Contact when people change.
• Link a Policy page stating scope, acceptable testing, expected response times and whether credit or rewards are offered; promise little and keep it.
• Publish an Encryption key only if someone can decrypt with it; a key nobody uses is a trap for reporters.
• Serve it from a path users cannot write to, and sign it if a key infrastructure exists.
• After each deployment run curl -i https://example.org/.well-known/security.txt and check status and content type.

Pitfalls

Serving it as text/html or behind a login. Copying an example with the example's dates or addresses. Forgetting that the file is per host, so api.example.org needs its own or a redirect. Expecting reporters to follow a policy that was never published.