Disclosure policy. The 2017 Snyk State of Open Source Security report shows only 21% of maintainers who do not have a public disclosure policy have been notified privately about a vulnerability. This jumps up to 73% of maintainers who do have a public disclosure policy. This illustrates the importance of defining the procedure of how an issue reporter can fully disclose security issues responsibly. This should include who to contact and how. This is extremely important as it allows you to gain important feedback from your users. People are lazy in general and if there’s no easy of well defined way of doing something, it’s easy for us to not bother doing it at all. Others may log the existence of a vulnerability as an open issue, inadvertently making the world aware of it before a fix is available. Make sure you give your users all the direction they need to give the right information to project maintainers when issues are found.

Security Update policy. Software vulnerabilities are discovered every single day. When a vulnerability is found in your application or library, you have a responsibility to your users to tell them about it. They could be using your open source code in production on critical systems. You need to have a well defined process to share the relevant information to them, including the severity of the vulnerability, the risk it brings, and how to move to a fixed version of your code. Define this process upfront so that the information is pushed to your users, allowing them to be updated as early as possible about new security vulnerabilities as they are found and fixed. This might be as simple as a security mailing list. A SECURITY.md file is a good home for such info on the repo, and if you have a website, consider an independent page for it – see Express.js’s security page as an example.

Security related configuration. The security considerations of your project go beyond your code alone. Users will likely need to configure your project and create settings in order for it to work as they need in their environment. You should provide your users with suggested settings to consider that will harden their security posture when deploying this project. Examples include turning on HTTPS, adding an authorisation layer and of course replacing default passwords (guidance many MongoDB users wish they’ve gotten). Remember that users typically have a fairly low understanding of security, so any advice you can pass on will help them greatly.

Known security gaps & future enhancements. Very rarely are projects in such a state that all the security improvements you want to make have been implemented. It’s important to inform users of the security controls that aren’t currently in place. Your users deserve to know the full story so they can make informed decisions about how they use your project. Who knows – you may even get contributions from your users of a security control implementation on the list! There’s a tradeoff between giving your users the information they need to secure their environment versus enabling an attacker with suggested attack routes. Always consider how the information you share could be used by both parties.

Good examples of SECURITY.md files in the wild can be seen in the Apache Storm and TensorFlow repositories.