security.txt Internet Draft

Tuesday 26th December 2017

Security.txt allows web service owners to outline security vulnerability disclosure policies in a simple and easily accessible .txt file format by hosting a security.txt file on their web server, file system or with their project.

It is currently an Internet Draft that has been submitted to the IETF (Internet Engineering Task Force) for RFC (Request for Comments) review.

Please note that this article is about version 01 of the security.txt internet draft, as that was the latest version at the time of writing. Newer versions have now been released with changes, so please see securitytxt.io for the latest version.

Skip to Section:

security.txt Internet Draft
┣━━ Introduction
┣━━ Header Fields
┣━━ Chrome Extension
┣━━ File Location For Websites
┣━━ robots.txt Inclusion
┣━━ Conclusion
┗━━ References

Introduction

The header of the official website for security.txt: https://securitytxt.org/

Abstract:

When security risks in web services are discovered by independent security researchers who understand the severity of the risk, they often lack the channels to properly disclose them. As a result, security issues may be left unreported. Security.txt defines a standard to help organizations define the process for security researchers to securely disclose security vulnerabilities.

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01

According to the latest draft (as of writing this post), security.txt is a standard UTF-8 encoded .txt file that consists of various fields that contain information for security researchers who may wish to disclose a security vulnerability.

The file is comparable to _^{^[HTTP]}robots.txt, however it is primarily designed for human rather than robot consumption, although it's simplicity means that it is also very machine-friendly.

I first came across the original security.txt Internet Draft back in September and thought it looked interesting, however an updated version of the draft has now been released and it seems to have been getting much more attention recently.

Edit 28th Dec 2017 @ 7:18pm: Version 02 of the draft specification was released just a day after I published this blog post. Version 02 is available here and a diff between version 01 and version 02 is here. There are few changes between versions 01 and 02, the addition of the "Policy" header field being the only major one. I have added inline edits to this blog post in order to add details on the newly released draft specification version 02.

A valid security.txt file could look like the following example:

Contact: security@example.com
Contact: https://example.com/contact#security
Encryption: https://example.com/pgp.asc
Acknowledgement: https://example.com/bug-bounty/hall-of-fame
Signature: https://example.com/.well-known/security.txt.sig

This would inform security researchers that:

"security@example.com" is the preferred contact method, however "https://example.com/contact" contains an alternate method.
Researchers can (and should) encrypt their report using the specified encryption key at "https://example.com/pgp.asc".
Valid submissions may be acknowledged/thanked at "https://example.com/bug-bounty/hall-of-fame".
The integrity of the security.txt file can be verified using the signature of a trusted identity.

The security.txt file should be located in the /.well-known/ directory for web properties, and in the root as .security.txt for file systems and version control repositories.

For example, all of the following are valid paths for security.txt as per draft version 01:

      (Sub)Domain Name: https://www.jamieweb.net/.well-known/security.txt
 IPv4 Address (Public): http://203.0.113.1/.well-known/security.txt
IPv4 Address (Private): http://192.168.0.1/.well-known/security.txt
 IPv6 Address (Public): http://[2001:DB8::1234:1]/.well-known/security.txt
IPv6 Address (Private): http://[fd00::1234:1]/.well-known/security.txt
  Version Control Repo: https://github.com/jamieweb/results-whitelist/tree/master/.security.txt
            FTP Server: ftp://ftp.example.com/.security.txt
 Unix-like File System: /.security.txt
   Windows File System: C:\.security.txt
     Windows SMB Share: \\exampleserver\.security.txt

A security.txt file generator is available on the security.txt website, where you can enter your variables and it will generate and offer a file for download. This really isn't needed though, since the format is extremely simple and it's probably easier to create one by hand.

Header Field Specification

The draft specification outlines 4 different header fields that can all optionally be included in your security.txt file. Excluding only the "Signature" header, you can mix and match them as much as you like - you can use the headers in any order and any number of times each, making security.txt as flexible and extensible as possible.

Version 01 of the draft outlines the following 4 header fields:

Contact:

The "Contact" header field is used to specify contact details for security researchers to use to disclose security vulnerabilities. The "Contact" header is the only mandatory field in security.txt:

