diff --git a/.github/ISSUE_TEMPLATES/siep.yml b/.github/ISSUE_TEMPLATE/siep.yml similarity index 100% rename from .github/ISSUE_TEMPLATES/siep.yml rename to .github/ISSUE_TEMPLATE/siep.yml diff --git a/.github/security-insights.yml b/.github/security-insights.yml new file mode 100644 index 0000000..0e9241d --- /dev/null +++ b/.github/security-insights.yml @@ -0,0 +1,50 @@ +header: + schema-version: 1.0.0 + last-updated: '2021-09-01' + last-reviewed: '2022-09-01' + url: https://github.com/ossf/security-insights-spec + comment: This file contains the security information for the Security Insights project. + +project: + name: Security Insights + administrators: + - name: Christopher Robinson + affiliation: Linux Foundation + primary: true + repositories: + - name: Security Insights + url: https://github.com/ossf/security-insights-spec + comment: | + Security Insights is the core repo for the Security Insights project. + vulnerability-reporting: + reports-accepted: true + bug-bounty-available: false + +repository: + status: active + url: https://github.com/ossf/security-insights-spec + accepts-change-request: true + accepts-automated-change-request: false + no-third-party-packages: true + core-team: + - name: Eddie Knight + affiliation: Sonatype + primary: true + license: + url: https://github.com/ossf/security-insights-spec/blob/main/LICENSE + expression: MIT AND Community Specification License 1.0 + security: + assessments: + self: + evidence: https://github.com/ossf/security-insights-spec/blob/main/docs/threat-model + comment: | + A light-weight threat model was completed when the project was first started, + and it remains accurate to-date. + documentation: + contributing-guide: https://github.com/ossf/security-insights-spec/blob/main/.github/CONTRIBUTING.md + governance: https://github.com/ossf/security-insights-spec/blob/main/docs/GOVERNANCE.md + release: + automated-pipeleine: false + distribution-points: + - uri: https://github.com/ossf/security-insights-spec/releases + comment: GitHub Release Page diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 380cc09..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,29 +0,0 @@ -Thank you for your interest in contributing to the Security Insights Specification! - -## How to Contribute - -1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository to your own GitHub account. -2. Make changes or improvements to the specification document in your forked repository. -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. - -## Issue Reporting - -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. - -## Review Process - -Our team will review your contributions and provide feedback. Once approved, we'll merge your changes. - -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. - -## Code of Conduct - -Please adhere to our [Code of Conduct](https://github.com/ossf/.github/CODE_OF_CONDUCT.md) when participating in this project. - -## Licensing - -By contributing, you agree that your contributions will be licensed under the [project's license](LICENSE.md). - -## Thanks! - -Thank you for helping improve the Security Insights Specification! diff --git a/README.md b/README.md index 5993172..a65492c 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,25 @@ This specification provides a mechanism for projects to report information about The data tracked within this specification is intended to fill the gaps between simplified solutions such as `SECURITY.md` and comprehensive automatable 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. +## Usage + +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/`. Users should assume the contents of that file will be updated any time the relevant information changes. + +To ensure you are adhering to an official version of the specification, please refer to the `specification.md` in the [latest release](https://github.com/ossf/security-insights/releases/latest), which is a versioned compilation of all details. + +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. + 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. -All information regarding the maintenance, security, and consumption of the Security Insights Specification can be found in this repo within the latest version of the [official specification file](/specification.md). +## Maintenance + +The specification maintenance occurs in the following places: + +- `specification/`: Contains markdown details for all specification values +- `schema.cue`: Contains the CUE schema that can be used to validate files against the specification +- `template-full.yml`: Contains a template that includes all possible fields +- `template-minimal.yml`: Contains a template that includes only the required fields + +Discussion and feedback should take place in [GitHub Issues](https://github.com/ossf/security-insights/issues). -Please use GitHub issues to discuss the maintenance of this specification, and review the [Contributor Guidelines](./CONTRIBUTING.md) for more information. +Because this specification recieves light maintenance and infrequent updates, beginning in 2025 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. diff --git a/SECURITY-INSIGHTS.yml b/SECURITY-INSIGHTS.yml deleted file mode 100644 index a827276..0000000 --- a/SECURITY-INSIGHTS.yml +++ /dev/null @@ -1,49 +0,0 @@ -header: - schema-version: 1.0.0 - last-updated: '2023-09-28' - last-reviewed: '2023-09-28' - expiration-date: '2024-09-28T01:00:00.000Z' - project-url: https://github.com/ossf/security-insights-spec - project-release: '1.0.0' -project-lifecycle: - status: active - bug-fixes-only: false - core-team: - - contact: github:luigigubello - - contact: github:eddie-knight -contribution-policy: - accepts-pull-requests: true - accepts-automated-pull-requests: true - code-of-conduct: https://openssf.org/community/code-of-conduct -documentation: -- https://github.com/ossf/security-insights-spec/blob/main/specification.md -distribution-points: -- https://github.com/ossf/security-insights-spec -security-artifacts: - threat-model: - threat-model-created: true - evidence-url: - - https://github.com/ossf/security-insights-spec/blob/main/docs/threat-model.md -security-testing: -- tool-type: sca - tool-name: Dependabot - tool-version: latest - integration: - ad-hoc: false - ci: true - before-release: true - comment: | - Dependabot is enabled for this repo. -security-contacts: -- type: email - value: security@openssf.org -vulnerability-reporting: - accepts-vulnerability-reports: true - security-policy: https://github.com/ossf/security-insights-spec/security/policy - email-contact: security@openssf.org - comment: | - The first and best way to report a vulnerability is by using private security issues in GitHub. -dependencies: - third-party-packages: true - dependencies-lists: - - https://github.com/ossf/security-insights-spec/blob/main/validators/python/requirements.txt diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index fb6f872..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,7 +0,0 @@ -# Reporting Security Issues - -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. - -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. - -Other contacts: security@openssf.org \ No newline at end of file diff --git a/GOVERNANCE.md b/docs/GOVERNANCE.md similarity index 100% rename from GOVERNANCE.md rename to docs/GOVERNANCE.md diff --git a/MAINTAINERS.md b/docs/MAINTAINERS.md similarity index 100% rename from MAINTAINERS.md rename to docs/MAINTAINERS.md diff --git a/schema.cue b/schema.cue index 8a05f73..dbb07f3 100644 --- a/schema.cue +++ b/schema.cue @@ -16,9 +16,9 @@ import ( } #Attestation: { - name: string - location: #URL - "predicate-uri": string + name: string + location: #URL + "predicate-uri": string comment?: string } diff --git a/specification-details/aliases.md b/specification/aliases.md similarity index 99% rename from specification-details/aliases.md rename to specification/aliases.md index 47f3134..652d60e 100644 --- a/specification-details/aliases.md +++ b/specification/aliases.md @@ -1,4 +1,4 @@ -# Aliases +# Aliases _(v2.0.0)_ The following aliases are used throughout the schema for consistency. diff --git a/specification-details/header.md b/specification/header.md similarity index 97% rename from specification-details/header.md rename to specification/header.md index ed59ed5..ea4ee56 100644 --- a/specification-details/header.md +++ b/specification/header.md @@ -1,4 +1,4 @@ -# `header` +# `header` _(v2.0.0)_ The `header` object captures high-level metadata about the schema. diff --git a/specification-details/project.md b/specification/project.md similarity index 99% rename from specification-details/project.md rename to specification/project.md index 534c2e8..6577833 100644 --- a/specification-details/project.md +++ b/specification/project.md @@ -1,4 +1,4 @@ -# `project` +# `project` _(v2.0.0)_ The `project` object describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details. diff --git a/specification-details/repository.md b/specification/repository.md similarity index 99% rename from specification-details/repository.md rename to specification/repository.md index 18a0eea..8e8a360 100644 --- a/specification-details/repository.md +++ b/specification/repository.md @@ -1,4 +1,4 @@ -# `repository` +# `repository` _(v2.0.0)_ The `repository` object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture. diff --git a/template-full.yml b/template-full.yml index 4a1bae8..b13dadf 100644 --- a/template-full.yml +++ b/template-full.yml @@ -1,5 +1,5 @@ header: - schema-version: 1.0.0 + schema-version: 2.0.0 last-updated: '2021-09-01' last-reviewed: '2022-09-01' url: https://foo.bar/foo/bar diff --git a/template-minimum.yml b/template-minimum.yml index bb839ac..1fd9755 100644 --- a/template-minimum.yml +++ b/template-minimum.yml @@ -1,5 +1,5 @@ header: - schema-version: 1.0.0 + schema-version: 2.0.0 last-updated: '2021-09-01' last-reviewed: '2022-09-01' url: https://foo.bar/kubernetes/kubernetes