• Share this article:

SECURITY.md: should I have it?

Monday, July 31, 2023 - 10:33 by Marta Rybczynska

You might have noticed a SECURITY.md file in git repositories of multiple projects. Should you have it? The answer is yes.

Who uses SECURITY.md?

When a security researcher has a potential vulnerability to communicate to a project, SECURITY.md is one of the first places (if not the first one) they will look into. If they cannot find information in that file, they will look elsewhere: in the README, project documentation, etc.

By having an up-to-date SECURITY.md, you significantly increase the probability of researchers finding the appropriate way to contact the project. You diminish the risk of public issues, messages on IRC...

What should it contain? 

As said above, it should contain information about contacting your project about a potential vulnerability or a security concern. Ideally, there should be a confidential way.

The Eclipse Foundation provides a template for SECURITY.md, you can find it here https://gitlab.eclipse.org/security/best-practices/-/blob/main/templates/SECURITY.md. Adapt it to your needs. 

Some inspiration from other projects:

  • Eclipse Leshan shows in an easy-to-understand way which versions are supported. They also list issues in dependencies that might affect Leshan. You can see their file here: https://github.com/eclipse-leshan/leshan/blob/master/SECURITY.md
  • Eclipse EE4j uses the Security template with one customization. As the organization contains different projects with different dependencies and release schedules, they ask researchers to check individual SECURITY.md of each project for details in https://github.com/eclipse-ee4j/.github/blob/main/SECURITY.md
  • Mosquitto has a minimal file with basic information security researchers may need https://github.com/eclipse/mosquitto/blob/master/SECURITY.md


If you want to know more, continue to: Reporting and Managing Security Issues in Eclipse Foundation Projects


Previous blog posts on security:

Eclipse Foundation Publishes Results of Equinox p2 Security Audit

How to Report a Security Issue in an Eclipse Foundation Project?

Eclipse Foundation Default Security Tracker Moves!