A File Format to Aid in Security Vulnerability Disclosure

The Problem and Solution

In an age where scoring bug bounties is some peoples' primary source of income, and responsible disclosure is the norm rather than the exception, it can be quite difficult to figure out where and how to report a security vulnerability. I ran into that problem with a vendor of mine. I came across a problem involving unescaped input, and searched high and low for a way to securely report it. In the end, I opened a ticket with their help desk, where they had me just tell them the problem in a clear-text email.

I'm not alone, either. In fact, in the Spring 2021 issue of 2600: The Hacker Quarterly, fellow reader Keifer Chiang wrote about finding a bug in a municipal web portal, and the weeks-long ordeal of trying to get his report securely into the eyeballs of the right person.

How many vulnerabilities have gone unreported, sold on the dark web, or simply blurted out on Twitter, only because getting in touch with the appropriate person was impossible?

When a security issue needs to be reported, time is of the essence. There needs to be a quick, standard way to find the right contact information, their encryption keys, and the preferred way to file your report. Fortunately, there is a standard, meekly called the security.txt file.

security.txt is a plain, UTF-8 encoded text file that is designed to be both human- and machine-readable. For ease of discovery, it lives in the well-known .well-known folder on the root of your Web server.

Example

In this article, let's assume we're looking at a security.txt file for the popular fictional company, Contoso:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

# This is the "security.txt" file for Contoso.com.
Canonical: https://contoso.com/.well-known/security.txt
Canonical: https://www.contoso.com/.well-known/security.txt
Canonical: https://webapp.contoso.com/.well-known/security.txt

# For security issues, please contact our security team.
# Email is preferred, but you may also call us or chat with us.
Contact: mailto:security@contoso.com
Contact: tel:+1-800-555-5555,123
Contact: MSTeams:/l/chat/0/0?users=alice@contoso.com,bob@contoso.com
Contact: https://contoso.com/contact-us#security-disclosures

# Our PGP key is available in a variety of places.
Encryption: https://contoso.com/pgp/securityteam.asc
Encryption: dns:5d2d3ceb7abe552344276d47d36a8175b7aeb250a9bf0bf00e850cd2._openpgpkey.contoso.com?type=OPENPGPKEY
Encryption: openpgp4fpr:1234567890ABCDEF1234567890ABCD

# We speak English, Spanish, and French.
Preferred-Languages: en, es, fr

# We welcome you to explore our site for bugs, but before you do, please
# read our disclosure agreement.
Policy: https://contoso.com/security-policy.html

# Thank you for your reports!  Why not join our security team?
Acknowledgments: https://contoso.com/humans.txt
Hiring: https://contoso.com/jobs#security

Expires: 2021-12-31T23:59:59Z

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEE8QHuP28wHqb4E6Yt4H79M4zP+valid+signature+here=
-----END PGP SIGNATURE-----

That's a lot to take in at once, so let's break it down. Aside from the comments, there are many fields you can use in a security.txt file. All fields can appear in any order, most fields are optional, and many of them can be repeated as many times as necessary. Most field values accept a URI, which can be of any scheme except non-secure HTTP.

Canonical

The first field is called Canonical. This should specify the URLs used to reach this security.txt file, to ensure that security researchers have found the correct file.

How to Make Contact

Up next is Contact, and this one is mandatory. This is where you specify your points of contact, in URI format, in order of preference. In this example, I've included an email address, a phone number, a link to start a Microsoft Teams chat with our old friends Alice and Bob, as well as a webpage with contact information. That should be enough for anyone.

Next, we have the Encryption field, where you provide URIs to download or find an encryption key, usually an OpenPGP key or S/MIME certificate. In this example, the contacts' PGP key can be downloaded from the web server or directly from a DNSSEC-signed DNS zone. The fingerprint is also provided, not only for reference, but in case the researcher wants to download it on their own.

Preferred-Languages is fairly obvious. List all human languages that your contacts understand. This field can only appear once, so list them all in one line.

You may want people to follow some ground rules when searching for or reporting bugs. If you have a security policy, use the Policy field to link people to it.

Just for Kicks

Of course, no standard would be complete without a few fun things. Acknowledgments links to a resource where this company will thank security researchers who have helped them out, and if you need to bolster your company's own red or blue teams, Hiring is a link to your security-related job postings.

Tying It All Together

Finally, there is the required Expires field, to make sure that anyone who might be reading this file knows that they have fresh data. The security.txt standard recommends that this timestamp be no more than one year in the future.

Now that you have your security.txt file, it's recommended that you PGP-clearsign it, to prove to your reader that all of the data is authentic and correct. Once that's done, upload it to your HTTPS-enabled web server. Now, you can sleep easier, knowing that if there is a problem, a security researcher will know how to reach you.

In Conclusion

Oh, and that vendor I mentioned at the top of the article? They now have their own security.txt file.

The security.txt standard exists as RFC 9116, developed by Edwin "EdOverflow" Foudil, Yakov Shafranovich, and the open-source community. To learn more, please visit securitytxt.org.