Security Insights (v2.2.0-dev)

Table of Contents

#SecurityInsights

SecurityInsights defines a schema that projects can use to report information about their security in a machine-processable way. 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.

header Header Required

header captures high level metadata about the schema.

project Project

project describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details. This field is not required if header.project-si-source is supplied.

repository Repository

repository describes repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture. This field is not required if header.project-si-source is supplied. This field is required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories via their respective header.project-si-source.

#Assessment

Assessment represents the results of a security assessment, including comments, evidence, and date.

comment string Required

Notes or commentary about the findings or purpose of the assessment.

date Date

The date the assessment was published.

evidence URL

The URL where the assessment report or artifact is located.

name string

The name or identifier of the assessment artifact.

#Attestation

Attestation describes an in-toto attestation, including its name, location, predicate URI, and any additional comments.

location URL Required

A web location where the attestation can be found.

name string Required

The name or identifier of the attestation.

predicate-uri string Required

A URI to a resource describing the attestation’s predicate or specification.

comment string

Additional context or instructions for using the attestation.

#Contact

Contact represents a person or entity responsible for the project, including their name, affiliation, and contact details.

name string Required

The contact person’s name.

primary boolean Required

Indicates whether this admin is the first point of contact for inquiries. Only one entry should be marked as primary.

affiliation string

The entity with which the contact is affiliated, such as a school or employer.

email Email

A preferred email address to reach the contact.

social string

A social media handle or profile for the contact.

The Header object captures high-level metadata about the schema.

last-reviewed Date Required

The date when the document or data was last reviewed.

last-updated Date Required

The date when the document or data was last updated.

schema-version SchemaVersion Required

The version of the Security Insights schema being used.

url URL Required

The original URL for the current Security Insights file. This should point to the canonical location where the file is hosted (e.g., a raw file URL in a version control system). This helps preserve context when the file is extracted from its source. This may also be referenced to help readers find the latest version of the security insights file, in the event that they are accessing it from an outdated source, such as a past release artifact. This is not to be confused with the URL for the project. Project URLs should be specified in project.repositories instead.

comment string

Additional information about the schema.

project-si-source URL

A URL to the security insights file that contains project information for this file to inherit. The URL provided here should respond to an unauthenticated GET request and return a valid security insights file using a content-type of “text/plain” or “application/yaml”. This is useful for projects that are part of a larger organization or ecosystem, where much of the security insights data is shared across multiple projects.

#License

expression string Required

The SPDX license expression for the license.

url URL Required

A web address where the license can be found.

comment string Required

Instructions or information about the link.

uri string Required

A link to a resource, not restricted to http/s.

#Project

Project describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details.

administrators array[Contact] Required

A list of 1 or more individuals who have administrative access to the project’s resources.

name string Required

The name of the project.

repositories array[ProjectRepository] Required

A list of 1 or more repositories that are part of this project, including the repository this file is published in.

vulnerability-reporting VulnerabilityReporting Required

An object describing how security vulnerabilities can be reported and how they are handled by the project.

documentation ProjectDocumentation

the project’s documentation resources

funding URL

A URL to information about sponsorships, donations, or other funding topics.

homepage URL

A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.

roadmap URL

A URL pointing to a roadmap or schedule for planned features and releases.

steward Link

This field is to communicate the relationship between the project and “a legal person, other than a manufacturer, that has the purpose or objective of systematically providing support on a sustained basis for the development of specific products with digital elements, qualifying as free and open-source software and intended for commercial activities, and that ensures the viability of those products” This definition is drawn from the European Union Cyber Resilience Act, Article 3.

#ProjectDocumentation

ProjectDocumentation contains links to various documents related to the project, including detailed guides, code of conduct, quickstart guides, release processes, support policies, and signature verification.

code-of-conduct URL

URL to the document outlining contributor and user conduct guidelines.

design URL

URL to design documentation for this project.

detailed-guide URL

URL to more extensive or advanced documentation.

quickstart-guide URL

URL to a concise guide to basic functionality for new users.

release-process URL

URL describing how releases are planned, prepared, and published.

signature-verification URL

URL to documentation explaining how to verify digital signatures on assets.

support-policy URL

URL to documentation describing how releases are supported. See Recommendations for publishing End-of-life dates and support timelines for best practices.

#ProjectRepository

The ProjectRepository object describes a repository that is part of a project, including its name, comment, and URL.

comment string Required

Explanation of the repository purpose or contents and its relation to the rest of the project.

name string Required

The name or short label of the repository.

url URL Required

The URL where the repository is hosted.

#ReleaseDetails

ReleaseDetails describes the release process for the repository, including automated pipelines, distribution points, changelogs, licenses, and attestations.

automated-pipeline boolean Required

