security.txt Generator

Someone notices that a web form leaks other people’s records. They did not break in. They would like to tell the owner and get on with their day. Then they discover that there is nobody to tell.

The United States cyber security agency, CISA, set out the reasons a report goes missing when it ordered federal agencies to publish disclosure policies. The first is the plainest: the reporter cannot work out how to report. People who find no authorised channel fall back on their own contacts, or hunt for a staff member’s personal details, or decide the effort is not worth it. The second is silence, because a report that gets no answer teaches the reporter to go public next time. The third is fear: strongly worded legal notices on government systems have left researchers unsure whether good faith will be met with thanks or with a lawyer.

A convention for the first problem has existed since May 1997, when RFC 2142 reserved the mailbox name SECURITY for security bulletins and queries. It gives one channel, by email only, and no place to say how reports are handled. That gap is what the security.txt format was written to fill.

A sign on the door

A security.txt is a short plain text file that says where reports should go. Edwin Foudil posted the first draft on 10 September 2017. The draft went through revisions up to number 12 before it was published as RFC 9116 in April 2022, with Yakov Shafranovich as co-author. It is an informational document, not a standard anyone is obliged to follow, and its own abstract states the purpose modestly: a machine-parsable format that helps organisations describe their disclosure practices.

The file has a fixed home. RFC 8615 reserves the path prefix /.well-known/ on a web server for exactly this kind of agreed location, and RFC 9116 places the file at /.well-known/security.txt. It must be fetched over https and served as plain text in UTF-8. A copy at the top level of the site is tolerated for older habits, but when both exist the well-known one is used. The scope is narrow on purpose. A file speaks for the one host it was fetched from, not for that host’s subdomains and not for the parent domain, so an organisation with twelve hostnames needs twelve files or twelve redirects.

Uptake has been slow. In December 2023 CISA wrote that, according to a recent study, only about half of one percent of the world’s top one million websites published the file. The agency’s own warnings about exploitable systems were being delayed by repeated emails and telephone calls made just to find the right person.

That is a great deal of delay for want of a few lines of text.

Field by field

The grammar is deliberately dull. Each line is a field name, a colon, a space and a value. A line that begins with a hash sign is a comment, blank lines are allowed, and lines may end with a line feed alone or with a carriage return and line feed. Field names ignore case. A reader must skip any field it does not understand, which is how the format can grow without breaking old readers. There are only 2 required fields, Contact and Expires.

Contact is a URI, not a bare address. An email address is written with the mailto scheme, a telephone number with tel, and a web page must begin with https. A bare email address with no scheme in front may look harmless, but by the grammar it is simply not a contact. Several Contact lines may appear, and their order is the order of preference.

Expires is a single date and time in the RFC 3339 form, such as 2027-01-31T00:00:00Z. It may appear only once.

The rest are links. Encryption points to a key for confidential reports; the RFC forbids pasting the key itself into the file. Acknowledgments points to a page thanking past reporters. Policy points to the disclosure policy, Hiring to security jobs. Canonical states the address or addresses where the file is supposed to live. Every one of them, when it is a web address, must use https.

Preferred-Languages is the one field with a list on a single line. It holds language tags in the RFC 5646 form, separated by commas, such as en, es, fr. The tags have equal standing, and if the field is absent a reporter may assume English.

New fields are added through a registry kept by IANA rather than by rewriting the RFC. Two have been registered beyond the original eight: CSAF, defined by the OASIS Common Security Advisory Framework as a link to a provider’s advisory metadata, and Bug-Bounty, whose value is True or False.

Why the file expires

Most configuration files stay correct until someone changes them. This one decays on its own. The person behind the security mailbox leaves, the reporting page moves, the key is replaced, and nothing in the file changes to show it. RFC 9116 is blunt about the consequence: reports may never arrive, or may arrive at the wrong party and expose the flaw to outsiders. It goes as far as saying that having no file may be preferable to having stale information in one.

So the format makes staleness visible. Past its Expires moment a file should not be used, and the RFC recommends setting that moment less than a year into the future. The owner is forced to come back.

A date is easy to get wrong across time zones, and a worked example shows why the offset matters. Take an Expires value of 2027-03-01T00:30:00+05:30, written by someone working five and a half hours ahead of UTC. In UTC that instant is 2027-02-28 19:00:00, the evening of the previous day. A reminder set 30 days earlier therefore falls at 2027-01-29 19:00:00 UTC, not on the 30th. Typing that Expires value into the tool above shows the same UTC time, and the calendar file it saves carries both instants in the UTC form that RFC 5545 defines, so every calendar program places them correctly.

Signing and the Canonical field

A text file on a web server is only as trustworthy as the server. RFC 9116 says so directly: an attacker who has taken over a site can rewrite the file or redirect it, and reports then go to the attacker. Its recommended defence is an OpenPGP cleartext signature, the framework defined in RFC 4880 and carried forward in RFC 9580. The file stays readable as text, with a short header above it and a signature block beneath. Signing tools handle the details, which include prefixing any line that starts with a dash and ignoring spaces at the ends of lines.

A signature alone proves who wrote the text, not where it belongs. A signed file copied to another site would still verify. The Canonical field closes that hole by putting the file’s own address inside the signed text, and the RFC adds that a file retrieved from an address not listed among its Canonical fields should not be trusted. Deciding whether to trust the signing key remains the reader’s job.

It is worth being plain about what a checker in a web page cannot do. It can test that every line fits the grammar, that dates and language tags are well formed, and that links have the right scheme. It cannot verify a signature without a trusted key, and the tool above does not try. It does not fetch anything, so it cannot tell whether a link resolves, whether the file is served with the right content type, or whether anyone reads the mailbox.

What the policy behind the link should promise

The file itself grants nothing. RFC 9116 warns researchers not to read the presence or absence of a security.txt as permission, or refusal, to test. Permission lives in the policy that the Policy field points to.

CISA’s Binding Operational Directive 20-01, issued on 2 September 2020, is a useful list of what such a policy must contain, because it was written as a requirement. A policy states which systems are in scope and what kinds of testing are allowed. It says where reports go and what information to include, and that reports may be anonymous. It commits the organisation not to pursue legal action over research done in good faith under the policy. It sets expectations for when a report will be acknowledged, and it carries an issuance date. The directive notes that a security.txt is not required but can help people find where to report.

The United Kingdom’s National Cyber Security Centre arrives at much the same list in its disclosure toolkit, which treats communication, policy and security.txt as three parts of one process. Its advice on replying is short and humane: do not ignore the report, thank the finder, do not demand a non-disclosure agreement, and send updates while the fix is under way. NIST’s SP 800-216, published in May 2023, gives federal bodies a framework for the same work.

A starter text can list those headings. It cannot decide your scope or make your legal commitments, which is why any draft needs review by the organisation that will stand behind it.

The file is the smallest part of the arrangement and the only part a stranger sees first. Keep it true, renew it before it lapses, and the person with something important to tell you will know which door to knock on.