2.3. Contact: Add an address that researchers MAY use for reporting security issues. The value can be an email address, a phone number and/or a security page with more information. The "Contact:" directive MUST always be present in a security.txt file. URIs SHOULD be loaded over HTTPS. Security email addresses SHOULD use the conventions defined in section 4 of [RFC2142], but there is no requirement for this directive to be an email address. The precedence is in listed order. The first field is the preferred method of contact. In the example below, the e-mail address is the preferred method of contact. <CODE BEGINS> Contact: security@example.com Contact: +1-201-555-0123 Contact: https://example.com/security <CODE ENDS>

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-2-3

The "Contact" field can be either an email address, phone number or link to a page with further information. For email addresses, an RFC2142 security contact email address should be used, which would generally be "security@domain.tld".

Encryption:

The "Encryption" field allows you to add a link to an encryption key that researchers can use for communication. This is highly recommended since vulnerability disclosures may contain highly confidential information.

2.4. Encryption: This directive allows you to add your key for encrypted communication. You MUST NOT directly add your key. The value MUST be a link to a page which contains your key. Keys SHOULD be loaded over HTTPS. <CODE BEGINS> Encryption: https://example.com/pgp-key.txt <CODE ENDS>

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-2-4

I am personally linking directly to my PGP key, however I have also seen other people linking to their Keybase profiles as well as directly to their keys on Keybase. I imagine you could also provide a link to your key on a public keyserver.

Signature:

The "Signature" field allows you to add the signature of your security.txt file, either linked or in-line.

2.5. Signature: In order to ensure the authentic[i]ty of the security.txt file one SHOULD use the "Signature:" directive, which allows you to link to an external signature or to directly include the signature in the file. External signature files should be named "security.txt.sig" and also be placed under the /.well-known/ path. Here is an example of an external signature file. <CODE BEGINS> Signature: https://example.com/.well-known/security.txt.sig <CODE ENDS> Here is an example inline signature. <CODE BEGINS> Signature: -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- <CODE ENDS>

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-2-5 (Square Brackets Mine)

There is nothing in the draft that specifies which key should be used to sign the file, however it would perhaps make sense to use the same key as specified in your "Encryption" field if applicable.

Acknowledgement:

The "Acknowledgement" field allows you to a vulnerability disclosure "hall-of-fame", where researchers are thanked for their work.

2.6. Acknowledgement: This directive allows you to link to a page where security researchers are recognized for their reports. The page should list individuals or companies that disclosed security vulnerabilities and worked with you to remediate the issue. <CODE BEGINS> Acknowledgement: https://example.com/hall-of-fame.html <CODE ENDS> Example security acknowledgements page: We would like to thank the following researchers: (2017-04-15) Frank Denis - Reflected cross-site scripting (2017-01-02) Alice Quinn - SQL injection (2016-12-24) John Buchner - Stored cross-site scripting (2016-06-10) Anna Richmond - A server configuration issue

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-2-6

I have seen people linking directly to their HackerOne program's thank-you page, however any format is acceptable.

