Ensure public repositories include a SECURITY.md file

Framework Reference: A.8.25 (Secure Development Lifecycle) Integration: GitHub – Repository Configuration

Why this matters

A SECURITY.md file defines your project’s security policy and provides instructions for responsibly reporting vulnerabilities.
This file is essential for maintaining transparent communication with external users and security researchers, especially in public repositories.

Having a clear and accessible security policy ensures that:

  • Vulnerabilities are reported through the correct channels
  • Disclosure follows responsible, standardized procedures
  • The organization demonstrates compliance with security best practices and industry standards

Without it, users might disclose vulnerabilities publicly or fail to report them altogether, increasing risk exposure.


What this check does

This check verifies that a SECURITY.md file exists in one of the recognized locations within the repository:

  • The repository root (/SECURITY.md)
  • The .github/ directory (/.github/SECURITY.md)
  • The docs/ directory (/docs/SECURITY.md)

GitHub automatically detects this file and displays its contents in the repository’s Security tab under Reporting a vulnerability.


How to fix it

From the GitHub Web Console

  1. Navigate to your repository on GitHub.
  2. Go to the Security tab.
  3. Under Reporting a vulnerability, click Add a security policy.
  4. GitHub will guide you to create a SECURITY.md file in the .github/ directory by default.
  5. Add content that includes:
    • How to report a security vulnerability
    • Expected response timelines
    • Disclosure and remediation policies
    • Contact information or submission process (e.g., via email or security form)
  6. Commit the file to the default branch.

Alternatively, you can manually create the file in the repository root or .github/ directory with relevant content and push it via Git.


Exceptions

  • The SECURITY.md file is optional for private repositories, but strongly recommended.
  • The file content and contact process should comply with your organization’s vulnerability disclosure policy.
  • GitHub automatically prioritizes the SECURITY.md file in the .github/ directory if multiple copies exist.

Further Resources

 

Was this article helpful?