Security.txt: Make Vulnerabilities Easier to Report
We all know that all software has bugs and that security is hard, but somehow we are still surprised when we see new vulnerabilities.
- Vulnerability
-
A bug, flaw, weakness, or exposure of an application, system, device, or service that could lead to a failure of confidentiality, integrity, or availability.
In 2020, there were 18,395 vulnerabilities reported, which means about 50 new vulnerabilities are reported every day. These numbers only include what has been reported to MITRE’s Common Vulnerability and Exposures (CVE) database, which means the actual value is likely much higher. Every year we add more software to the world, so these numbers will only increase. I didn’t list this number here to scare you; more so, they are a fact of life, and we all need to be aware of how to deal with them.
Reporting Vulnerabilities
Vulnerabilities are NOT handled the same way as a typical software bug. A properly handled vulnerability is reported privately to the project’s maintainers, then fixed and released before any information about the vulnerability is made public. It may seem like a good idea to report a security issue on GitHub Issues, but it isn’t! Handling vulnerabilities privately may seem counter-intuitive, especially for open-source projects where everything is public, but this isn’t just good manners, even more importantly it reduces potential exposure for everyone using the project.
Okay, so if not a public issue tracker, then where do you report the issue?
Where do you report a vulnerability
The actual "where do you report a vulnerability" is where things get complicated; every project and company has a different process to handle vulnerabilities. Figuring out who to report an issue to is often an exercise in frustration; try to browse a website, do a Google search, maybe even look on bug bounty sites like HackerOne or Bugcrowd. There is an easier way! Enter security.txt, a draft RFC, that aims to standardize a method for security policies to be discovered.
Defining a security.txt is easy. Create a small .well-known/security.txt file at the root of your domain containing your security team’s contact information. There is even a form on securitytxt.org that will generate one for you in a few seconds!
For example, Okta’s https://www.okta.com/.well-known/security.txt is:
Contact: mailto:security@okta.com (1)
Expires: 2023-01-01T05:00:00.000Z (2)
# Optional Fields
Preferred-Languages: en (3)
Policy: https://www.okta.com/vulnerability-reporting-policy/ (4)
Hiring: https://www.okta.com/company/careers/ (5)| 1 | How to contact the security team. |
| 2 | A date when to consider this data stale. |
| 3 | List of languages the security team prefers. |
| 4 | Link back to a reporting policy page with more details. |
| 5 | Even a link back to relevant job postings. |
The contents of the security.txt, a quick summary of who to contact and where to go to find more information, is not a replacement for existing security policy pages. Still, it can contain additional information such as a company’s PGP keys, acknowledgments, and canonical URL information.
|
If you are familiar with OpenID Connect, the |
Bonus: Update your bug tracking templates
If we as developers were in the habit of reading documentation, RTFM wouldn’t be a thing, or maybe we are just busy:
In general, your users are trying to get something done, and they see reading the manual as a waste of time, or at the very least, as a distraction that keeps them from getting their task done.
joelonsoftware.com
If your project uses a public bug tracker (like GitHub Issues), information about handling security issues needs to be obvious to the reporter. One way to do this is to define a SECURITY.md file and create ISSUE_TEMPLATE.md; that way it’s the first thing the reporter sees when the file an issue. For example, the Spring Security issue template starts with:
<!--
For Security Vulnerabilities, please use https://pivotal.io/security#reporting
-->| What makes this so clever is the HTML comment; only the reporter sees the comment when opening an issue. It doesn’t get displayed when the Markdown is rendered! |
Learn more about application security
Most folks don’t know that vulnerabilities require special handling; it isn’t taught in a typical university computer science curriculum or coding bootcamp. Information about how to report security issues needs to be obvious and easily discoverable.
If you want to learn more about application security, check out these great posts:
If you have questions, please leave a comment below. If you liked this post, follow @oktadev on Twitter, follow us on LinkedIn, or subscribe to our YouTube channel.
Brian Demers is a Developer Advocate at Okta and a PMC member for the Apache Shiro project. He spends much of his day contributing to OSS projects in the form of writing code, tutorials, blogs, and answering questions. Along with typical software development, Brian also has a passion for fast builds and automation. Away from the keyboard, Brian is a beekeeper and can likely be found playing board games. You can find him on Twitter at @briandemers.
Okta Developer Blog Comment Policy
We welcome relevant and respectful comments. Off-topic comments may be removed.