security.txt: what the file is, which fields RFC 9116 defines, and where it goes
security.txt is a short text file at /.well-known/security.txt that tells a security researcher how to report a vulnerability to you. RFC 9116 requires two fields in it, Contact and Expires. It asks to be contacted; it does not protect, hide or block anything. This page explains each field, shows an example file for example.com and covers signing.
Quick facts
- Location
- /.well-known/security.txt; /security.txt is a legacy fallback (section 3)
- Delivery
- HTTPS only, Content-Type text/plain with charset utf-8 (section 3)
- Required fields
- Contact and Expires (section 2.5)
- Standard
- RFC 9116, published in April 2022; the format is also described at securitytxt.org
- Signature
- Recommended, not required: OpenPGP cleartext (section 2.3)
- Scope
- Applies only to the host or IP address it was fetched from (section 3.1)
- Permission to test
- The file neither grants nor denies it; that belongs in a Policy (section 5.5)
- Also searched as
- security.txt, .well-known/security.txt, security txt file, RFC 9116
The short version: security.txt is a signpost. It does not protect anything, and it is not a vulnerability program by itself. It answers one question for a stranger who has found a flaw: whom do I tell?
What the file is for
A researcher who spots a weakness on a website usually has no idea who to write to. Guessing at addresses, hunting through a contact form or posting in public all go badly for both sides. RFC 9116 was written to remove that guesswork: a fixed address, a fixed format, a few fields a script can parse.
That is the whole job. The file names a way to reach you, says how long that information stays valid, and can point to a disclosure policy, an encryption key and a thank-you page. Everything else about running a program, such as triage, rewards and fixing, happens elsewhere. If a report arrives, the work looks like any other incident.
The file is also public by design. Anyone can fetch it, including scrapers and spammers; the RFC itself lists extra unsolicited mail and automated reports as a cost of publishing it (section 5.8). Use a role address that several people read rather than one person's inbox.
The fields
Field names are case-insensitive, each field sits on its own line, and a line that starts with # is a comment (sections 2 and 2.1). Every field except Contact and Expires is optional, and a reader must ignore fields it does not know.
| Field | Status | What it holds |
|---|---|---|
| Contact | Required, may repeat | A mailto:, tel: or https:// URI. List the preferred channel first. The RFC points to the conventions of RFC 2142 for security mailboxes |
| Expires | Required, once | An ISO 8601 date and time in the RFC 3339 profile. The RFC recommends less than a year ahead |
| Encryption | Optional, may repeat | Where to find the key for encrypted reports, as a link or a fingerprint reference. Keys are never pasted inline |
| Policy | Optional, may repeat | An https:// link to your disclosure policy: what is in scope, what you promise researchers |
| Preferred-Languages | Optional, once | Comma-separated language tags (RFC 5646). Order is not a priority; if absent, English is assumed |
| Canonical | Optional, may repeat | The https:// address or addresses where this exact file is meant to be served |
| Acknowledgments | Optional, may repeat | A page that thanks people who reported issues |
| Hiring | Optional, may repeat | A link to security job openings |
Three of these deserve a closer look.
- Contact. Put the best channel first. An https:// URI can point to a web form or a vulnerability-reporting page. Whatever you list, someone must read it, and answer within a time you are willing to state in the policy.
- Expires. It is there to stop old files from misleading people. The RFC says (section 5.3) that no file may be better than one with stale details, so choose a date you will really renew, and put a reminder in a calendar.
- Encryption. It names a key for encrypted reports. A researcher must not assume that this key also made the file's signature (section 2.5.4); the two jobs are separate.
New fields can be added through the IANA registry of security.txt fields, so the list above can grow. A parser written today should skip what it does not recognise.
An example file
This file describes the fictional domain example.com. Every address, key location and date is a placeholder; replace them with your own, and do not copy the dates.
# Reports of security issues in example.com and its services
Contact: mailto:security@example.com
Contact: https://example.com/report-a-vulnerability
Expires: 2027-06-30T23:59:59Z
Encryption: https://example.com/.well-known/pgp-key.txt
Policy: https://example.com/disclosure-policy
Preferred-Languages: en, de
Canonical: https://example.com/.well-known/security.txt
Two Contact lines mean two ways in, in order of preference. The Expires value is a UTC timestamp with a trailing Z. There is one Preferred-Languages line, even though it holds two languages, because the field may appear only once. Canonical names the one address this file is meant to be served from.
The securitytxt.org site has a form that builds a file like this one. You can also write it by hand in a text editor; there is nothing to install. This page does not generate or check files for you.
Where it lives and how it is served
Web services place the file under /.well-known/security.txt. A copy at /security.txt is allowed for older setups, and if both exist, the one under /.well-known/ wins (section 3). The file is fetched over HTTPS and must come with a Content-Type of text/plain and the default charset utf-8.
Scope is narrow. A file applies only to the host or IP address in the URL it was retrieved from, not to subdomains or a parent domain (section 3.1). If you run app.example.com and www.example.com, each needs its own file or a redirect to one. Redirects are allowed, but a researcher is told to look at them before trusting the result (section 5.2).
A short list of ways the setup goes wrong:
- The file returns HTML, such as a soft 404 page with status 200, instead of text.
- It is served over plain HTTP, or from a path under a CMS that rewrites
/.well-known/. - The file is fine on the apex domain and absent on the host that people actually attack.
- The Expires date passed months ago and nobody noticed.
You can look at the result without any tool beyond curl. The -i flag prints headers, and -L follows redirects so you see where you land.
curl -iL https://example.com/.well-known/security.txt
Read the status line, then Content-Type, then the body. For the headers that the rest of your pages send, see HTTP security headers.
Signing the file
Because the file says where to send a report, a forged copy would send reports to the wrong place. The RFC therefore recommends an OpenPGP cleartext signature (section 2.3). A cleartext signature wraps the text in a header and a signature block, so the file stays readable in a browser, as the second example above shows.
If you sign, add the Canonical field. The signature then covers the address the file belongs at, and a copy lifted to another host no longer matches. In the other direction, the RFC says that if the address a file was fetched from is not in any Canonical field, its contents should not be trusted (section 2.5.2).
A signature is only as good as the reader's trust in the key. The RFC puts that on the researcher: they must make sure the key is one they trust. Publish the key where people can find it, and renew the signature each time you change Expires, since any edit breaks it.
Signing is a recommendation. A plain file with a correct Contact and a current date is valid and far more useful than no file.
security.txt and robots.txt
Both sit at a fixed address, both are plain text, and both are read by software. After that they part ways.
| security.txt | robots.txt | |
|---|---|---|
| Reader | A person, or a script working for one, who found a flaw | A crawler deciding which URLs to fetch |
| Address | /.well-known/security.txt | /robots.txt |
| Standard | RFC 9116 | RFC 9309 |
| Must have | Contact and Expires | No required rule |
| Missing file | Researchers guess, or look elsewhere | A 4xx lets a crawler access any resource |
| Controls access | No | No |
Neither file protects anything. The robots.txt page, robots.txt: what it is and how to check it, covers why a polite request to crawlers is not a lock, and security.txt is the same in a different way: it asks to be contacted and promises nothing on its own. Do not list sensitive paths in either; both are public.
One more difference is worth stating. RFC 9116 says the presence or absence of the file does not grant or deny permission to test a site (section 5.5). If you want to say what is welcome, write it in the policy that the Policy field links to.
Where a WAF helps and where it does not
security.txt is a static document served by your origin or hosting. A WAF does not write it, sign it or renew it, and it cannot tell whether the address in Contact is still read by a human.
- What a filter sees. Requests for
/.well-known/security.txtlike any other path, with their address, headers and rate. Ordinary fetches come from researchers and from automated tools, which the bot detection and content scraper pages describe. Hits on the file in the activity log are normal traffic, not an attack. - What it does not see. Whether a report was sent, who sent it, or whether the file is stale. A wrong Expires date looks like a perfectly healthy 200.
- What can go wrong. A path rule or a client rule that is too wide can end up refusing the researcher who is trying to reach you. After any change, fetch the file as an ordinary visitor and confirm it still returns 200 with the right content type.
Bridge WAF has three modes: off, monitor and block. Start in monitor, which records matches while every request is still served, read what would have been refused, and move a rule to block only when the matches look right. The steps are in WAF monitor mode. Clients that hammer paths, including vulnerability scanners, are a separate question from the file itself; blocking bad bots covers it.
Questions
What is a security.txt file?
A security.txt file is a small plain-text file, published at /.well-known/security.txt, that tells security researchers how to report a vulnerability to the site owner. It is defined in RFC 9116 and needs two fields: Contact and Expires.
Where do I put security.txt?
Put it at /.well-known/security.txt on the host it describes and serve it over HTTPS as text/plain with charset utf-8. RFC 9116 also allows a copy at /security.txt for older setups, but if both exist the file under /.well-known/ is the one to use.
Is security.txt the same as robots.txt?
No. robots.txt tells crawlers which paths they may request. security.txt tells people who find a vulnerability where to send the report. Different readers, different formats, and neither file controls access to anything.
Does security.txt need to be signed?
No, signing is a recommendation, not a requirement. RFC 9116 suggests an OpenPGP cleartext signature, and says that when a file is signed the Canonical field should be included so the signature also covers where the file is meant to live.
What happens when the Expires date passes?
The file counts as stale, and a researcher should not rely on it. RFC 9116 notes that no file can be better than one with outdated details, so set a date you will actually renew, and the RFC recommends less than a year ahead.