Indicates if the repository uses an automated release pipeline.

distribution-points array[Link] Required

A list of 1 or more links describing where the repository’s releases are distributed. This may be the VCS releases page, a package manager, or other distribution points.

attestations array[Attestation]

List of attestations for the repository’s releases.

changelog URL

A URL to the repository’s release changelog. The URL value should include placeholders such as {version} if relevant.

license License

Describes the license details specifically for releases. This should be used when the release license differs from the repository license.

#Repository

The Repository object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture.

accepts-automated-change-request boolean Required

Indicates whether the repository accepts automated or machine-generated change requests.

accepts-change-request boolean Required

Indicates whether the repository currently accepts any change requests.

core-team array[Contact] Required

A list of 1 or more core team members for this repository, such as maintainers or approvers.

license License Required

The license information for this repository.

security SecurityPosture Required

An object describing security-related artifacts, champions, and tooling for the repository.

status string Required

Indicates the repository’s current Repo Status.

url URL Required

The main URL for this repository.

bug-fixes-only boolean

Specifies whether the repository only accepts bug-fixes and not feature work.

documentation RepositoryDocumentation

Documentation links for the repository, including links to contributing guides, dependency management policies, governance documents, and review policies.

no-third-party-packages boolean

Indicates whether the repository universally avoids package dependencies from outside of the project.

release ReleaseDetails

Release describes the release process for the repository.

#RepositoryDocumentation

RepositoryDocumentation contains links to various documents related to the repository, including contributing guides, dependency management policies, governance documents, and review policies.

contributing-guide URL

URL to a document outlining the process for contributing to the repository.

dependency-management-policy URL

URL to a document outlining the process for managing dependencies in the repository.

governance URL

URL to any governance documents regarding roles, responsibilities, processes, and decision-making.

review-policy URL

URL to a document outlining the process for reviewing changes to the repository.

security-policy URL

URL with information about the repository’s security, including the policy for reporting security vulnerabilities.

#SecurityPosture

SecurityPosture describes the security posture of the repository, including assessments, champions, and tools.

assessments object Required

An object describing security assessments for the repository.

champions array[Contact]

A list of core team members who advocate for continuous improvement of security practices. These individuals may take responsibility for security reviews, training, interfacing with stakeholders on security topics, or other similar activities.

tools array[SecurityTool]

A list of objects describing security-related tools used in the repository.

#SecurityTool

SecurityTool describes a security-related tool used in the repository, including its name, type, version, rulesets, integration details, and results.

integration SecurityToolIntegration Required

An object describing how the tool is integrated with the project.

name string Required

The name of the tool.

results SecurityToolResults Required

SecurityToolResults describes the results of security scans, including those run on-demand, in continuous integration, and during the release process.

rulesets string Required

The set of rules or configurations applied by the tool. If customization is not enabled, the only value here should be “default”.

type string Required

The general category or type of the tool.

comment string

Additional notes about the tool’s usage or configuration.

version string

The version of the tool that is used.

#SecurityToolIntegration

SecurityToolIntegration describes how a security tool is integrated into the repository, including whether it is used in scheduled processes, continuous integration, or during the release process.

adhoc boolean Required

Indicates whether the tool is used in a scheduled process or supports an on-demand.

ci boolean Required

Indicates whether the tool is used in the continuous integration process.

release boolean Required

Indicates whether the tool is run before or during the release process.

#SecurityToolResults

SecurityToolResults describes the results of security scans, including those run on-demand, in continuous integration, and during the release process.

adhoc Attestation

Results of scheduled or on-demand security scans.

ci Attestation

Results of security scans run in the continuous integration process.

release Attestation

Results of security scans run in the build and release process.

#VulnerabilityReporting

VulnerabilityReporting describes how security vulnerabilities can be reported and how they are handled by the project.

bug-bounty-available boolean Required

Specifies whether a bug bounty program is offered.

reports-accepted boolean Required

Indicates whether this project currently accepts vulnerability reports.

bug-bounty-program URL

Path to a page providing details about any bug bounty program.

comment string

Additional comments or instructions about vulnerability reporting.

contact Contact

Point of contact for reporting vulnerabilities. This may be a single person or a mailgroup.

in-scope array[string]

A list of issues or components that are covered by the vulnerability reporting process.

out-of-scope array[string]

A list of issues or components not covered by the vulnerability reporting process.

pgp-key string

The PGP public key for secure communication.

policy URL

Path to a page containing rules for security-related disclosures.

Aliases

The following aliases are used throughout the schema for consistency.

Date

Date is a date in the format YYYY-MM-DD

Email

Email is a valid email address

SchemaVersion

SchemaVersion is a version string in the format X.Y.Z

URL

URL is a TLS URL