Security Insights Specification

Security Insights is a single YAML file where a project reports its security practices in a standard, machine-readable format.

It fills the gap between a plain-text SECURITY.md and an SBOM (a machine-readable list of everything inside your software). Some security facts can only be reported by maintainers themselves. This file is where they go.

Who is it for?

• Project maintainers — communicate your security posture clearly
• Security researchers — learn how to report vulnerabilities
• End users and organizations — evaluate the security of dependencies
• Automated tools — parse security information consistently

Quick Start

For Project Maintainers

Follow the Get Started guide. It covers single-repo and multi-repo layouts, copyable examples, and the validation command. A single-repository project typically takes about 30 minutes from first read to a validated file.

For Consumers

Look for security-insights.yml at the repository root or in the source-forge directory (.github/, .gitlab/, etc.).

Treat the contents as a snapshot. It describes the commit or release it ships with, not necessarily the project’s current state.

Documentation

• Get Started - Step-by-step guide for producing a valid file
• Schema Documentation - Complete reference for all fields in the specification
• Examples - Starting points for each layout:
  • example-minimum.yml - Single repository, minimal required fields
  • example-full.yml - Single repository, all possible fields
  • example-multi-repository-project.yml - Multi-repo: parent file holding the project: section
  • example-multi-repository-project-reuse.yml - Multi-repo: child file referencing the parent

Releases

Download the official schema from the latest release.

The main branch may be slightly ahead of the latest release. Treat any differences as a preview of the next release, not as final.

Tooling Ecosystem

As the adoption of Security Insights grows, so does the opportunity to automatically ingest it:

• si-tooling - Community-maintained tools for reading, validating and manipulating Security Insights data
• CLOMonitor - The Linux Foundation’s tool that parses Security Insights files to determine whether projects have reported on select security factors
• LFX Insights - The Linux Foundation’s tool that reads a project’s Security Insights file to evaluate security hygiene against the OSPS Baseline (a set of minimum security requirements for open source projects)
• OSPS Baseline Scanner - GitHub Action that runs OSPS Baseline assessments on individual repositories using the same scanner as LFX Insights

Contributing

The specification is maintained by the Security Insights maintainers according to the governance documentation.

Discussion and feedback should take place in GitHub Issues. We ask that you follow the Security Insights Enhancement Proposal process to explore potential changes to the specification.

Get Involved

• Slack: Join the OpenSSF Security Insights channel
• GitHub: Contribute at ossf/security-insights