├── .gitignore ├── .github ├── CODEOWNERS ├── workflows │ └── ci.yml ├── SECURITY.md ├── CONTRIBUTING.md ├── security-insights.yml └── ISSUE_TEMPLATE │ └── siep.yml ├── docs ├── threat-model │ ├── SECURITY-INSIGHTS-STRIDE-threat-model.pdf │ ├── SECURITY-INSIGHTS-STRIDE-threat-model.png │ ├── README.md │ └── SECURITY-INSIGHTS-STRIDE-threat-model.json ├── MAINTAINERS.md ├── roadmap │ └── security-insights-v1.1.md ├── versioning-policy.md ├── user-story.md └── GOVERNANCE.md ├── LICENSE ├── examples ├── example-multi-repository-project-reuse.yml ├── example-minimum.yml ├── example-multi-repository-project.yml └── example-full.yml ├── Makefile ├── spec ├── header.md ├── aliases.md ├── project.md ├── repository.md └── schema.cue └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | cue_types_gen.go 2 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @eddie-knight @jmeridth 2 | -------------------------------------------------------------------------------- /docs/threat-model/SECURITY-INSIGHTS-STRIDE-threat-model.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ossf/security-insights/HEAD/docs/threat-model/SECURITY-INSIGHTS-STRIDE-threat-model.pdf -------------------------------------------------------------------------------- /docs/threat-model/SECURITY-INSIGHTS-STRIDE-threat-model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ossf/security-insights/HEAD/docs/threat-model/SECURITY-INSIGHTS-STRIDE-threat-model.png -------------------------------------------------------------------------------- /docs/MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | This following are current maintainers of the specification. 4 | 5 | - Eddie Knight (@eddie-knight), Sonatype 6 | - Jason Meridth (@jmeridth), GitHub 7 | 8 | ## Emeritus Maintainers 9 | 10 | - Luigi Gubello (@luigigubello), Pitch 11 | 12 | Additions and status changes may be made via the processes outlined in the [governance](/GOVERNANCE.md) document. -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: CI Checks 3 | 4 | on: 5 | pull_request: 6 | 7 | permissions: 8 | contents: read 9 | 10 | jobs: 11 | ci: 12 | name: CI checks 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@v4.2.2 16 | with: 17 | persist-credentials: false 18 | 19 | - name: Setup Cue 20 | uses: cue-lang/setup-cue@v1.0.1 21 | 22 | - name: Validate schema.cue 23 | run: make lintcue 24 | 25 | - name: Validate example files against schema 26 | run: make lintyml 27 | -------------------------------------------------------------------------------- /.github/SECURITY.md: -------------------------------------------------------------------------------- 1 | # Reporting Security Issues 2 | 3 | To report a security issue or vulnerability, submit a [private vulnerability report via GitHub](https://github.com/ossf/security-insights-spec/security/advisories/new) to the repository maintainers with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue. 4 | 5 | Our vulnerability management team will respond within 7 working days of your report. If the issue is confirmed as a vulnerability, we will open a Security Advisory and acknowledge your contributions as part of it. This project follows a 90 day disclosure timeline. 6 | 7 | Other contacts: security@openssf.org -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Specifications in the repository are subject to the **Community Specification License 1.0** available at https://github.com/CommunitySpecification/1.0. 2 | 3 | If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the MIT license unless otherwise designated. In the case of any conflict or confusion within this specification repository between the Community Specification License and the MIT or other designated license, the terms of the Community Specification License shall apply. 4 | 5 | In the case of any conflict or confusion within this specification repository between the Community Specification License and the designated source code license, the terms of the Community Specification License shall apply. 6 | -------------------------------------------------------------------------------- /examples/example-multi-repository-project-reuse.yml: -------------------------------------------------------------------------------- 1 | # Repository template for a multi-repository project 2 | # This file would be stored in the https://vcs.example.com/foobar/bar repository 3 | header: 4 | schema-version: 2.0.0 5 | last-updated: '2025-03-01' 6 | last-reviewed: '2025-04-01' 7 | url: https://example.com/kubernetes/kubernetes 8 | project-si-source: https://raw.githubusercontent.com/example/repo/refs/heads/main/security-insights.yml 9 | 10 | repository: 11 | url: https://vcs.example.com/foobar/bar 12 | status: active 13 | accepts-change-request: true 14 | accepts-automated-change-request: true 15 | core-team: 16 | - name: Alice White 17 | affiliation: Foo Bar 18 | email: alicewhite@email.com 19 | social: https://social.example.com/alicewhite 20 | primary: true 21 | license: 22 | url: https://example.com/LICENSE 23 | expression: MIT 24 | security: 25 | assessments: 26 | self: 27 | comment: | 28 | Self assessment has not yet been completed. 29 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | lintcue: 2 | @echo " > Linting CUE schema ..." 3 | @cd spec 4 | @cue vet ./spec --all-errors --verbose 5 | 6 | lintyml: 7 | @echo " > Linting YAML files ..." 8 | @echo " > Linting .github/security-insights.yml ..." 9 | @cue vet -d '#SecurityInsights' ./spec .github/security-insights.yml 10 | @echo " > Linting template-full.yml ..." 11 | cue vet -d '#SecurityInsights' ./spec examples/example-full.yml 12 | @echo " > Linting template-minimum.yml ..." 13 | cue vet -d '#SecurityInsights' ./spec examples/example-minimum.yml 14 | @echo " > Linting template-multi-repository-project-reuse.yml ..." 15 | cue vet -d '#SecurityInsights' ./spec examples/example-multi-repository-project-reuse.yml 16 | @echo " > Linting template-multi-repository-project.yml ..." 17 | cue vet -d '#SecurityInsights' ./spec examples/example-multi-repository-project.yml 18 | 19 | cuegen: 20 | @echo " > Generating types from cue schema ..." 21 | @cue exp gengotypes spec/schema.cue 22 | @echo " > vet the generated go types ..." 23 | @go vet cue_types_gen.go 24 | 25 | PHONY: lintcue lintyml cuegen 26 | -------------------------------------------------------------------------------- /docs/roadmap/security-insights-v1.1.md: -------------------------------------------------------------------------------- 1 | # SECURITY INSIGHTS v1.1 Roadmap 2 | 3 | This document would like to define the minimum required improvements and changes to release version **1.1** of the Security Insights specification. 4 | 5 | 1. Create an independent website, with its custom top-level domain, to document the specification Security Insights. 6 | 1. We can use the domain `securityinsights.dev.` 7 | 2. Improve the Security Insights specification: 8 | 1. Support more tool families in `security-testing`(risk score checkers (e.g. Scorecard), linters, other generic scanners) ([Slack](https://openssf.slack.com/archives/C04BB493NET/p1696468506093119)); 9 | 2. Improve support for maintainers and owners by allowing URLs to other trusted sources (issue #67); 10 | 3. Improve `dependencies` section, in particular the SBOM sub-section according to real-world scenarios; 11 | 4. Add more examples, and use-cases (issue #68). 12 | 3. Create and implement a GitHub Action into `ossf/security-insights-spec` to validate changes and pull requests. 13 | 4. Work on si-tooling to offer more validator and wizard tools to the community to accelerate the SECURITY INSIGHTS adoption: 14 | 1. A Golang script; 15 | 2. A static webpage. 16 | 17 | **Estimated Time of Arrival:** 2024.Q1 18 | 19 | 20 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Thank you for your interest in contributing to the Security Insights Specification! 2 | 3 | ## How to Contribute 4 | 5 | 1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository to your own GitHub account. 6 | 2. Make changes or improvements to the specification document in your forked repository. 7 | 3. Create a [Pull Request](https://docs.github.com/en/get-started/quickstart/opening-a-pull-request) with a clear title and description of your changes. 8 | 9 | ## Issue Reporting 10 | 11 | If you find issues or inconsistencies in the specification, please [open an issue](https://docs.github.com/en/get-started/quickstart/opening-an-issue) with a detailed description. 12 | 13 | ## Review Process 14 | 15 | Our team will review your contributions and provide feedback. Once approved, we'll merge your changes. 16 | 17 | Reach out to us on [Slack](https://openssf.slack.com/messages/security_insights) or join a [community meeting](https://calendar.google.com/calendar?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for the Metrics & Metadata working group. 18 | 19 | ## Code of Conduct 20 | 21 | Please adhere to our [Code of Conduct](https://github.com/ossf/.github/CODE_OF_CONDUCT.md) when participating in this project. 22 | 23 | ## Licensing 24 | 25 | By contributing, you agree that your contributions will be licensed under the [project's license](LICENSE.md). 26 | 27 | ## Thanks! 28 | 29 | Thank you for helping improve the Security Insights Specification! 30 | -------------------------------------------------------------------------------- /examples/example-minimum.yml: -------------------------------------------------------------------------------- 1 | header: 2 | schema-version: 2.0.0 3 | last-updated: '2025-03-01' 4 | last-reviewed: '2025-04-01' 5 | url: https://example.com/kubernetes/kubernetes 6 | comment: | 7 | This file contains the minimum information for both project and repository. 8 | It not required to include both a project and repository section if the project 9 | section is intended to be inherited by repositories via header.project-si-source 10 | 11 | project: 12 | name: FooBar 13 | administrators: 14 | - name: Joe Dohn 15 | affiliation: Foo 16 | email: joe.bob@example.com 17 | social: https://social.example.com/joebob 18 | primary: true 19 | repositories: 20 | - name: Foo 21 | url: https://vcs.example.com/foobar/foo 22 | comment: | 23 | Foo is the core repo for FooBar. 24 | vulnerability-reporting: 25 | reports-accepted: true 26 | bug-bounty-available: true 27 | 28 | repository: 29 | url: https://vcs.example.com/foobar/foo 30 | status: active 31 | accepts-change-request: true 32 | accepts-automated-change-request: true 33 | core-team: 34 | - name: Alice White 35 | affiliation: Foo Bar 36 | email: alicewhite@email.com 37 | social: https://social.example.com/alicewhite 38 | primary: true 39 | license: 40 | url: https://example.com/LICENSE 41 | expression: MIT 42 | security: 43 | assessments: 44 | self: 45 | comment: | 46 | Self assessment has not yet been completed. 47 | -------------------------------------------------------------------------------- /spec/header.md: -------------------------------------------------------------------------------- 1 | # `header` _(v2.0.0)_ 2 | 3 | The `header` object captures high-level metadata about the schema. 4 | 5 | --- 6 | 7 | ## `header.last-reviewed` 8 | 9 | - **Type**: [Date] 10 | - **Description**: The date when the document or data was last reviewed. 11 | 12 | --- 13 | 14 | ## `header.last-updated` 15 | 16 | - **Type**: [Date] 17 | - **Description**: The date when this document or data was last updated. 18 | 19 | --- 20 | 21 | ## `header.schema-version` 22 | 23 | - **Type**: [SchemaVersion] 24 | - **Description**: Represents the version of this schema. 25 | 26 | --- 27 | 28 | ## `header.url` 29 | 30 | - **Type**: [URL] 31 | - **Description**: The primary reference URL for this schema’s origin or repository. 32 | 33 | --- 34 | 35 | ## `header.comment` (optional) 36 | 37 | - **Type**: `string` 38 | - **Description**: Additional information about the schema. 39 | 40 | --- 41 | 42 | ## `header.project-si-source` (optional) 43 | 44 | - **Type**: [URL] 45 | - **Description**: 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. 46 | 47 | --- 48 | 49 | [URL]: ./aliases.md#url 50 | [Date]: ./aliases.md#date 51 | [SchemaVersion]: ./aliases.md#schemaversion 52 | -------------------------------------------------------------------------------- /examples/example-multi-repository-project.yml: -------------------------------------------------------------------------------- 1 | # Project and repository template for a multi-repository project 2 | # This file would be stored in the https://vcs.example.com/foobar/foo repository 3 | # and addressable via https://vcs.example.com/foobar/foo/security-insights.yml 4 | header: 5 | schema-version: 2.0.0 6 | last-updated: '2025-03-01' 7 | last-reviewed: '2025-04-01' 8 | url: https://example.com/kubernetes/kubernetes 9 | comment: | 10 | This file contains the minimum information for both project and repository. 11 | It not required to include both a project and repository section if the project 12 | section is intended to be inherited by repositories via header.project-si-source 13 | 14 | project: 15 | name: FooBar 16 | administrators: 17 | - name: Joe Dohn 18 | affiliation: Foo 19 | email: joe.bob@example.com 20 | social: https://social.example.com/joebob 21 | primary: true 22 | repositories: 23 | - name: Foo 24 | url: https://vcs.example.com/foobar/foo 25 | comment: | 26 | Foo is the core repo for FooBar. 27 | - name: Bar 28 | url: https://vcs.example.com/foobar/bar 29 | comment: | 30 | Bar is also part of the FooBar project. 31 | vulnerability-reporting: 32 | reports-accepted: true 33 | bug-bounty-available: true 34 | 35 | repository: 36 | url: https://vcs.example.com/foobar/foo 37 | status: active 38 | accepts-change-request: true 39 | accepts-automated-change-request: true 40 | core-team: 41 | - name: Alice White 42 | affiliation: Foo Bar 43 | email: alicewhite@email.com 44 | social: https://social.example.com/alicewhite 45 | primary: true 46 | license: 47 | url: https://example.com/LICENSE 48 | expression: MIT 49 | security: 50 | assessments: 51 | self: 52 | comment: | 53 | Self assessment has not yet been completed. 54 | -------------------------------------------------------------------------------- /.github/security-insights.yml: -------------------------------------------------------------------------------- 1 | header: 2 | schema-version: 2.0.0 3 | last-updated: '2024-12-31' 4 | last-reviewed: '2025-01-01' 5 | url: https://github.com/ossf/security-insights-spec 6 | comment: This file contains the security information for the Security Insights project. 7 | 8 | project: 9 | name: Security Insights 10 | administrators: 11 | - name: Christopher Robinson 12 | affiliation: Linux Foundation 13 | primary: true 14 | repositories: 15 | - name: Security Insights 16 | url: https://github.com/ossf/security-insights-spec 17 | comment: | 18 | Security Insights is the core repo for the Security Insights project. 19 | steward: 20 | uri: https://openssf.org 21 | comment: | 22 | The Security Insights Specification is a copyright of the Open Source Security Foundation (OpenSSF) and it is maintained by volunteers under the oversight of the OpenSSF. 23 | vulnerability-reporting: 24 | reports-accepted: true 25 | bug-bounty-available: false 26 | 27 | repository: 28 | status: active 29 | url: https://github.com/ossf/security-insights-spec 30 | accepts-change-request: true 31 | accepts-automated-change-request: false 32 | no-third-party-packages: true 33 | core-team: 34 | - name: Eddie Knight 35 | affiliation: Sonatype 36 | primary: true 37 | license: 38 | url: https://github.com/ossf/security-insights-spec/blob/main/LICENSE 39 | expression: MIT AND Community Specification License 1.0 40 | security: 41 | assessments: 42 | self: 43 | evidence: https://github.com/ossf/security-insights-spec/blob/main/docs/threat-model 44 | comment: | 45 | A light-weight threat model was completed when the project was first started, 46 | and it remains accurate to-date. 47 | documentation: 48 | contributing-guide: https://github.com/ossf/security-insights-spec/blob/main/.github/CONTRIBUTING.md 49 | governance: https://github.com/ossf/security-insights-spec/blob/main/docs/GOVERNANCE.md 50 | release: 51 | automated-pipeline: false 52 | distribution-points: 53 | - uri: https://github.com/ossf/security-insights-spec/releases 54 | comment: GitHub Release Page 55 | -------------------------------------------------------------------------------- /docs/threat-model/README.md: -------------------------------------------------------------------------------- 1 | # Threat Model 2 | 3 | A [STRIDE](https://docs.microsoft.com/it-it/azure/security/develop/threat-modeling-tool-threats) Threat Model 4 | for SECURITY-INSIGHTS project is available both in [PDF format](./SECURITY-INSIGHTS-STRIDE-threat-model.pdf) and 5 | [JSON format](./SECURITY-INSIGHTS-STRIDE-threat-model.json), generated using the [OWASP Threat Dragon](https://github.com/OWASP/threat-dragon) tool. 6 | 7 | ![Threat Model](./SECURITY-INSIGHTS-STRIDE-threat-model.png) 8 | 9 | ## Supply-chain 10 | 11 | **Description:** Attackers can obtain the control of a third-party sources (e.g. website 12 | domain, server, etc) linked in the `SECURITY-INSIGHTS.yml`. 13 | 14 | **Mitigation:** Maintainers could self-host the evidence to reduce risks. 15 | 16 | ## False information in the SECURITY-INSIGHTS.yml 17 | 18 | **Description:** Maintainers could upload false information in the `SECURITY-INSIGHTS.yml` 19 | just to obtain a high score from the scanners or other services which use SECURITY- 20 | INSIGHTS to evaluate the project. 21 | 22 | **Mitigation:** Scanners could introduce some additional checks (e.g. check if URLs 23 | return 200 OK status) and a weighted score to reduce the risks. In addition, the open-source 24 | community can read the YAML file and report false information (or just information without clear evidence). 25 | 26 | ## Private information sharing 27 | 28 | **Description:** A maintainer shares mistakenly private critical information (e.g. security audit 29 | containing unpatched vulnerabilities). 30 | 31 | **Mitigation:** 32 | 33 | ## Malicious pull-request 34 | 35 | **Description:** A malicious contributor could introduce false or malicious information (e.g. 36 | malicious URLs) to obtain a particular advantage. 37 | 38 | **Mitigation:** The contributors' PRs to `SECURITY-INSIGHTS.yml` should be carefully reviewed and 39 | approved by the maintainers. In addition, the maintainers could decide to not 40 | accept direct contributions to the `SECURITY-INSIGHTS.yml`. 41 | 42 | ## Missing pull-request review or lacks in the review process 43 | 44 | **Description:** Missing PR review or lack in the review process can lead to the tampering of 45 | `SECURITY-INSIGHTS.yml` by adding false information. 46 | 47 | **Mitigation:** The PR should be formally reviewed and approved by another maintainer. 48 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/siep.yml: -------------------------------------------------------------------------------- 1 | name: Security Insights Enhancement Proposal (SIEP) 2 | description: Propose a new feature or improvement to the Security Insights specification. 3 | title: "[SIEP] " 4 | labels: 5 | - enhancement 6 | 7 | body: 8 | - type: markdown 9 | attributes: 10 | value: | 11 | # Security Insights Enhancement Proposal (SIEP) 12 | 13 | - type: input 14 | id: proposal_summary 15 | attributes: 16 | label: Proposal Summary 17 | description: Provide a brief summary of the proposed enhancement. Explain what problem it solves and why it is necessary. 18 | placeholder: Enter the proposal summary here 19 | validations: 20 | required: true 21 | 22 | - type: textarea 23 | id: detailed_design 24 | attributes: 25 | label: Detailed Design 26 | description: Provide a detailed description of the proposal, including a design of how it will fit into the specification. 27 | placeholder: Enter the detailed design here 28 | validations: 29 | required: true 30 | 31 | - type: textarea 32 | id: impact 33 | attributes: 34 | label: Impact 35 | description: Explain the potential impact of this proposal. Consider both positive and negative effects, including the risk of future breaking changes. 36 | placeholder: Enter the impact here 37 | validations: 38 | required: true 39 | 40 | - type: textarea 41 | id: compatibility 42 | attributes: 43 | label: Compatibility 44 | description: Discuss how this proposal maintains or breaks compatibility with existing versions. If there are breaking changes, explain why they are necessary and how they can be mitigated. 45 | placeholder: Enter the compatibility details here 46 | validations: 47 | required: true 48 | 49 | - type: textarea 50 | id: alternatives 51 | attributes: 52 | label: Alternatives 53 | description: List and describe any alternative phrasing or approaches that were considered, and why they were not chosen. 54 | placeholder: Enter the alternatives here 55 | validations: 56 | required: true 57 | 58 | - type: textarea 59 | id: open_questions 60 | attributes: 61 | label: Open Questions 62 | description: List any open questions or unresolved issues related to this proposal. 63 | placeholder: Enter the open questions here 64 | validations: 65 | required: true 66 | 67 | - type: dropdown 68 | id: sponsoring_maintainer 69 | attributes: 70 | label: Sponsoring Maintainer Assigned 71 | description: Select the maintainer sponsoring this proposal. 72 | multiple: false 73 | options: 74 | - label: No Sponsor Yet 75 | value: None 76 | - label: Eddie Knight 77 | value: "@eddie-knight" 78 | validations: 79 | required: true 80 | -------------------------------------------------------------------------------- /docs/versioning-policy.md: -------------------------------------------------------------------------------- 1 | # Security Insights Specification Versioning Policy 2 | 3 | ## 1. Introduction 4 | 5 | The versioning policy for the Security Insights Specification should provide guidelines for releasing new versions of the Security Insights YAML schema. This policy ensures that changes are documented, tracked, and communicated to the community and stakeholders. 6 | 7 | ## 2. Versioning Scheme 8 | 9 | The Security Insights Specification uses a semantic versioning (SemVer) scheme to indicate changes. The version number format is as follows: 10 | 11 | **Major.Minor.Patch** 12 | 13 | **Major**: Incremented for significant changes. Ideally at most one per year. 14 | **Minor**: Incremented for important changes and improvements. Ideally, at most four per year. 15 | **Patch**: Incremented for minor changes, and typo fixes. 16 | 17 | ## 3. Version Release Process 18 | 19 | Whenever a new version of the specification is released, a new version of the ossf/si-tooling project should also be released. 20 | 21 | ### 3.1. Major Releases 22 | 23 | A major release (e.g., from `1.X.X` to `2.X.X`) signifies significant changes that may require a substantial update to the Security Insights specification. Major releases may include: 24 | 25 | - Major and important changes to the SECURITY INSIGHTS schema; 26 | - Significant policy or procedure modifications. 27 | 28 | ### 3.2. Minor Releases 29 | 30 | A minor release (e.g., from `1.1.X` to `1.2.X`) introduces changes and improvements that need to be properly released. Minor releases may include: 31 | 32 | - Improvements, changes, or minor milestones to the SECURITY INSIGHTS schema. 33 | 34 | ### 3.3. Patch Releases 35 | 36 | A patch release (e.g., from `1.1.0` to `1.1.1`) includes minor fixes, typo corrections, or updates that do not introduce substantial changes. Patch releases may include: 37 | 38 | - Typo corrections or language improvements. 39 | 40 | ### 3.4 Procedure for Major Releases: 41 | 42 | - Discuss and propose the changes through open-source project communication channels (GitHub repo [ossf/security-insights-spec](https://github.com/ossf/security-insights-spec), OpenSSF Slack channels [#wg_metrics_and_metadata](https://openssf.slack.com/archives/C01A50B978T) and [#security_insights](https://openssf.slack.com/archives/C04BB493NET)). 43 | - Conduct a review and discussion among community, and OpenSSF working groups. 44 | - Update the project with proposed changes, and update the changelog. 45 | - Release the updates through GitHub Release. 46 | 47 | ## 4. Changelog 48 | 49 | A changelog will be maintained, detailing all changes made in each release (major, minor, or patch). The changelog should include: 50 | 51 | - A proper tag; 52 | - A summary of changes for each version (major, minor, or patch); 53 | - References to pull requests, issues, or discussions related to the changes. 54 | 55 | ## 5. Communication 56 | 57 | All the releases can be monitored via GitHub Release. Major and minor releases may be communicated through OpenSSF communication channels. 58 | 59 | ## 6. Review and Adoption 60 | 61 | Feedback and suggestions for improvements to the policy are encouraged and can be submitted through the project's communication channels. 62 | -------------------------------------------------------------------------------- /spec/aliases.md: -------------------------------------------------------------------------------- 1 | # Aliases _(v2.0.0)_ 2 | 3 | The following aliases are used throughout the schema for consistency. 4 | 5 | ## `assessment` 6 | 7 | ### `assessment.name` 8 | 9 | - **Type**: `string` 10 | - **Description**: The name or identifier of the assessment artifact. 11 | 12 | ### `assessment.evidence` 13 | 14 | - **Type**: [URL] 15 | - **Matches Pattern**: `^https?://[^\\s]+$` 16 | - **Description**: The URL where the assessment report or artifact is located. 17 | 18 | ### `assessment.date` 19 | 20 | - **Type**: [Date] 21 | - **Description**: The date the assessment was published. 22 | 23 | ### `assessment.comment` 24 | 25 | - **Type**: `string` 26 | - **Description**: Notes or commentary about the findings or purpose of the assessment. 27 | 28 | --- 29 | 30 | ## `attestation` 31 | 32 | A list of objects describing various release attestations or artifacts. 33 | 34 | ### `attestation.name` 35 | 36 | - **Type**: `string` 37 | - **Description**: The name or identifier of the attestation. 38 | 39 | ### `attestation.location` 40 | 41 | - **Type**: [URL] 42 | - **Description**: A web location where the attestation can be found. 43 | 44 | ### `attestation.predicate-uri` 45 | 46 | - **Type**: `string` 47 | - **Description**: A URI to a resource describing the attestation’s predicate or specification. 48 | 49 | ### `attestation.comment` 50 | 51 | - **Type**: `string` 52 | - **Description**: Additional context or instructions for using the attestation. 53 | 54 | --- 55 | 56 | ## `contact` 57 | 58 | - `contact.name` 59 | - **Type**: `string` 60 | - **Description**: The contact person's name. 61 | - `contact.primary` 62 | - **Type**: `bool` 63 | - **Description**: Indicates whether this admin is the first point of contact for inquiries. Only one entry should be marked as primary. 64 | - `contact.affiliation` (optional) 65 | - **Type**: `string` 66 | - **Description**: The entity with which the contact is affiliated, such as a school or employer. 67 | - `contact.email` (optional) 68 | - **Type**: [Email] 69 | - **Description**: A preferred email address to reach the contact. 70 | - `contact.social` (optional) 71 | - **Type**: `string` 72 | - **Description**: A social media handle or profile for the contact. 73 | 74 | --- 75 | 76 | ## `license` 77 | 78 | - `license.url` 79 | - **Type**: [URL] 80 | - **Description**: A web address where the license can be found. 81 | - `license.expression` 82 | - **Type**: `string` 83 | - **Description**: The SPDX license expression for the license. 84 | 85 | --- 86 | 87 | ## `link` 88 | 89 | - `link.uri` 90 | - **Type**: `string` 91 | - **Description**: A link to a resource, not restricted to http/s. 92 | - `link.comment` 93 | - **Type**: `string` 94 | - **Description**: Instructions or information about the link. 95 | 96 | --- 97 | 98 | ## Validation Types 99 | 100 | ### `date` 101 | 102 | - **Type**: `string` 103 | - **Description**: A date in ISO 8601 format (`YYYY-MM-DD`). 104 | 105 | ### `email` 106 | 107 | - **Type**: `string` 108 | - **Matches Pattern**: `^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$` 109 | 110 | ### `url` 111 | 112 | - **Type**: `string` 113 | - **Matches Pattern**: `^https?://[^\\s]+$` 114 | 115 | ### `schemaversion` 116 | 117 | - **Type**: `string` 118 | - **Matches Pattern**: `^[1-9]+\\.[0-9]+\\.[0-9]+$` 119 | 120 | --- 121 | 122 | [URL]: #url 123 | [Email]: #email 124 | [Date]: #date 125 | -------------------------------------------------------------------------------- /docs/user-story.md: -------------------------------------------------------------------------------- 1 | # Why must this specification exist? 2 | 3 | ## Introduction 4 | 5 | Security is important, for this reason, many potential users (final users, engineers, 6 | developers, or companies) might want to evaluate the security of a particular 7 | open-source project. There are many ways to evaluate the security of a project, 8 | including evaluating the code itself (statically or dynamically), the processes used, 9 | and/or the people involved (e.g., whether or not they know how to develop secure 10 | software). 11 | 12 | Some information can be determined automatically by tools, but determining 13 | information via tools is often imperfect. For example, many would want to know if a 14 | project uses an automated test suite, yet because there are so many different kinds 15 | of test suites & ways to invoke them, automated tools often fail to correctly 16 | identify whether or not automated tests are performed. It can be provided manually, 17 | but that must be done for each approach. 18 | 19 | This specification provides a mechanism for projects to report information about 20 | their security in a machine-processable way. It is formatted as a YAML file to make 21 | it easy to read and edit directly by people. It is expected that a first draft of the 22 | file would be created by automated tools, "wizards" that guide users through the 23 | answers, and linter tools that help users to check the YAML file schema. The file is 24 | then put under version control, provided to potential users, and updated as needed. 25 | The file's contents may then be extracted for a variety of different reasons (e.g., 26 | extracted into security evaluations, etc.). 27 | 28 | This is an early version created by the OpenSSF Metrics & Metadata working 29 | group. See the [OpenSSF Community Calendar](https://calendar.google.com/calendar?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ). 30 | 31 | ## SECURITY-INSIGHTS.yml 32 | 33 | > *"How much can tools trust this file?"* 34 | 35 | That is an issue in the end decided by the tools that read this data. 36 | 37 | The minimum viable product (MVP) should provide the following information: 38 | 39 | - Procedure to report a vulnerability (security contact, Vulnerability Disclosure Policy (VDP)); 40 | - Owners contacts. 41 | 42 | This format records assertions made by a project itself. These assertions may be 43 | obsolete or even maliciously false. Still, it provides additional information that 44 | otherwise would not be automatically accessible. Humans and tools that evaluate 45 | projects may want to report results both including and not including self-assertions, 46 | or assertions unverified by a trusted third party. 47 | 48 | ## User stories 49 | 50 | **SECURITY-INSIGHTS.yml** would like to solve the following user stories by helping 51 | the maintainers to improve the security of their projects and the final users (e.g. 52 | developers, companies, automated scanners, etc) to better evaluate the security of 53 | third-party software. 54 | 55 | | AS A/AN | I WANT TO | SO THAT | 56 | |---|---|---| 57 | | developer of an automated tool | have a standard machine-readable file containing security information about the project | I can scan it to reduce false-positive results | 58 | | security researcher | report a potential vulnerability | the project's maintainers may be aware of it | 59 | | 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 | 60 | | 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 | 61 | | user | know what are the trusted sources for this project | I can read, download or install only trusted code | 62 | | user | know project status, release cycle time, security maintenance, and project end of life | I can schedule ordinary and extraordinary maintenance | 63 | | 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 | 64 | | user | contact the project maintainers for general questions | I can solve my issues | 65 | | user | read a security policy | I can easily know security practices in place | 66 | 67 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [](https://openssf.slack.com/messages/security_insights/) 2 | 3 | # Security Insights Specification 4 | 5 | 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 by humans. 6 | 7 | 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. 8 | 9 | ## Usage by project maintainers 10 | 11 | We hope your project appreciates the value the specification provides and makes the decision to use it. Here's how you can. 12 | 13 | ### Initial Adoption 14 | 15 | Projects adopting the specification in a single project repository should be able to get started and produce a useful `security-insights.yml` in about 30 minutes by consulting the [`example-minimum.yml`](examples/example-minimum.yml). 16 | 17 | If your project has multiple repositories, you can define a detailed and centralized insights file in one repository and then reuse the `project` definition from that across other files. The consuming insights files must provide a URL in `header.project-si-source` that points to the parent insights file. The URL provided must respond to an unauthenticated GET request and return a valid security insights file using a content-type of "text/plain" or "application/yaml". See [`example-multi-repository-project.yml`](examples/example-multi-repository-project.yml) and [`example-multi-repository-project-reuse.yml`](examples/example-multi-repository-project-reuse.yml) that demonstrate how this use case can be implemented. 18 | 19 | Projects should include a `security-insights.yml` file in the root of their repository, or in the appropriate source forge directory such as `.github/` or `.gitlab/`. 20 | 21 | To ensure you are adhering to an official version of the specification, please refer to the `schema.cue` and `Security-Insights-{version}.pdf` in the [latest release](https://github.com/ossf/security-insights-spec/releases/latest). 22 | 23 | ### Plan your project security investments 24 | 25 | In reviewing the schema, the examples, and creating a `security-insights.yml` for your project, you probably found many parts of the specification that you would like to be able to add over time. It can be helpful to refer to [`example-full.yml`](examples/example-full.yml) and identify sections for targeted improvement. Consider filing issues in your project's issue tracker for each section so the community understands how you prioritize these investments. 26 | 27 | ### Ongoing Maintenance 28 | 29 | As the project and community around it evolve over time, so too does the project's security posture. As the posture of the project changes, these changes should be reflected in updates to `security-insights.yml`. In the example below, we see the insights data was `last-updated` quite some time ago, but the `last-reviewed` highlights the project's ongoing maintenance efforts to review the data for accuracy. 30 | 31 | ```yaml 32 | header: 33 | schema-version: 2.0.0 34 | last-updated: '2025-01-15' 35 | last-reviewed: '2025-04-03' # no changes needed, reviewed as part of last minor version release 36 | ``` 37 | 38 | Consider using [a scheduled issue](https://docs.github.com/en/actions/use-cases-and-examples/project-management/scheduling-issue-creation) in your project's issue tracker to review the data every 1, 3 or 6 months and make required updates to `security-insights.yml`. 39 | 40 | ## Usage by project consumers 41 | 42 | Consumers of the `security-insights.yml` file(s) provided by projects should assume the contents will be updated any time the relevant information changes. 43 | 44 | ## Releases 45 | 46 | This repository often 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 only be considered previews of the next release. 47 | 48 | ## Tooling Ecosystem 49 | 50 | As the adoption of Security Insights grows, so does the opportunity to automatically ingest it. For example, the Linux Foundation's [CLOMonitor](https://clomonitor.io/) parses a project's Security Insights file to determine whether projects have reported on select security factors prioritized by the foundation. The [si-tooling](https://github.com/ossf/si-tooling) repository has community-maintained tools for reading, validating and manipulating the data. 51 | 52 | ## Maintenance 53 | 54 | The specification maintenance occurs in the following places: 55 | 56 | - `specification/`: Contains markdown details for all specification values 57 | - `schema.cue`: Contains the CUE schema that can be used to validate files against the specification 58 | 59 | Examples are also available to provide further context to the specification details above. 60 | 61 | - `examples/example-full.yml`: Contains a template that includes all possible fields 62 | - `examples/example-minimum.yml`: Contains a template that includes only the required fields 63 | - `examples/example-multi-repository-project.yml`: Contains an extension of `examples/example-minimum.yml` for the primary repository of a multi-repository project 64 | - `examples/example-multi-repository-project-reuse.yml`: Contains a template for a secondary repository of a multi-repository project 65 | 66 | Discussion and feedback should take place in [GitHub Issues](https://github.com/ossf/security-insights-spec/issues). We ask that you follow the [Security Insights Enhancement Proposal](./docs/GOVERNANCE.md#security-insights-enhancement-proposals) process to explore potential changes to the specification. 67 | -------------------------------------------------------------------------------- /spec/project.md: -------------------------------------------------------------------------------- 1 | # `project` _(v2.0.0)_ 2 | 3 | The `project` object describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details. 4 | 5 | This field is not required if `header.project-si-source` is supplied. 6 | 7 | ## Required vs Optional Fields 8 | 9 | Required if `project` is present: 10 | 11 | - `name` 12 | - `administrators` 13 | - `repositories` 14 | - `vulnerability-reporting` 15 | 16 | Optional: 17 | 18 | - `homepage` 19 | - `funding` 20 | - `roadmap` 21 | - `documentation` 22 | - `steward` 23 | 24 | --- 25 | 26 | ## `project.name` 27 | 28 | - **Type**: `string` 29 | - **Description**: The name of the project. 30 | 31 | --- 32 | 33 | ## `project.administrators` 34 | 35 | - **Type**: `slice` of [Contact] 36 | - **Description**: A list of 1 or more individuals who have administrative access to the project's resources. 37 | 38 | --- 39 | 40 | ## `project.repositories` 41 | 42 | A list of 1 or more repositories that are part of this project, including the repository this file is published in. 43 | 44 | - `repositories[].name` 45 | - **Type**: `string` 46 | - **Description**: The name or short label of the repository. 47 | - `repositories[].comment` 48 | - **Type**: `string` 49 | - **Description**: Explanation of the repository purpose or contents and its relation to the rest of the project. 50 | - `repositories[].url` 51 | - **Type**: [URL] 52 | - **Description**: The URL where the repository is hosted. 53 | 54 | --- 55 | 56 | ## `project.vulnerability-reporting` 57 | 58 | An object describing how security vulnerabilities can be reported and how they are handled by the project. 59 | 60 | ### `vulnerability-reporting.reports-accepted` 61 | 62 | - **Type**: `bool` 63 | - **Description**: Indicates whether this project currently accepts vulnerability reports. 64 | 65 | ### `vulnerability-reporting.bug-bounty-available` 66 | 67 | - **Type**: `bool` 68 | - **Description**: Specifies whether a bug bounty program is offered. 69 | 70 | ### `vulnerability-reporting.bug-bounty-program` (optional) 71 | 72 | - **Type**: [URL] 73 | - **Description**: Path to a page providing details about any bug bounty program. 74 | 75 | ### `vulnerability-reporting.contact` (optional) 76 | 77 | - **Type**: [Contact] 78 | - **Description**: Point of contact for reporting vulnerabilities. This may be a single person or a mailgroup. 79 | 80 | ### `vulnerability-reporting.comment` (optional) 81 | 82 | - **Type**: `string` 83 | - **Description**: Additional comments or instructions about vulnerability reporting. 84 | 85 | ### `vulnerability-reporting.in-scope` (optional) 86 | 87 | - **Type**: `slice` of `strings` 88 | - **Description**: A list of issues or components that are covered by the vulnerability reporting process. 89 | 90 | ### `vulnerability-reporting.out-of-scope` (optional) 91 | 92 | - **Type**: `slice` of `strings` 93 | - **Description**: A list of issues or components not covered by the vulnerability reporting process. 94 | 95 | ### `vulnerability-reporting.pgp-key` (optional) 96 | 97 | - **Type**: `string` 98 | - **Description**: The PGP public key for secure communication. 99 | 100 | ### `vulnerability-reporting.security-policy` (optional) 101 | 102 | - **Type**: [URL] 103 | - **Description**: Path to a page containing guidelines for security-related disclosures. 104 | 105 | --- 106 | 107 | ## `project.documentation` (optional) 108 | 109 | An object containing references to key documentation URLs. 110 | 111 | ### `project.documentation.code-of-conduct` (optional) 112 | 113 | - **Type**: [URL] 114 | - **Description**: URL to the document outlining contributor and user conduct guidelines. 115 | 116 | ### `project.documentation.detailed-guide` (optional) 117 | 118 | - **Type**: [URL] 119 | - **Description**: URL to more extensive or advanced documentation. 120 | 121 | ### `project.documentation.quickstart-guide` (optional) 122 | 123 | - **Type**: [URL] 124 | - **Description**: URL to a concise guide to basic functionality for new users. 125 | 126 | ### `project.documentation.release-process` (optional) 127 | 128 | - **Type**: [URL] 129 | - **Description**: URL describing how releases are planned, prepared, and published. 130 | 131 | ### `project.documentation.support-policy` (optional) 132 | 133 | - **Type**: [URL] 134 | - **Description**: URL to documentation describing how releases are supported. See [Recommendations for publishing End-of-life dates and support timelines](https://endoflife.date/recommendations) for best practices. 135 | 136 | ### `project.documentation.signature-verification` (optional) 137 | 138 | - **Type**: [URL] 139 | - **Description**: URL to documentation explaining how to verify digital signatures on assets. 140 | 141 | --- 142 | 143 | ## `project.homepage` (optional) 144 | 145 | - **Type**: [URL] 146 | - **Description**: 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. 147 | 148 | --- 149 | 150 | ## `project.funding` (optional) 151 | 152 | - **Type**: [URL] 153 | - **Description**: A URL to information about sponsorships, donations, or other funding topics. 154 | 155 | --- 156 | 157 | ## `project.roadmap` (optional) 158 | 159 | - **Type**: [URL] 160 | - **Description**: A URL pointing to a roadmap or schedule for planned features and releases. 161 | 162 | --- 163 | 164 | ## `project.steward` (optional) 165 | 166 | - **Type**: [Link] 167 | - **Description**: 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](https://eur-lex.europa.eu/eli/reg/2024/2847/oj/eng#art_3). 168 | 169 | [URL]: ./aliases.md#url 170 | [Contact]: ./aliases.md#contact 171 | [Link]: ./aliases.md#link 172 | -------------------------------------------------------------------------------- /examples/example-full.yml: -------------------------------------------------------------------------------- 1 | header: 2 | schema-version: 2.0.0 3 | last-updated: '2025-03-01' 4 | last-reviewed: '2025-04-01' 5 | url: https://example.com/foo/bar 6 | comment: | 7 | This file contains all possible information for both project and repository, 8 | though it is not required to include all of this information every time. 9 | Nor is it required to include both a project and repository section if the project 10 | section is intended to be inherited by repositories via header.project-si-source 11 | 12 | project: 13 | name: FooBar 14 | homepage: https://example.com 15 | funding: https://example.com/FUNDING.yml 16 | roadmap: https://example.com/roadmap.html 17 | steward: 18 | uri: https://example.com 19 | comment: | 20 | Some description of the relationship between this project and its steward. 21 | administrators: 22 | - name: Joe Dohn 23 | affiliation: Foo 24 | email: joe.bob@email.com 25 | social: https://social.example.com/joebob 26 | primary: true 27 | documentation: 28 | quickstart-guide: https://example.com/quickstart 29 | detailed-guide: https://example.com/user-guide 30 | code-of-conduct: https://example.com/code-of-conduct.html 31 | release-process: https://example.com/release-process 32 | support-policy: https://example.com/support-policy 33 | signature-verification: https://example.com/signature-verification 34 | repositories: 35 | - name: Foo 36 | url: https://vcs.example.com/foobar/foo 37 | comment: | 38 | Foo is the core repo for FooBar. 39 | - name: Bar 40 | url: https://vcs.example.com/foobar/bar 41 | comment: | 42 | Bar is a subproject repo. 43 | vulnerability-reporting: 44 | reports-accepted: true 45 | bug-bounty-available: true 46 | bug-bounty-program: https://example.com/bugs.html 47 | contact: 48 | name: The security team at FooBar Enterprise provides security support for this project. 49 | email: security@something.com 50 | primary: true 51 | security-policy: https://example.com/reporting.html 52 | in-scope: 53 | - broken access control 54 | - other 55 | out-of-scope: 56 | - other 57 | pgp-key: | 58 | your-key-here 59 | comment: | 60 | Lorum ipsum... 61 | 62 | repository: 63 | url: https://github.com/kubernetes/kubernetes 64 | status: active 65 | bug-fixes-only: false 66 | accepts-change-request: true 67 | accepts-automated-change-request: true 68 | no-third-party-packages: false 69 | core-team: 70 | - name: Alice White 71 | affiliation: Foo Bar 72 | email: alicewhite@example.com 73 | social: https://social.example.com/alicewhite 74 | primary: true 75 | documentation: 76 | contributing-guide: https://example.com/contributing-guide 77 | review-policy: https://example.com/review-policy 78 | security-policy: https://example.com/security-policy.html 79 | governance: https://example.com/governance 80 | dependency-management-policy: https://example.com/dependency-management-policy 81 | license: 82 | url: https://example.com/LICENSE 83 | expression: MIT 84 | release: 85 | changelog: https://example.com/release/{version}#changelog 86 | automated-pipeline: true 87 | attestations: 88 | - name: Release VEX 89 | predicate-uri: https://intoto.VEX 90 | location: https://example.com/release/{version}#vex 91 | comment: Replace {version} with the actual version number for the release you want VEX data for. 92 | - name: Release SBOM 93 | predicate-uri: https://intoto.SPDX 94 | location: https://example.com/release/{version}#spdx 95 | comment: Replace {version} with the actual version number for the release you want an SBOM for. 96 | - name: Maintainer Identity VSA 97 | location: https://example.com/maintainer-identity 98 | predicate-uri: https://slsa.dev/verification_summary/v1 99 | comment: | 100 | This is a VSA that details how trust identities were established for maintainers of the project. 101 | - name: SCA Scan Results 102 | location: https://example.com/test-results#{version} 103 | predicate-uri: https://slsa.dev/test_results/{version} 104 | comment: Results from SCA scan for a specific version 105 | distribution-points: 106 | - uri: https://example.com/foo 107 | comment: GitHub Release Page 108 | - uri: pkg:npm/foobar 109 | comment: NPM Package 110 | license: 111 | url: https://example.com/release/{version}#license 112 | expression: MIT AND Apache-2.0 113 | security: 114 | assessments: 115 | self: 116 | evidence: https://example.com/assessment.html 117 | date: '2021-09-01' 118 | comment: | 119 | foo bar 120 | third-party: 121 | - evidence: https://example.com/artifact.html 122 | date: '2021-09-01' 123 | comment: | 124 | foo bar 125 | champions: 126 | - name: Joe Bob 127 | email: joe.bob@example.com 128 | primary: true 129 | tools: 130 | - name: Dependabot 131 | type: SCA 132 | version: 1.2.3 133 | rulesets: 134 | - built-in 135 | results: 136 | adhoc: 137 | name: Scheduled SCA Scan Results 138 | predicate-uri: https://intoto.SCA 139 | location: https://example.com/release/{version}#SCA 140 | comment: Replace {version} with the actual version number for the release you want VEX data for. 141 | ci: 142 | name: PR SCA Scan Results 143 | predicate-uri: https://intoto.SCA 144 | location: https://example.com/release/{version}#SCA 145 | comment: Replace {version} with the actual version number for the release you want VEX data for. 146 | release: 147 | name: Build & Release SCA Scan Results 148 | predicate-uri: https://intoto.SCA 149 | location: https://example.com/release/{version}#SCA 150 | comment: Replace {version} with the actual version number for the release you want VEX data for. 151 | integration: 152 | adhoc: true 153 | ci: true 154 | release: true 155 | comment: | 156 | foo bar 157 | -------------------------------------------------------------------------------- /docs/GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Security Insights Project Governance 2 | 3 | As a developing project, Security Insights aims to have a quick development cycle where decisions and community issues are resolved promptly while capturing the input of interested stakeholders. 4 | 5 | Security Insights has no formal collegiate body in charge of steering. **Decisions are guided by the consensus of community members who have achieved maintainer status.** 6 | 7 | While maintainer consensus shall be the process for decision making, all issues and proposals shall be governed by the project's guiding principles. 8 | 9 | ## Guiding Governance Principles 10 | 11 | Any issues or proposals brought to the project's maintainers shall be framed in the Security Insights guiding principles. Proposals not adhering to said principles shall not be considered for consensus. 12 | 13 | ### Favor Simplicity 14 | 15 | The goal of Security Insights is to create a minimal and efficient format that can be used with agility and be embeddable. Simple is better. 16 | 17 | ### Ensure Stability 18 | 19 | Any enhancements to the Security Insights spec and tooling must not break the working model of the specification. Changes to the description of a value are permissible, but changes that break the format or structure will have wide-ranging impacts and must be avoided unless absolutely necessary. 20 | 21 | ### Cautious Incremental Improvement 22 | 23 | New entries must be added with caution, and breaking changes should be extremely rare. The project does not have the luxury of frequent incremental improvements; therefore, each change must be carefully considered. 24 | 25 | ## Security Insights Enhancement Proposals 26 | 27 | To introduce a new feature or functional modification into the Security Insights specification, a user may open a Security Insights Enhancement Proposal (SIEP). Any SIEP opened by a community member who has achieved maintainer status shall be automatically open for discussion if the author so chooses. 28 | 29 | SIEPs filed by non-maintainers need to be sponsored by a maintainer before being admitted for discussion. 30 | 31 | SIEPs shall follow the structure set forth by the issue template in the Security Insights/community repository. 32 | 33 | After a SIEP is accepted for discussion, it shall remain in under discussion status for no longer than 30 days, after which consensus will be recorded according to the [maintainer consensus process](#maintainer-consensus). 34 | 35 | ## Maintainer Consensus 36 | 37 | Each Security Insights project (e.g., spec, tools, etc.) will have its own set of maintainers. 38 | 39 | To reach a decision on an issue, proposal, or formal SIEP, the proponents need to seek maintainer consensus. In the context of this document, "maintainer consensus" means collecting a sufficient number of favorable opinions of community members with maintainer status in the relevant projects to move forward with a proposal. 40 | 41 | This document does not prescribe a method of voting. Any mechanism that enables the collection of positive/negative votes associated with an identity may be used. Examples of this include voting through "thumbs up/down" emojis or with "+1" comments in issues. 42 | 43 | Maintainer consensus shall be reached in the following circumstances: 44 | 45 | - Having a majority of favorable maintainer votes at the end of the proposal discussion term which may not be longer than thirty (30) days. The number of favorable opinions may never be less than two (2). 46 | - Achieving a favorable vote of more than 50% of the total active maintainers at any time during the discussion period. 47 | - In most cases, when the number of organizations with active maintainers in the project exceeds four (4), the total vote count shall include maintainers from at least two different organizations. 48 | - A quorum for a favorable vote for spec changes must include maintainers from at least two (2) organizations. 49 | - An exception to reaching maintainer consensus is when voting for proposals that modify the governance model (see below). 50 | 51 | Note that when qualified, the proponents may add their favorable vote to count towards consensus but needs to be explicitly recorded in the voting mechanism. 52 | 53 | ## Review Criteria for Security Insights Repositories 54 | 55 | Any changes intended to be merged in the Security Insights repositories shall meet the following minimal criteria: 56 | 57 | - Commits must be signed off. 58 | - Pull requests must be approved by at least one of the project's maintainers. 59 | 60 | Any repository under the Security Insights organization may impose additional requirements to approve pull requests as long as these minimal requirements are met. 61 | 62 | ## Reaching Maintainer Status 63 | 64 | Any community member can be considered as a candidate for maintainer status under the following conditions: 65 | 66 | - Any community member may self-nominate as a maintainer candidate after actively contributing to Security Insights constantly for six months or more. 67 | - A sponsoring committee of maintainers that meets the qualifying criteria may nominate a community member. 68 | 69 | ### Sponsoring Committees 70 | 71 | To nominate a community member as a maintainer candidate, a group of maintainers may file a nomination. The committee shall meet the following criteria to be qualified to file the nomination: 72 | 73 | - The number of members in the committee shall not be less than two (2). 74 | - Whenever the number of organizations with maintainers in the project is more than two (2), committee members shall be from different organizations. 75 | 76 | Once the nomination is filed and deemed valid, the regular process for maintainer approval shall govern the decision to accept the candidate as a maintainer. 77 | 78 | ## Emeritus Maintainers 79 | 80 | Emeritus maintainers will be listed in a separate section on the Security Insights [MAINTAINERS.md] 81 | 82 | A maintainer who is not currently active on the project may be given Emeritus status by default after six months of no activity, such as pull request interactions or GitHub Issue interactions. A maintainer may also assign themselves Emeritus status through a pull request. 83 | 84 | A maintainer may become active from Emeritus status through [maintainer consensus] and a corresponding pull request. 85 | 86 | ## Revisions to the Governance Model 87 | 88 | The project's governance model shall be revisited every six months to address the needs of the community, as the project recognizes that communities need to steer themselves according to their size, members, and other factors that shape their complexity. 89 | 90 | At any point, a Security Insights Enhancement Proposal may be opened to redefine the project's governance. To be accepted, governing model proposals shall be approved by a qualified majority consisting of a minimum of 66% favorable votes of all active maintainers. 91 | 92 | [MAINTAINERS.md]: /MAINTAINERS.md 93 | [Maintainer Consensus]: #maintainer-consensus -------------------------------------------------------------------------------- /spec/repository.md: -------------------------------------------------------------------------------- 1 | # `repository` _(v2.0.0)_ 2 | 3 | The `repository` object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture. 4 | 5 | This section is not 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`. 6 | 7 | ## Required vs Optional Fields 8 | 9 | Required if `repository` is present: 10 | 11 | - `status` 12 | - `url` 13 | - `accepts-change-request` 14 | - `accepts-automated-change-request` 15 | - `core-team` 16 | - `license` 17 | - `security` 18 | 19 | Optional top-level fields: 20 | 21 | - `documentation` 22 | - `release` 23 | - `bug-fixes-only` (assume false if not present) 24 | - `no-third-party-packages` (assume false if not present) 25 | 26 | --- 27 | 28 | ## `repository.status` 29 | 30 | - **Type**: `string` 31 | - **Matches Pattern**: `^(active|abandoned|concept|inactive|moved|suspended|unsupported|WIP)$` 32 | - **Description**: Indicates the repository’s current [Repo Status](https://repostatus.org). 33 | 34 | --- 35 | 36 | ## `repository.accepts-change-request` 37 | 38 | - **Type**: `bool` 39 | - **Description**: Indicates whether the repository currently accepts any change requests. 40 | 41 | --- 42 | 43 | ## `repository.accepts-automated-change-request` 44 | 45 | - **Type**: `bool` 46 | - **Description**: Indicates whether the repository accepts automated or machine-generated change requests. 47 | 48 | --- 49 | 50 | ## `repository.bug-fixes-only` 51 | 52 | - **Type**: `bool` 53 | - **Description**: Specifies whether the repository only accepts bug-fixes and not feature work. 54 | 55 | --- 56 | 57 | ## `repository.no-third-party-packages` 58 | 59 | - **Type**: `bool` 60 | - **Description**: Indicates whether the repository universally avoids package dependencies from outside of the project. 61 | 62 | --- 63 | 64 | ## `repository.url` 65 | 66 | - **Type**: [URL] 67 | - **Description**: The main URL for this repository. 68 | 69 | --- 70 | 71 | ## `repository.core-team` 72 | 73 | - **Type**: `slice` of [Contact] 74 | - **Description**: A list of 1 or more core team members for this repository, such as maintainers or approvers. 75 | 76 | --- 77 | 78 | ## `repository.license` 79 | 80 | - **Type**: [License] 81 | - **Description**: The license information for this repository. 82 | 83 | --- 84 | 85 | ## `repository.security` 86 | 87 | An object describing security-related artifacts, champions, and tooling for the repository. 88 | 89 | ### `repository.security.assessments` 90 | 91 | An object describing security assessments for the repository. 92 | 93 | - `repository.security.assessments.self` 94 | - **Type**: [Assessment] 95 | - **Description**: Results of the contributor team's assessment of software produced by this repository. 96 | - `repository.security.assessments.third-party` (optional) 97 | - **Type**: `slice` of [Assessment] 98 | - **Description**: Results of third-party assessments of software produced by this repository. 99 | 100 | ### `repository.security.champions` (optional) 101 | 102 | - **Type**: `slice` of [Contact] 103 | - **Description**: 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. 104 | 105 | ### `repository.security.tools` 106 | 107 | A list of objects describing security-related tools used in the repository. 108 | 109 | - `tools[].name` 110 | - **Type**: `string` 111 | - **Description**: The name of the tool. 112 | - `tools[].type` 113 | - **Type**: `string` 114 | - **Matches Pattern**: `^(fuzzing|container|secret|SCA|SAST|other)$` 115 | - **Description**: The general category or type of the tool. 116 | - `tools[].version` (optional) 117 | - **Type**: `string` 118 | - **Description**: The version of the tool that is used. 119 | - `tools[].comment` (optional) 120 | - **Type**: `string` 121 | - **Description**: Additional notes about the tool’s usage or configuration. 122 | - `tools[].rulesets` 123 | - **Type**: `slice` of `string` 124 | - **Description**: The set of rules or configurations applied by the tool. If customization is not enabled, the only value here should be "default". 125 | - `tools[].integration` 126 | - `integration.adhoc` 127 | - **Type**: `bool` 128 | - **Description**: Indicates whether the tool is used in a scheduled process or supports an on-demand. 129 | - `integration.ci` 130 | - **Type**: `bool` 131 | - **Description**: Indicates whether the tool is used in the continuous integration process. 132 | - `integration.release` 133 | - **Type**: `bool` 134 | - **Description**: Indicates whether the tool is run before or during the release process. 135 | - `tools[].results` 136 | - `results.adhoc` (optional) 137 | - **Type**: [Attestation] 138 | - **Description**: Results of scheduled or on-demand security scans. 139 | - `results.ci` (optional) 140 | - **Type**: [Attestation] 141 | - **Description**: Results of security scans run in the continuous integration process. 142 | - `results.release` (optional) 143 | - **Type**: [Attestation] 144 | - **Description**: Results of security scans run in the build and release process. 145 | 146 | --- 147 | 148 | ## `repository.documentation` (optional) 149 | 150 | An object referencing documentation URLs. 151 | 152 | - **`documentation.contributing-guide`** (optional) 153 | - **Type**: [URL] 154 | - **Description**: The URL to a guide for proper contributions. 155 | 156 | - **`documentation.dependency-management-policy`** (optional) 157 | - **Type**: [URL] 158 | - **Description**: The URL to information about how dependencies are managed in this repository. 159 | 160 | - **`documentation.governance`** (optional) 161 | - **Type**: [URL] 162 | - **Description**: The URL to any governance documents regarding roles, responsibilities, processes, and decision-making. 163 | 164 | - **`documentation.review-policy`** (optional) 165 | - **Type**: [URL] 166 | - **Description**: The URL to a guide for proper change reviews. 167 | 168 | - **`documentation.security-policy`** (optional) 169 | - **Type**: [URL] 170 | - **Description**: The URL with information about the repository's security, including the policy for reporting security vulnerabilities. 171 | 172 | --- 173 | 174 | ## `repository.release` (optional) 175 | 176 | An object describing release-related details for this repository. 177 | 178 | ### `release.automated-pipeline` 179 | 180 | - **Type**: `bool` 181 | - **Description**: Indicates if the repository uses an automated release pipeline. 182 | 183 | ### `release.distribution-points` 184 | 185 | - **Type**: `slice` of [Link] 186 | - **Description**: 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. 187 | 188 | ### `release.changelog` (optional) 189 | 190 | - **Type**: [URL] 191 | - **Description**: A URL to the repository’s release changelog. The URL value should include placeholders such as `{version}` if relevant. 192 | 193 | ### `release.license` (optional) 194 | 195 | - **Type**: [License] 196 | - **Description**: An object describing the license details specifically for releases. This should be used when the release license differs from the repository license. 197 | 198 | ### `release.attestations` (optional) 199 | 200 | - **Type**: `slice` of [Attestation] 201 | - **Description**: A list of attestations for the repository’s releases. 202 | 203 | --- 204 | 205 | [Assessment]: ./aliases.md#assessment 206 | [Attestation]: ./aliases.md#attestation 207 | [Contact]: ./aliases.md#contact 208 | [License]: ./aliases.md#license 209 | [Link]: ./aliases.md#link 210 | [URL]: ./aliases.md#url 211 | -------------------------------------------------------------------------------- /spec/schema.cue: -------------------------------------------------------------------------------- 1 | package spec 2 | 3 | import ( 4 | "time" 5 | ) 6 | 7 | @go("si") 8 | 9 | // URL is a TLS URL 10 | #URL: =~"^https?://[^\\s]+$" 11 | 12 | // Email is a valid email address 13 | #Email: =~"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" 14 | 15 | // Date is a date in the format YYYY-MM-DD 16 | #Date: time.Format("2006-01-02") 17 | 18 | // SchemaVersion is a version string in the format X.Y.Z 19 | #SchemaVersion: =~"^[1-9]+\\.[0-9]+\\.[0-9]+$" 20 | 21 | // Assessment represents the results of a security assessment, including comments, evidence, and date. 22 | #Assessment: { 23 | 24 | // Notes or commentary about the findings or purpose of the assessment. 25 | comment: string 26 | 27 | // The name or identifier of the assessment artifact. 28 | name?: string @go(Name,type=*string) 29 | 30 | // The URL where the assessment report or artifact is located. 31 | evidence?: #URL @go(Evidence,type=*URL) 32 | 33 | // The date the assessment was published. 34 | date?: #Date 35 | } 36 | 37 | // Attestation describes an [in-toto attestation](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec), including its name, location, predicate URI, and any additional comments. 38 | #Attestation: { 39 | 40 | // The name or identifier of the attestation. 41 | name: string 42 | 43 | // A web location where the attestation can be found. 44 | location: #URL 45 | 46 | // A URI to a resource describing the attestation’s predicate or specification. 47 | "predicate-uri": string @go(PredicateURI) 48 | 49 | // Additional context or instructions for using the attestation. 50 | comment?: string @go(Comment,type=*string) 51 | } 52 | 53 | // Contact represents a person or entity responsible for the project, including their name, affiliation, and contact details. 54 | #Contact: { 55 | 56 | // The contact person's name. 57 | name: string 58 | 59 | // Indicates whether this admin is the first point of contact for inquiries. Only one entry should be marked as primary. 60 | primary: bool 61 | 62 | // The entity with which the contact is affiliated, such as a school or employer. 63 | affiliation?: string @go(Affiliation,type=*string) 64 | 65 | // A preferred email address to reach the contact. 66 | email?: #Email @go(Email,type=*Email) 67 | 68 | // A social media handle or profile for the contact. 69 | social?: string @go(Social,type=*string) 70 | } 71 | 72 | #License: { 73 | 74 | // A web address where the license can be found. 75 | url: #URL 76 | 77 | // The SPDX license expression for the license. 78 | expression: string 79 | } 80 | 81 | #Link: { 82 | 83 | // A link to a resource, not restricted to http/s. 84 | uri: string 85 | 86 | // Instructions or information about the link. 87 | comment: string 88 | } 89 | 90 | // The ProjectRepository object describes a repository that is part of a project, including its name, comment, and URL. 91 | #ProjectRepository: { 92 | 93 | // The name or short label of the repository. 94 | name: string 95 | 96 | // Explanation of the repository purpose or contents and its relation to the rest of the project. 97 | comment: string 98 | 99 | // The URL where the repository is hosted. 100 | url: #URL 101 | } 102 | 103 | // 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. 104 | #SecurityInsights: { 105 | 106 | // header captures high level metadata about the schema. 107 | header: #Header 108 | 109 | // 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. 110 | project?: #Project 111 | 112 | // 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`. 113 | repository?: #Repository 114 | } 115 | 116 | // The Header object captures high-level metadata about the schema. 117 | #Header: { 118 | 119 | // The date when the document or data was last reviewed. 120 | "last-reviewed": #Date @go(LastReviewed) 121 | 122 | // The date when the document or data was last updated. 123 | "last-updated": #Date @go(LastUpdated) 124 | 125 | // The version of the Security Insights schema being used. 126 | "schema-version": #SchemaVersion @go(SchemaVersion) 127 | 128 | // The primary reference URL for this schema’s origin or repository. 129 | url: #URL @go(URL) 130 | 131 | // Additional information about the schema. 132 | comment?: string @go(Comment,type=*string) 133 | 134 | // 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. 135 | "project-si-source"?: #URL @go(ProjectSISource,type=*URL) 136 | } 137 | 138 | // 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. 139 | #ProjectDocumentation: { 140 | // URL to more extensive or advanced documentation. 141 | "detailed-guide"?: #URL @go(DetailedGuide,type=*URL) 142 | 143 | // URL to the document outlining contributor and user conduct guidelines. 144 | "code-of-conduct"?: #URL @go(CodeOfConduct,type=*URL) 145 | 146 | // URL to a concise guide to basic functionality for new users. 147 | "quickstart-guide"?: #URL @go(QuickstartGuide,type=*URL) 148 | 149 | // URL describing how releases are planned, prepared, and published. 150 | "release-process"?: #URL @go(ReleaseProcess,type=*URL) 151 | 152 | // URL to documentation describing how releases are supported. See [Recommendations for publishing End-of-life dates and support timelines](https://endoflife.date/recommendations) for best practices. 153 | "support-policy"?: #URL @go(SupportPolicy,type=*URL) 154 | 155 | // URL to documentation explaining how to verify digital signatures on assets. 156 | "signature-verification"?: #URL @go(SignatureVerification,type=*URL) 157 | } 158 | 159 | // VulnerabilityReporting describes how security vulnerabilities can be reported and how they are handled by the project. 160 | #VulnerabilityReporting: { 161 | // Indicates whether this project currently accepts vulnerability reports. 162 | "reports-accepted": bool @go(ReportsAccepted) 163 | 164 | // Specifies whether a bug bounty program is offered. 165 | "bug-bounty-available": bool @go(BugBountyAvailable) 166 | 167 | // Path to a page providing details about any bug bounty program. 168 | "bug-bounty-program"?: #URL @go(BugBountyProgram,type=*URL) 169 | 170 | // Point of contact for reporting vulnerabilities. This may be a single person or a mailgroup. 171 | contact?: #Contact @go(Contact,type=*Contact) 172 | 173 | // Additional comments or instructions about vulnerability reporting. 174 | comment?: string @go(Comment,type=*string) 175 | 176 | // Path to a page containing guidelines for security-related disclosures. 177 | "security-policy"?: #URL @go(SecurityPolicy,type=*URL) 178 | 179 | // The PGP public key for secure communication. 180 | "pgp-key"?: string @go(PGPKey,type=*URL) 181 | 182 | // A list of issues or components that are covered by the vulnerability reporting process. 183 | "in-scope"?: [...string] @go(InScope,type=*URL) 184 | 185 | // A list of issues or components not covered by the vulnerability reporting process. 186 | "out-of-scope"?: [...string] @go(OutOfScope,type=*URL) 187 | } 188 | 189 | // Project describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details. 190 | #Project: { 191 | 192 | // The name of the project. 193 | name: string 194 | 195 | // 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. 196 | homepage?: #URL @go(HomePage,type=*URL) 197 | 198 | // A URL pointing to a roadmap or schedule for planned features and releases. 199 | roadmap?: #URL @go(Roadmap,type=*URL) 200 | 201 | // A URL to information about sponsorships, donations, or other funding topics. 202 | funding?: #URL @go(Funding,type=*URL) 203 | 204 | // 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](https://eur-lex.europa.eu/eli/reg/2024/2847/oj/eng#art_3). 205 | steward?: #Link @go(Steward,type=*Link) 206 | 207 | // A list of 1 or more individuals who have administrative access to the project's resources. 208 | administrators: [#Contact, ...] @go(,type=[]Contact) 209 | 210 | // A list of 1 or more repositories that are part of this project, including the repository this file is published in. 211 | repositories: [#ProjectRepository, ...] @go(Repositories,type=[]ProjectRepository) 212 | 213 | // An object describing how security vulnerabilities can be reported and how they are handled by the project. 214 | "vulnerability-reporting": #VulnerabilityReporting @go(VulnerabilityReporting) 215 | 216 | // the project's documentation resources 217 | documentation?: #ProjectDocumentation @go(Documentation,type=*ProjectDocumentation) 218 | } 219 | 220 | // 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. 221 | #SecurityToolIntegration: { 222 | // Indicates whether the tool is used in a scheduled process or supports an on-demand. 223 | adhoc: bool 224 | 225 | // Indicates whether the tool is used in the continuous integration process. 226 | ci: bool 227 | 228 | // Indicates whether the tool is run before or during the release process. 229 | release: bool 230 | } 231 | 232 | // SecurityToolResults describes the results of security scans, including those run on-demand, in continuous integration, and during the release process. 233 | #SecurityToolResults: { 234 | // Results of scheduled or on-demand security scans. 235 | adhoc?: #Attestation @go(Adhoc,type=*Attestation) 236 | 237 | // Results of security scans run in the continuous integration process. 238 | ci?: #Attestation @go(CI,type=*Attestation) 239 | 240 | // Results of security scans run in the build and release process. 241 | release?: #Attestation @go(Release,type=*Attestation) 242 | } 243 | 244 | // SecurityTool describes a security-related tool used in the repository, including its name, type, version, rulesets, integration details, and results. 245 | #SecurityTool: { 246 | // The name of the tool. 247 | name: string 248 | 249 | // The general category or type of the tool. 250 | type: "fuzzing" | "container" | "secret" | "SCA" | "SAST" | "other" 251 | 252 | // The version of the tool that is used. 253 | version?: string @go(Version,type=*string) 254 | 255 | // Additional notes about the tool’s usage or configuration. 256 | comment?: string @go(Comment,type=*string) 257 | 258 | // The set of rules or configurations applied by the tool. If customization is not enabled, the only value here should be "default". 259 | rulesets: ["default"] | [...string] @go(,type=[]string) 260 | 261 | // An object describing how the tool is integrated with the project. 262 | integration: #SecurityToolIntegration @go(Integration) 263 | 264 | results: #SecurityToolResults @go(Results) 265 | } 266 | 267 | // SecurityPosture describes the security posture of the repository, including assessments, champions, and tools. 268 | #SecurityPosture: { 269 | // An object describing security assessments for the repository. 270 | assessments: { 271 | // Results of the contributor team's assessment of software produced by this repository. 272 | self: #Assessment 273 | 274 | // Results of third-party assessments of software produced by this repository. 275 | "third-party"?: [...#Assessment] @go(ThirdPartyAssessment) 276 | } 277 | 278 | // 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. 279 | champions?: [...#Contact] 280 | 281 | // A list of objects describing security-related tools used in the repository. 282 | tools?: [...#SecurityTool] @go(Tools,type=[]SecurityTool) 283 | } 284 | 285 | // RepositoryDocumentation contains links to various documents related to the repository, including contributing guides, dependency management policies, governance documents, and review policies. 286 | #RepositoryDocumentation: { 287 | // URL to a document outlining the process for contributing to the repository. 288 | "contributing-guide"?: #URL @go(ContributingGuide,type=*URL) 289 | // URL to a document outlining the process for managing dependencies in the repository. 290 | "dependency-management-policy"?: #URL @go(DependencyManagementPolicy,type=*URL) 291 | // URL to any governance documents regarding roles, responsibilities, processes, and decision-making. 292 | governance?: #URL @go(Governance,type=*URL) 293 | // URL to a document outlining the process for reviewing changes to the repository. 294 | "review-policy"?: #URL @go(ReviewPolicy,type=*URL) 295 | // URL with information about the repository's security, including the policy for reporting security vulnerabilities. 296 | "security-policy"?: #URL @go(SecurityPolicy,type=*URL) 297 | } 298 | 299 | // ReleaseDetails describes the release process for the repository, including automated pipelines, distribution points, changelogs, licenses, and attestations. 300 | #ReleaseDetails: { 301 | // Indicates if the repository uses an automated release pipeline. 302 | "automated-pipeline": bool @go(AutomatedPipeline) 303 | // 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. 304 | "distribution-points": [#Link, ...] @go(DistributionPoints,type=[]Link) 305 | // A URL to the repository’s release changelog. The URL value should include placeholders such as `{version}` if relevant. 306 | changelog?: #URL @go(Changelog,type=*URL) 307 | // Describes the license details specifically for releases. This should be used when the release license differs from the repository license. 308 | license?: #License @go(License,type=*License) 309 | // List of attestations for the repository’s releases. 310 | attestations?: [...#Attestation] 311 | } 312 | 313 | // The Repository object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture. 314 | #Repository: { 315 | 316 | // Indicates the repository’s current [Repo Status](https://repostatus.org). 317 | status: "active" | "abandoned" | "concept" | "inactive" | "moved" | "suspended" | "unsupported" | "WIP" 318 | 319 | // The main URL for this repository. 320 | url: #URL 321 | 322 | // Indicates whether the repository currently accepts any change requests. 323 | "accepts-change-request": bool @go(AcceptsChangeRequest) 324 | 325 | // Indicates whether the repository accepts automated or machine-generated change requests. 326 | "accepts-automated-change-request": bool @go(AcceptsAutomatedChangeRequest) 327 | 328 | // Specifies whether the repository only accepts bug-fixes and not feature work. 329 | "bug-fixes-only"?: bool @go(BugFixesOnly) 330 | 331 | // Indicates whether the repository universally avoids package dependencies from outside of the project. 332 | "no-third-party-packages"?: bool @go(NoThirdPartyPackages) 333 | 334 | // A list of 1 or more core team members for this repository, such as maintainers or approvers. 335 | "core-team": [#Contact, ...] @go(CoreTeam,type=[]Contact) 336 | 337 | // The license information for this repository. 338 | license: #License 339 | 340 | // An object describing security-related artifacts, champions, and tooling for the repository. 341 | security: #SecurityPosture @go(SecurityPosture) 342 | 343 | // Documentation links for the repository, including links to contributing guides, dependency management policies, governance documents, and review policies. 344 | documentation?: #RepositoryDocumentation @go(Documentation,type=*RepositoryDocumentation) 345 | 346 | // Release describes the release process for the repository. 347 | release?: #ReleaseDetails @go(ReleaseDetails,type=*ReleaseDetails) 348 | } 349 | -------------------------------------------------------------------------------- /docs/threat-model/SECURITY-INSIGHTS-STRIDE-threat-model.json: -------------------------------------------------------------------------------- 1 | { 2 | "summary": { 3 | "title": "SECURITY-INSIGHTS Threat Model", 4 | "owner": "Luigi Gubello", 5 | "description": "A threat model for the project SECURITY-INSIGHTS to evidence the related risks." 6 | }, 7 | "detail": { 8 | "contributors": [], 9 | "diagrams": [ 10 | { 11 | "title": "SECURITY-INSIGHTS Threat Model", 12 | "thumbnail": "./public/content/images/thumbnail.stride.jpg", 13 | "diagramType": "STRIDE", 14 | "id": 0, 15 | "$$hashKey": "object:193", 16 | "diagramJson": { 17 | "cells": [ 18 | { 19 | "type": "tm.Actor", 20 | "size": { 21 | "width": 160, 22 | "height": 80 23 | }, 24 | "position": { 25 | "x": 50, 26 | "y": 50 27 | }, 28 | "angle": 0, 29 | "id": "43eb853d-6203-4934-984f-b0e881f4e22e", 30 | "z": 1, 31 | "hasOpenThreats": false, 32 | "description": "Official maintainer of the open source project", 33 | "attrs": { 34 | ".element-shape": { 35 | "class": "element-shape hasNoOpenThreats isInScope" 36 | }, 37 | "text": { 38 | "text": "1. Maintainer" 39 | }, 40 | ".element-text": { 41 | "class": "element-text hasNoOpenThreats isInScope" 42 | } 43 | } 44 | }, 45 | { 46 | "type": "tm.Actor", 47 | "size": { 48 | "width": 160, 49 | "height": 80 50 | }, 51 | "position": { 52 | "x": 50, 53 | "y": 374 54 | }, 55 | "angle": 0, 56 | "id": "a83e58e5-821c-458b-ae7b-79632b9e0de0", 57 | "z": 2, 58 | "hasOpenThreats": false, 59 | "description": "External contributor to the open source project", 60 | "attrs": { 61 | ".element-shape": { 62 | "class": "element-shape hasNoOpenThreats isInScope" 63 | }, 64 | "text": { 65 | "text": "2. Contributor" 66 | }, 67 | ".element-text": { 68 | "class": "element-text hasNoOpenThreats isInScope" 69 | } 70 | } 71 | }, 72 | { 73 | "type": "tm.Actor", 74 | "size": { 75 | "width": 160, 76 | "height": 80 77 | }, 78 | "position": { 79 | "x": 1025, 80 | "y": 175 81 | }, 82 | "angle": 0, 83 | "id": "4597982a-9683-4d3a-9f15-37a910c32ec0", 84 | "z": 3, 85 | "hasOpenThreats": true, 86 | "description": "(e.g. URLs, documents, third-party tools mentioned in the SECURITY-INSIGHTS.yml)", 87 | "threats": [ 88 | { 89 | "status": "Open", 90 | "severity": "High", 91 | "modelType": "STRIDE", 92 | "title": "Supply-chain", 93 | "type": "Spoofing", 94 | "description": "Attackers can obtain the control of a third-party sources (e.g. website domain, server, etc) linked in the SECURITY-INSIGHTS.yml.", 95 | "mitigation": "Maintainers could self-host the evidence to reduce risks.", 96 | "threatId": "b122089b-3b8f-4f94-8845-82cb6a7d588b", 97 | "$$hashKey": "object:250" 98 | } 99 | ], 100 | "attrs": { 101 | ".element-shape": { 102 | "class": "element-shape hasOpenThreats isInScope" 103 | }, 104 | "text": { 105 | "text": "4. Third-party sources" 106 | }, 107 | ".element-text": { 108 | "class": "element-text hasOpenThreats isInScope" 109 | } 110 | } 111 | }, 112 | { 113 | "type": "tm.Store", 114 | "size": { 115 | "width": 160, 116 | "height": 80 117 | }, 118 | "position": { 119 | "x": 591, 120 | "y": 376 121 | }, 122 | "angle": 0, 123 | "id": "25db412a-6568-4998-bf11-a64f822cde91", 124 | "z": 4, 125 | "hasOpenThreats": false, 126 | "description": "A tool that processes the SECURITY-INSIGHTS.yml", 127 | "outOfScope": true, 128 | "reasonOutOfScope": "Vulnerabilities or malicious behaviors in the scanner are not directly related to SECURITY-INSIGHTS.yml", 129 | "attrs": { 130 | ".element-shape": { 131 | "class": "element-shape hasNoOpenThreats isOutOfScope" 132 | }, 133 | "text": { 134 | "text": "5. Scanner" 135 | }, 136 | ".element-text": { 137 | "class": "element-text hasNoOpenThreats isInScope" 138 | } 139 | } 140 | }, 141 | { 142 | "type": "tm.Boundary", 143 | "size": { 144 | "width": 10, 145 | "height": 10 146 | }, 147 | "smooth": true, 148 | "source": { 149 | "x": 536, 150 | "y": 518 151 | }, 152 | "target": { 153 | "x": 877, 154 | "y": 497 155 | }, 156 | "vertices": [ 157 | { 158 | "x": 517, 159 | "y": 375 160 | }, 161 | { 162 | "x": 788, 163 | "y": 339 164 | } 165 | ], 166 | "id": "c9437a71-bcf5-4e59-a3da-fd21c1c3b6dd", 167 | "z": 5, 168 | "attrs": {} 169 | }, 170 | { 171 | "type": "tm.Process", 172 | "size": { 173 | "width": 100, 174 | "height": 100 175 | }, 176 | "position": { 177 | "x": 395, 178 | "y": 127 179 | }, 180 | "angle": 0, 181 | "id": "eb4c9135-b8f5-40a8-9fdc-b0226d8e37ce", 182 | "z": 6, 183 | "hasOpenThreats": false, 184 | "attrs": { 185 | ".element-shape": { 186 | "class": "element-shape hasNoOpenThreats isInScope" 187 | }, 188 | "text": { 189 | "text": "6. Pull request" 190 | }, 191 | ".element-text": { 192 | "class": "element-text hasNoOpenThreats isInScope" 193 | } 194 | } 195 | }, 196 | { 197 | "type": "tm.Flow", 198 | "size": { 199 | "width": 10, 200 | "height": 10 201 | }, 202 | "smooth": true, 203 | "source": { 204 | "x": 212, 205 | "y": 92 206 | }, 207 | "target": { 208 | "x": 393, 209 | "y": 161 210 | }, 211 | "vertices": [], 212 | "id": "2797c3a2-dfe4-4480-aeae-e01d252bede5", 213 | "labels": [ 214 | { 215 | "position": 0.5, 216 | "attrs": { 217 | "text": { 218 | "text": "7. Open pull request", 219 | "font-weight": "400", 220 | "font-size": "small" 221 | } 222 | } 223 | } 224 | ], 225 | "z": 7, 226 | "hasOpenThreats": true, 227 | "description": "The user opens a pull request to edit/update/implement SECURITY-INSIGHTS.yml", 228 | "threats": [ 229 | { 230 | "status": "Open", 231 | "severity": "High", 232 | "modelType": "STRIDE", 233 | "type": "Repudiation", 234 | "title": "False information in the SECURITY-INSIGHTS.yml", 235 | "threatId": "0fcd6224-7ac3-4496-9779-ef98c8561d54", 236 | "description": "Maintainers could upload false information in the SECURITY-INSIGHTS.yml just to obtain a high score from the scanners or other services which use SECURITY-INSIGHTS to evaluate the project.", 237 | "mitigation": "Scanners could introduce some additional checks (e.g. check if URLs return 200 OK status) and a weighted score to reduce the risks. In addition, the open-source community can read the file and report false information (or just information without clear evidence).", 238 | "$$hashKey": "object:244" 239 | }, 240 | { 241 | "status": "Open", 242 | "severity": "High", 243 | "modelType": "STRIDE", 244 | "title": "Private information sharing", 245 | "type": "Information disclosure", 246 | "threatId": "b851dfa6-ea0c-4db6-9973-afbfb144e302", 247 | "$$hashKey": "object:185", 248 | "description": "A maintainer shares mistakenly private critical information (e.g. security audit containing unpatched vulnerabilities).", 249 | "mitigation": "" 250 | } 251 | ], 252 | "attrs": { 253 | ".marker-target": { 254 | "class": "marker-target hasOpenThreats isInScope" 255 | }, 256 | ".connection": { 257 | "class": "connection hasOpenThreats isInScope" 258 | } 259 | } 260 | }, 261 | { 262 | "type": "tm.Flow", 263 | "size": { 264 | "width": 10, 265 | "height": 10 266 | }, 267 | "smooth": true, 268 | "source": { 269 | "id": "a83e58e5-821c-458b-ae7b-79632b9e0de0" 270 | }, 271 | "target": { 272 | "id": "eb4c9135-b8f5-40a8-9fdc-b0226d8e37ce" 273 | }, 274 | "id": "1194b293-ee9f-417e-854a-5a0958e46173", 275 | "labels": [ 276 | { 277 | "position": 0.5, 278 | "attrs": { 279 | "text": { 280 | "text": "8. Open pull request", 281 | "font-weight": "400", 282 | "font-size": "small" 283 | } 284 | } 285 | } 286 | ], 287 | "z": 7, 288 | "hasOpenThreats": true, 289 | "description": "The user opens a pull request to edit/update/implement SECURITY-INSIGHTS.yml", 290 | "vertices": [], 291 | "threats": [ 292 | { 293 | "status": "Open", 294 | "severity": "Medium", 295 | "modelType": "STRIDE", 296 | "title": "Malicious pull-request", 297 | "type": "Tampering", 298 | "threatId": "ea435a89-8720-4ce0-b414-a9a7a9d7950a", 299 | "description": "A malicious contributor could introduce false or malicious information (e.g. malicious URLs) to obtain a particular advantage.", 300 | "mitigation": "The contributors' PRs to SECURITY-INSIGHTS.yml should be carefully reviewed and approved by the maintainers. In addition, the maintainers could decide to not accept direct contributions to the SECURITY-INSIGHTS.yml.", 301 | "$$hashKey": "object:192" 302 | } 303 | ], 304 | "attrs": { 305 | ".marker-target": { 306 | "class": "marker-target hasOpenThreats isInScope" 307 | }, 308 | ".connection": { 309 | "class": "connection hasOpenThreats isInScope" 310 | } 311 | } 312 | }, 313 | { 314 | "type": "tm.Flow", 315 | "size": { 316 | "width": 10, 317 | "height": 10 318 | }, 319 | "smooth": true, 320 | "source": { 321 | "id": "eb4c9135-b8f5-40a8-9fdc-b0226d8e37ce" 322 | }, 323 | "target": { 324 | "x": 719, 325 | "y": 20 326 | }, 327 | "vertices": [], 328 | "id": "7c65fde7-e414-48e6-972a-3038b0cf7ea9", 329 | "labels": [ 330 | { 331 | "position": 0.5, 332 | "attrs": { 333 | "text": { 334 | "text": "9. Merge pull request", 335 | "font-weight": "400", 336 | "font-size": "small" 337 | } 338 | } 339 | } 340 | ], 341 | "z": 8, 342 | "hasOpenThreats": true, 343 | "description": "", 344 | "threats": [ 345 | { 346 | "status": "Open", 347 | "severity": "Medium", 348 | "modelType": "STRIDE", 349 | "title": "Missing pull-request review or lacks in the review process", 350 | "type": "Tampering", 351 | "description": "Missing PR review or lack in the review process can lead to the tampering of SECURITY-INSIGHTS.yml by adding false information.", 352 | "mitigation": "THE PR should be formally reviewed and approved by another maintainer.", 353 | "threatId": "dccde8e4-d6a1-4215-b3b5-68539a4006be", 354 | "$$hashKey": "object:106" 355 | } 356 | ], 357 | "attrs": { 358 | ".marker-target": { 359 | "class": "marker-target hasOpenThreats isInScope" 360 | }, 361 | ".connection": { 362 | "class": "connection hasOpenThreats isInScope" 363 | } 364 | } 365 | }, 366 | { 367 | "type": "tm.Store", 368 | "size": { 369 | "width": 160, 370 | "height": 80 371 | }, 372 | "position": { 373 | "x": 721, 374 | "y": 1 375 | }, 376 | "angle": 0, 377 | "id": "53a861ba-8fc7-425c-b258-00eac6121699", 378 | "z": 9, 379 | "hasOpenThreats": false, 380 | "attrs": { 381 | ".element-shape": { 382 | "class": "element-shape hasNoOpenThreats isInScope" 383 | }, 384 | "text": { 385 | "text": "3.\nSECURITY-INSIGHTS.yml" 386 | }, 387 | ".element-text": { 388 | "class": "element-text hasNoOpenThreats isInScope" 389 | } 390 | } 391 | }, 392 | { 393 | "type": "tm.Flow", 394 | "size": { 395 | "width": 10, 396 | "height": 10 397 | }, 398 | "smooth": true, 399 | "source": { 400 | "id": "25db412a-6568-4998-bf11-a64f822cde91" 401 | }, 402 | "target": { 403 | "id": "53a861ba-8fc7-425c-b258-00eac6121699" 404 | }, 405 | "vertices": [], 406 | "id": "53ee6932-ae9e-4cc4-b1aa-e13eb68e1a19", 407 | "labels": [ 408 | { 409 | "position": 0.5, 410 | "attrs": { 411 | "text": { 412 | "text": "10. YAML processing", 413 | "font-weight": "400", 414 | "font-size": "small" 415 | } 416 | } 417 | } 418 | ], 419 | "z": 10, 420 | "hasOpenThreats": false, 421 | "description": "The scanner ingests and processes the SECURITY-INSIGHTS.yml", 422 | "outOfScope": true, 423 | "reasonOutOfScope": "The scanner's security is not directly related to SECURITY-INSIGHTS.yml", 424 | "attrs": { 425 | ".marker-target": { 426 | "class": "marker-target hasNoOpenThreats isInScope" 427 | }, 428 | ".connection": { 429 | "class": "connection hasNoOpenThreats isOutOfScope" 430 | } 431 | } 432 | }, 433 | { 434 | "type": "tm.Flow", 435 | "size": { 436 | "width": 10, 437 | "height": 10 438 | }, 439 | "smooth": true, 440 | "source": { 441 | "id": "53a861ba-8fc7-425c-b258-00eac6121699" 442 | }, 443 | "target": { 444 | "id": "4597982a-9683-4d3a-9f15-37a910c32ec0" 445 | }, 446 | "vertices": [], 447 | "id": "5f77093b-03ab-4503-a7ee-407de1fadf7b", 448 | "labels": [ 449 | { 450 | "position": 0.5, 451 | "attrs": { 452 | "text": { 453 | "text": "11. Link to external\nsources", 454 | "font-weight": "400", 455 | "font-size": "small" 456 | } 457 | } 458 | } 459 | ], 460 | "z": 11, 461 | "hasOpenThreats": false, 462 | "description": "SECURITY-INSIGHTS.yml links to external sources", 463 | "attrs": { 464 | ".marker-target": { 465 | "class": "marker-target hasNoOpenThreats isInScope" 466 | }, 467 | ".connection": { 468 | "class": "connection hasNoOpenThreats isInScope" 469 | } 470 | } 471 | } 472 | ] 473 | }, 474 | "size": { 475 | "height": 590, 476 | "width": 1505 477 | } 478 | } 479 | ], 480 | "reviewer": "" 481 | } 482 | } --------------------------------------------------------------------------------