Add a SECURITY.md file to your Azure Repos

This post highlights best practice #4 — adding a SECURITY.md file to your repos — from our series of 8 security best practices for Azure Repos.

Add a SECURITY.md file to your Azure Repos

It’s natural for most project owners and maintainers to add a README.md for their repository. In fact, these days it’s expected and it’s quite frowned upon if one is missing. Likewise, it’s becoming increasingly common to add a SECURITY.md file that highlights security-related information for your project. Not only does it give users of your open source project the important security information they need, but it also forces the maintainers to think about how they should deal with security disclosures, updates and general security practices.

Here’s a high level overview of some of the suggested topics that you should cover in the SECURITY.md file:

• 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 the users of your project.If there's no easy 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 project 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 tell the users of your project. 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 project 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 of your open source project likely need to add configuration to your project and create settings in order for it to work as necessary in their environment. You should provide your project users with suggested settings that harden their security posture when deploying this project. Examples include turning on HTTPS, adding an authorization layer and of course replacing default passwords (guidance many MongoDB users wish they’ve gotten). Remember that many 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. 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.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 your project 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 of a security control implementation from your users on the list!

Continue reading the list of 8 Azure Repos security best practices:

1. Never store credentials as code/config in Azure Repos

2. Remove sensitive data in your files and Azure Repos history

3. Tightly control access

4. Add a SECURITY.md file

5. Use Personal Access Tokens

6. Provide granular permissions and groups for users

7. Add security testing to Pull Requests

8. Rotate SSH keys and personal access tokens

If you haven’t done so yet, make sure you download this cheat sheet now and pin it up, so your future decisions are secure decisions.