OpenSSF introduces the Specification Security Insights 1.0

By Luigi Gubello (Pitch), Eddie Knight (Sonatype), Michael Scovetta (Microsoft)

The Open Source Security Foundation (OpenSSF) is a dedicated community committed to enhancing the security of open source software. We are thrilled to announce the release of version 1.0 for the Security Insights Specification. This marks the culmination of more than two years worth of community discussion and development to address common software security difficulties.

In addition to adoption by projects such as GUAC, the Cloud Native Computing Foundation will be incentivizing Security Insights adoption as part of their upcoming security hygiene event: the Cloud Native Security Slam.

The Challenge of Fragmented Information

Critical information about security, policies, documentation, and other essential details often reside in various sources, making it challenging for both humans and machines to find, access, and process. 

While there have been attempts to create some standard documents like SECURITY.md and CONTRIBUTING.md to address these issues, the current situation is still the fragmentation of information. This fragmentation hampers automation and creates complexity for project maintainers and contributors.

Enter Security Insights v1.0

Security Insights provides a mechanism for maintainers to provide information about their projects’ security processes in a machine-processable way. Formatted as a YAML file, it ensures easy readability and editing by humans as well as machines.

Values included within the specification may be required or optional. Optional values are recommendations from the Open Source Security Foundation’s Identifying Security Threats Working Group, acknowledging the diversity of use cases.

Maintenance for the specification is led by the OpenSSF Identifying Security Threats Working Group, with improvements handled exclusively within the project’s GitHub repository. Additional information about contributions can be found in the project’s Contribution Policy.

Key Features of Security Insights

Machine-Processable Information: Security Insights allows projects to report critical security information in a way that can be easily processed by automated tools. This simplifies the task of monitoring and enhancing project security.

Human-Friendly Information: Security Insights is a YAML file that can be easily read and written by humans, by making this file easy to use for the entire community.

No Need to Rewrite or Relocate Policies: One of the standout features of Security Insights is that it doesn’t require project maintainers to rewrite or relocate their existing policies and documentation. It harmoniously integrates with the current setup, making it a seamless transition.

Minimal Sample

This is a minimal sample of SECURITY-INSIGHTS.yml.

header:
  schema-version: '1.0.0'
  expiration-date: '2023-10-01T10:10:09.000Z'
  project-url: https://github.com/ossf/example
project-lifecycle:
  stage: active
  bug-fixes-only: false
  core-maintainers:
    - github:example
contribution-policy:
  accepts-pull-requests: true
  accepts-automated-pull-requests: true
distribution-points:
  - https://example.com/package
  - pkg:npm/example
security-contacts:
  - type: email
    value: maintainer@example.com
vulnerability-reporting:
  accepts-vulnerability-reports: false

By providing a standardized and easy-to-read format for security information, Security Insights enables open-source projects to better communicate their security posture, helping the project’s consumers, the project’s contributors, and the security researchers community. This transparency can help ensure that potential vulnerabilities are addressed promptly.

Security Researchers Friendly: SECURITY-INSIGHTS.yml has sections dedicated to security policy and bug bounty programs. The maintainers can add security contacts, and information about bug bounty, in-scope, and out-of-scope areas, giving the security researchers community a quick overview of their communication standards. 

User-oriented: Security Insights YAML can help final users and project consumers to find easily and quickly important documentation, understand and know security best practices in place, and evaluate the security risks. The specification aggregates a ton of helpful information, usually spread between different sources (repos, wiki, documentation, policies, etc.). 

Getting Started with Security Insights

OpenSSF encourages all open-source projects to adopt the Security Insights specification. To get started, visit the Security Insights GitHub repository for detailed documentation, examples, and implementation guidelines.

By adopting Security Insights, you contribute to a more secure, collaborative, and automated open-source ecosystem. Stay tuned for more updates, and let’s make open source even better!

About the Authors

Luigi Gubello 

Luigi works at Pitch as a security engineer, and at OpenSSF he co-leads the working group “Identifying Security Threats”, which helps to identify threats to the open source ecosystem and to recommend mitigations and good practices.

Eddie Knight 

Eddie leads the Open Source Program Office at Sonatype, and serves as a maintainer for complimentary security and compliance projects within the OpenSSF, CNCF, and FINOS ecosystems.

Michael Scovetta 

Michael co-leads the Identifying Security Threats working group and the Alpha-Omega project. At Microsoft, he leads a security team that helps engineering teams understand and mitigate supply chain security risk.