Frequently Asked Questions (FAQ)

What is Security Insights?

Security Insights is a standardized YAML format that lets open source projects self-report their security practices, policies, and processes. 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:

What problems does Security Insights solve?

AS A/AN I WANT TO SO THAT
user know which tools are used to lint or scan the code, and which are the security processes in place I can evaluate the security best practices followed by the project
user know what are the trusted sources for this project I can read, download or install only trusted code
user know project status, release cycle time, security maintenance, and project end of life I can schedule ordinary and extraordinary maintenance
user contact the project maintainers I can get answers or report issues
user read a security policy I can easily know security practices in place
maintainer know which free tools (better open-source) I can use to lint or scan the code and the dependencies I can reduce risks related to supply-chain attacks or human errors
maintainer receive reports related only to certain types of vulnerabilities I can work on more urgent features and fixes instead of reading out-of-scope reports
security researcher report a potential vulnerability the project’s maintainers may be aware of it
developer of a security tool have a standard machine-readable file containing security information about the project I can scan it to reduce false-positive results

Getting Started

How do I get started as a project maintainer?

See the Get Started guide. It walks through both the single-repository and multi-repository layouts, with copyable examples and the validation command.

Where should I place the security-insights.yml file?

At the repository root (security-insights.yml) or in the source-forge directory (.github/security-insights.yml, .gitlab/security-insights.yml, etc.). Tools that consume the file look in these locations.

What’s the minimum required information?

At minimum, the file should let a reader contact a maintainer, find the vulnerability disclosure policy, and identify the repository’s basic posture. The minimum example is the canonical starting point — every field it shows is a reasonable default to fill in or drop.

How do I handle multi-repository projects?

Publish a parent file containing the project: section in one repository, and a child file in each of the other repositories that sets header.project-si-source to the raw URL of the parent. Children inherit project-level data from the parent and only need to describe their own repository.

The multi-repository path in the Get Started guide covers the mechanics — including the raw-URL requirement that catches most first-time setups — and points at the parent and child example files.

Trust and Maintenance

How much can tools trust this file?

The format records assertions made by the project itself. These assertions may be obsolete or even maliciously false. Tools that consume the file should treat it as additional context that wouldn’t otherwise be available, and may want to report results both with and without unverified self-assertions.

How do I keep my file accurate over time?

Treat each file as describing your project at the commit or release artifact it ships with, and update it as your project evolves. A quick review every 1–6 months is enough for most projects; bump header.last-updated and header.last-reviewed whenever you make changes.

Versioning

How is the specification versioned?

The specification follows Semantic Versioning. See the Versioning Policy for the release cadence, the criteria distinguishing major, minor, and patch releases, and the procedure for proposing changes.

Tooling and Contributing

What tools support Security Insights?

See the Tooling Ecosystem on the home page.

How can I contribute to the specification?

The spec is maintained by the Security Insights maintainers per the governance documentation. Discussion happens in GitHub Issues, on the OpenSSF Slack #security_insights channel, and on the mailing list.

To propose a change to the specification, follow the Security Insights Enhancement Proposal process.