Frequently Asked Questions (FAQ)

What is Security Insights?

Security Insights is a standardized YAML format that enables open source projects to self-report their security practices, policies, and processes. It provides a mechanism for projects to report information about their security in a machine-processable way, formatted as a YAML file to make it easy to read and edit by humans.

This information helps:

The data tracked within this specification is intended to fill the gaps between simplified solutions such as SECURITY.md and comprehensive automated solutions such as SBOMs. In that gap lay elements that must be self-reported by projects to allow end-users to make informed security decisions.

Why does this specification exist?

Security is important, and many potential users (final users, engineers, developers, or companies) might want to evaluate the security of a particular open-source project. There are many ways to evaluate the security of a project, including evaluating the code itself (statically or dynamically), the processes used, and/or the people involved (e.g., whether or not they know how to develop secure software).

Some information can be determined automatically by tools, but determining information via tools is often imperfect. For example, many would want to know if a project uses an automated test suite, yet because there are so many different kinds of test suites & ways to invoke them, automated tools often fail to correctly identify whether or not automated tests are performed. It can be provided manually, but that must be done for each approach.

This specification provides a mechanism for projects to report information about their security in a machine-processable way. It is formatted as a YAML file to make it easy to read and edit directly by people. It is expected that a first draft of the file would be created by automated tools, “wizards” that guide users through the answers, and linter tools that help users to check the YAML file schema. The file is then put under version control, provided to potential users, and updated as needed. The file’s contents may then be extracted for a variety of different reasons (e.g., extracted into security evaluations, etc.).

What problems does Security Insights solve?

SECURITY-INSIGHTS.yml helps solve the following user stories:

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?

Projects adopting the specification in a single repository should be able to get started and produce a useful security-insights.yml in about 30 minutes.

Getting Started:

  1. Review the Schema Documentation to understand available fields
  2. Start with the minimum example
  3. Place your security-insights.yml file in the root of your repository or in your source forge directory (e.g. .github/ or .gitlab/) to support automated detection
  4. Validate your file using cue vet against the CUE schema

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

Place your security-insights.yml file in the root of your repository or in your source forge directory (e.g. .github/ or .gitlab/) to support automated detection. Consumers of the security-insights.yml file(s) should look for it in these locations.

How do I validate my security-insights.yml file?

Validate your file using cue vet against the CUE schema. You can also use linter tools that help users to check the YAML file schema.

What’s the minimum required information?

The minimum viable product (MVP) should provide the following information:

See the minimum example for a complete reference.

Trust and Reliability

How much can tools trust this file?

That is an issue ultimately decided by the tools that read this data. The format records assertions made by a project itself. These assertions may be obsolete or even maliciously false. Still, it provides additional information that otherwise would not be automatically accessible. Humans and tools that evaluate projects may want to report results both including and not including self-assertions, or assertions unverified by a trusted third party.

What if the information is outdated or incorrect?

Consumers of the security-insights.yml file(s) provided by projects should assume the contents is only relative to the commit or release artifact it is associated with. As your project evolves, keep your security-insights.yml file up to date. Consider scheduling periodic reminders (every 1, 3, or 6 months) to ensure the information remains accurate.

Versioning and Releases

How is the specification versioned?

The Security Insights Specification uses a semantic versioning (SemVer) scheme to indicate changes. The version number format is as follows:

Major.Minor.Patch

How often are new versions released?

Whenever a new version of the specification is released, a new version of the ossf/si-tooling project should also be released.

Where can I find the latest release?

The Git repository typically remains unchanged from the latest release, but may diverge as incremental development takes place in preparation for an upcoming release. Any differences between the latest release and the main branch should be considered as non-authoritative previews of the next release.

You may download the official schema in the latest release. All releases can be monitored via GitHub Release. Major and minor releases may be communicated through OpenSSF communication channels.

A changelog is maintained, detailing all changes made in each release (major, minor, or patch). The changelog includes a proper tag, a summary of changes for each version, and references to pull requests, issues, or discussions related to the changes.

Usage Questions

How do I handle multi-repository projects?

More complex projects will want to take advantage of the header.project-si-source value to allow for multiple repositories to reference a shared location for project data.

See the multi-repository examples for details:

How often should I update my security-insights.yml file?

As your project evolves, keep your security-insights.yml file up to date. Consider scheduling periodic reminders (every 1, 3, or 6 months) to ensure the information remains accurate.

What tools support Security Insights?

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

Contributing

How can I contribute to the specification?

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

Discussion and feedback should take place in GitHub Issues.

Get Involved:

How are changes to the specification proposed?

We ask that you follow the Security Insights Enhancement Proposal process to explore potential changes to the specification.

For major releases, the procedure includes:

Feedback and suggestions for improvements to the policy are encouraged and can be submitted through the project’s communication channels.