Security Insights Specification

Security Insights is a standardized YAML format that lets open source projects self-report their security practices, policies, and processes in a machine-processable way. It fills the gap between simplified solutions like SECURITY.md and comprehensive automated solutions like SBOMs — recording elements that must be self-asserted by the project itself.

It’s intended to be useful for:

• Project maintainers communicating their security posture clearly
• Security researchers finding how to report vulnerabilities
• End users and organizations evaluating the security of dependencies
• Automated tools parsing and analyzing security information consistently

Quick Start

For Project Maintainers

The Get Started guide 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 file as describing the project at the commit or release artifact it ships with. For multi-repository projects, a child file’s header.project-si-source points at the raw URL of the parent file containing the project: section; consumers should fetch and merge that data.

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

The repository’s main branch may diverge from the latest tagged release as work lands toward the next version; treat the difference as a non-authoritative preview. The current authoritative schema is published with the latest release.

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 assessment requirements
• 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 per the governance documentation. Discussion happens in GitHub Issues and the OpenSSF Slack #security_insights channel; spec changes follow the Security Insights Enhancement Proposal process.