Comments can also be included in security.txt by prefixing lines with a hash symbol (#).

Edit 28th Dec 2017 @ 7:26pm: Just one day after publishing this blog post, version 02 of the draft specification was released. This added details on the "Policy" header, which can be used to point researchers in the direction of your security/disclosure policy page. You can read the draft specification for the "Policy" header here.

Chrome Extension

There is also an official Google Chrome/Chromium extension for security.txt, which will automatically scan the website that you are currently browsing for a security.txt file.

The extension can be downloaded from the GitHub repository and installed manually. It is not available on the Chrome Web Store (I prefer it this way since then you can see what you're getting before you actually install it).

The current version of the extension searches for the file at both /security.txt and /.well-known/security.txt, as seen in the code for this version here.

The colour of the extension icon changes to green when a security.txt policy is detected on the current website, and you can click on the icon to see the policy:

Sites where no security.txt file can be found display a bright red icon instead.

There are no configurable options for the current version of the extension (not a bad thing, there really doesn't need to be).

File Location for Websites

The draft specification outlines the standard file name and location for both web properties as well as file systems and version control repositories, however for now I am focusing on web properties.

Version 00 of the draft states that the security.txt file should be at the root of the web server:

2.  The Specification

   Security.txt is a text file located in the website's top-level
   directory.

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-00#section-2

However in draft version 01, this was changed to the /.well-known/ directory on a web server:

3.1.  Web-based services

   Web-based services SHOULD place the security.txt file under the
   /.well-known/ path; e.g. https://example.com/.well-known/
   security.txt.

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-3.1

It is important to know that these directories are not an absolute requirement of the draft standard, as the RFC2119 term "SHOULD" is used.

I have seen a couple of large and reputable sources still using the original draft spec rather than the newer one, and I personally agree with them. I think that the file is far better suited to being in the root of the web server rather than in the .well-known folder.

There are plenty of uses for the .well-known directory, however for this application it just seems to make it unnecessarily clunky and adds extra complication to the setup. I know that it's literally just creating a folder, however for many systems even this could be difficult. For example certain content management systems or web hosting interfaces may restrict access to the .well-known folder or disallow file/folder names with dots. For technical users these issues should be easy to overcome, however security.txt should be as accessible and easy as possible.

On JamieWeb, I am hosting the file at both locations:

https://www.jamieweb.net/.well-known/security.txt
https://www.jamieweb.net/security.txt

I was originally going to add a 301 redirect from /security.txt to /.well-known/security.txt, however I realised that this is not ideal for scrapers/bots since if they don't follow redirects, they'd just get the 301 redirect itself rather than the actual security.txt destination:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="https://www.jamieweb.net/.well-known/security.txt">here</a>.</p>
</body></html>

Instead, I simply created a hard link using ln:

jamie@box:~/path/to/website/root$ sudo ln .well-known/security.txt security.txt

Now I only have to edit one file to update the "files" at both paths, and they can still be read and modified as though they are distinct.

It is also worth noting that security.txt for web properties is not exclusive to traditional domain names, you can also use it for IP addresses and subdomains.

robots.txt Inclusion

In order to tell well-behaved bots to index your security.txt file, use the following syntax for your robots.txt file:

User-agent: *
Allow: /.well-known/security.txt

Conclusion

I have added a security.txt for my website and many others have too. I really hope it catches on as much as robots.txt did and it might be a step towards solving the problem of difficult vulnerability disclosure.

One interesting idea that I had is a security.txt aggregator. One of these may already exist however I'm sure in the future there will be a resource somewhere that scrapes the web and publishes a public list of websites that have security.txt policies. This would be a great way for white-hats to find sites to research on. Perhaps website owners or members of the public could also submit links to security.txt files to add them to the list.

Edit 25th Feb 2018 @ 10:46pm: A security.txt aggregator now exists! See securitytext.org by @AustinHeap.

Another idea that I had for the security.txt specification is to add a "Scope" header field, which would outline the systems that are in-scope of the vulnerability disclosure policy/bug bounty program. I am aware that security.txt already kind-of answers this by stating:

A security.txt file only applies to the domain, subdomain, IPv4 or IPv6 address it is located in.

Source: https://tools.ietf.org/html/draft-foudil-securitytxt-01#section-2

...however, this applies more to the use scope of the contact details rather than researcher activity. Ultimately, security.txt is a disclosure policy rather than a researching policy, so my idea for a "Scope" header perhaps isn't really applicable.

Edit 28th Dec 2017 @ 7:30pm: Just one day after publishing this blog post, version 02 of the draft specification was released. This added details on the "Policy" header, which I described above. This field kind of satisfies my idea for a "Scope" header, since you can link directly to a security/disclosure policy page which will likely include a scope and/or asset list.

A final interesting idea of mine is to add support for Bitmessage addresses in the "Contact" field. The reason I suggest Bitmessage and not other "chat" applications is that the decentralized and secure nature of Bitmessage covers the "Encryption" part as well as the contact method. The encryption used by Bitmessage is completely in control of the user, unlike various other chat applications which provide a managed encryption service which is mostly transparent to the user. Again, there is a good chance that this wouldn't be suitable for the official standard however it is definitely interesting to discuss.