Split out the spec into separate md files

Signed-off-by: Eddie Knight <[email protected]>

.gitignore

@@ -0,0 +1 @@
+website/content/specification

specification/contribution-policy.md

@@ -0,0 +1,48 @@
+# Contribution Policy
+
+The "`contribution-policy`" section offers documentation outlining the project's contribution rules, requirements, and policies. It serves as a resource for the community, helping them understand how to contribute to the project. Specifically, this section clarifies whether pull requests and automated pull requests are permitted. This section is **required**.
+
+```yaml
+contribution-policy:
+  accepts-pull-requests: true
+  accepts-automated-pull-requests: true
+  automated-tools-list:
+  - automated-tool: example/security-research
+    action: denied
+    path:
+    - main/foo/bar
+    - main/examples
+    comment: |
+      foo bar
+  contributing-policy: https://example.com/development-policy.html
+  code-of-conduct: https://example.com/code-of-conduct.html
+```
+
+- `accepts-pull-requests` (Required)
+  - **Description:** Define if the maintainers accept pull-requests or not from external contributors.
+  - **Type:** Boolean.
+- `accepts-automated-pull-requests` (Required)
+  - **Description:** Define if the maintainers accept pull-requests generated by bots or automated tools.
+  - **Type:** Boolean.
+- `automated-tools-list`
+  - **Description:** List of allowed and denied automated tools and bots. This property can integrate the value `accepts-automated-pull-requests`, according to an automated tool is allowed or denied.
+  - **Type:** Array.
+  - `automated-tool` (Required)
+    - **Description:** The name of the automated tool or bot.
+    - **Type:** String.
+  - `action` (Required)
+    - **Description:** Define if automated actions from a specific tool are allowed or denied.
+    - **Type:** String. The version must match one of the values defined in the field `enum` of the schema.
+  - `path`
+    - **Description:** Provide paths or sub-paths where the automated actions are allowed or denied.
+    - **Type:** Array. Elements of the array are strings.
+  - `comment`
+    - **Description:** Provide additional context or comments.
+    - **Type:** String. At most 560 characters.
+- `contributing-policy`
+  - **Description:** URI to the project contributing policy.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+- `code-of-conduct`
+  - **Description:** URI to the project code of conduct.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+

specification/dependencies.md

@@ -0,0 +1,57 @@
+# Dependencies
+
+The "`dependencies`" section offers an overview of the project's supply chain. It provides information on the sources and policies governing the usage of third-party artifacts, along with insights into their adoption and maintenance. Here, Security Insights consumers can easily access the SBOM file, details about its creation process, and the lifecycle policy for the dependencies.
+
+```yaml
+dependencies:
+  third-party-packages: true
+  dependencies-lists:
+  - https://github.com/foo/packages.json
+  sbom:
+  - sbom-file: https://foo.bar/sbom
+    sbom-format: CycloneDX
+    sbom-url: https://foo.bar
+  dependencies-lifecycle:
+    policy-url: https://example.org
+    comment: |
+      foo bar
+  env-dependencies-policy:
+    policy-url: https://example.org
+    comment: |
+      foo bar
+```
+
+- `third-party-packages`
+  - **Description:** Define if the project uses third-party packages.
+  - **Type:** Boolean.
+- `dependencies-lists`
+  - **Description:** List of URI to the dependencies file (`package.json`, `requirements.txt`, etc) used in the project.
+  - **Type:** Array. Every provided item must be a string that meets the IRI standard (RFC 3987) and begin with `https://`.
+- `sbom`
+  - **Type:** Array.
+  - `sbom-file`
+    - **Description:** URI to the SBOM file.
+    - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+  - `sbom-format`
+    - **Description:** Name of the SBOM standard used (e.g. CycloneDX, SPDX, etc.).
+    - **Type:** String.
+  - `sbom-url`
+    - **Description:** URI to the SBOM standard website or documentation. This can help Security Insights consumers scan or read the SBOM file using the proper tools.
+    - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+  - `sbom-creation`
+    - **Description:** Short description of how the SBOM is created.
+    - **Type:** String. At most 560 characters.
+- `dependencies-lifecycle`
+  - `policy-url`
+    - **Description:** URI to the dependencies lifecycle policy. This information can help the Security Insights consumers to better evaluate the maintenance period and the scheduled end of life for the project.
+    - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+  - `comment`
+    - **Description:** Short comment about the dependencies lifecycle policy, third-party packages updating process, and deprecation process.
+    - **Type:** String. At most 560 characters.
+- `env-dependencies-policy`
+  - `policy-url`
+    - **Description:** URI to environment dependencies policy. This information can help Security Insights consumers know how the project maintainers consume third-party packages.
+    - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+  - `comment`
+    - **Description:** Short comment about how third-party dependencies are adopted and consumed in the different environments (dev, test, prod).
+    - **Type:** String. At most 560 characters.

specification/distribution-points.md

@@ -0,0 +1,12 @@
+# Distribution Points
+
+The "`distribution-points`" section contains a list of PURLs (Package URLs) for official project releases and distributions, managed directly by the project's maintainers. This section assists Security Insights consumers in verifying the source of installed artifacts. This section is **required**.
+
+
+```yaml
+distribution-points:
+  - https://example.com/foo
+  - pkg:npm/foobar
+```
+
+It is an array containing pURLs to the official releases, official released artifacts, or official packages of the project. Every item must be a string.

specification/documentation.md

@@ -0,0 +1,10 @@
+# Documentation
+
+The "`documentation`" section is simply a list of URIs for any kind of documentation that maintainers want to provide to the community (project adopters, contributors, security researchers, etc.).
+
+```yaml
+documentation:
+  - http://foo.bar/wiki
+```
+
+This section is not required. It is an array containing links to the project documentation (docs, wiki, etc.). Every item must be a string that meets the IRI standard (RFC 3987) and begin with `https://`.

specification/header.md

@@ -0,0 +1,44 @@
+# Header
+
+The section "`header`" holds high-level information about the project (e.g. license, changelog) and `SECURITY-INSIGHTS.yml`. This section is **required**.
+
+```yaml
+header:
+  schema-version: 1.0.0
+  expiration-date: '2023-08-31T10:10:09.000Z'
+  last-updated: '2021-09-01'
+  last-reviewed: '2022-09-01'
+  commit-hash: 4dbf78ebc006ee5f668c0a74876ef8d6db9485be
+  project-url: https://github.com/foo/bar
+  project-release: '1.2.0'
+  changelog: https://github.com/foo/changelog.md
+  license: https://git.foo/license
+```
+
+- `schema-version` (Required)
+  - **Description:** Provide the version of the specification that you are adhering to. This information is useful to validate the YAML according to the correct schema version.
+  - **Type:** String. The version must match one of the values defined in the field `enum` of the schema.
+- `expiration-date` (Required) 
+  - **Description:** The date this file should no longer be considered valid, and it can be at most one year from the date it was last reviewed.
+  - **Type:** String. The provided value must be a datetime.
+- `last-updated`
+  - **Description:** The date of the last update to `SECURITY-INSIGHTS.yml`, excluding the properties `commit-hash` and `last-reviewed`.
+  - **Type:** String. The provided value must be a date.
+- `last-reviewed`
+  - **Description:** Date this file was last reviewed by a project maintainer to confirm holistic accuracy.
+  - **Type:** String. The provided value must be a date.
+- `commit-hash`
+  - **Description:** The last commit to which the `SECURITY-INSIGHTS.yml` refers.
+  - **Type:** String. The provided hash must match a SHA hash (`^\b[0-9a-f]{5,40}\b$`).
+- `project-url` (Required)
+  - **Description:** URI for the main project repository that this document refers to.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+- `project-release`
+  - **Description:** The release version or artifact version to which the `SECURITY-INSIGHTS.yml` refers.
+  - **Type:** String.
+- `changelog`
+  - **Description:** URL to the project changelog.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+- `license`
+  - **Description:** URL to the project license.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.

specification/introduction.md

@@ -0,0 +1,19 @@
+## Introduction
+
+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.
+
+Values that are included within the specification may be required or optional. Optional values are reccommendations from the Open Source Security Foundation's _Identifying Security Threats Working Group_, but may not be prudent for all use cases.
+
+Example implementations can be found on the specification's [GitHub repository](https://github.com/ossf/security-insights-spec).
+
+A collection of unofficial supplemental tooling can be found in the ["SI Tooling" GitHub Repository](https://github.com/ossf/si-tooling).
+
+Maintenance for the specification is led by the OpenSSF [Metrics & Metadata working group](https://github.com/ossf/wg-metrics-and-metadata), and improvements are handled exclusively within the project's GitHub repository. Additional information about contribution can be found within the project's [Contribution Policy](/CONTRIBUTING.md).
+
+Improvement suggestions and clarification requests can be logged as [GitHub Issues](https://github.com/ossf/security-insights-spec/issues/new), raised as discussion on [Slack](https://openssf.slack.com/messages/security_insights/), or discussed with the community in the appropriate Working Group meeting from the [OpenSSF Community Calendar](https://calendar.google.com/calendar?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ).
+
+This specification follows semantic versioning. Changes made to the schema on GitHub are considered to be _draft changes_ until a formal release has been made in accordance with the project's [versioning policy](./docs/versioning-policy.md).
+
+Any security-related issues related to the specification or maintenance thereof should follow the recommendations outlined in the project's [security policy](./SECURITY.md).
+
+This specification subject to the Community Specification License 1.0 available at <https://github.com/CommunitySpecification/1.0>.

specification/project-lifecycle.md

@@ -0,0 +1,67 @@
+# Project Lifecycle
+
+The section "`project-lifecycle`" describes the life status of the project by providing information about the project's status - whether it is active or not, the roadmap, release cycle, and contact information. The purpose of this section is to help project adopters evaluate adoption risk and the maintenance status (e.g., whether maintainers are continuing to ship security fixes). This section is **required**.
+
+
+```yaml
+project-lifecycle:
+  status: active
+  roadmap: https://foo.bar/roadmap.html
+  bug-fixes-only: false
+  core-maintainers:
+  - https://github.com/github
+  - [email protected]
+  core-team:
+  - name: Alice White
+    contact: github:example
+  - name: Joe Dohn
+    contact: [email protected]
+  release-cycle: https://foo/release
+  release-process: |
+      foo bar
+```
+
+- `bug-fixes-only` (Required)
+  - **Description:** Provide the maintenance status of the project by specifying if the maintainers fix only bugs without providing new features.
+  - **Type:** Boolean.
+- `core-maintainers`
+  - **Description:** Provide the contacts of the project maintainers (emails, social profiles, websites, etc). This information can help consumers to contact the right people.
+    - [Deprecation notice] _`core-maintainers` will be removed in v1.2.0_
+  - **Type:** Array. Elements of the array are strings.
+- `core-team` (Conditionally required)
+  - **Description:** Provide the contacts of the project maintainers (emails, social profiles, websites, etc) or team (web-pages, group e-mails, mailing list, etc). This information can help consumers to contact the right people.
+  - **Type:** Array.
+  - `name`
+    - **Description:** The name of the maintainer or the team.
+    - **Type:** String.
+  - `role`
+    - **Description:** Role of the maintainer in the project.
+    - **Type:** String.
+  - `contact` (Conditional required)
+    - **Description:** Contact of the maintaner or team (e.g. e-mail, Discord, mailing list, etc).
+    - **Type:** String.
+  - `uri` (Conditional required)
+    - **Description:** URI to the team page or team contact information (e.g. mail form page).
+    - **Type:** String. 
+  - **Condition:** This value `core-team` is required if `bug-fixes-only` is `true` or if `status` is `active`. At least one between `contact` and `uri` is required. 
+- `roadmap`
+  - **Description:** URI to the project roadmap.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+- `release-cycle`
+  - **Description:** URI to the project release cycle.
+  - **Type:** String. The provided URL must meet the IRI standard (RFC 3987) and begin with `https://`.
+- `release-process`
+  - **Description:** Provide a short description for the release process of the process.
+  - **Type:** String. At most 560 characters.
+- `status` (Required)
+  - **Description:** Provide the status of the project. This information can help Security Insights consumers to know if a project is still actively maintained or not. The possible values are inspired by [repostatus.org](https://repostatus.org), and the description of each value below is quoted from the repostatus.org documentation.
+  - **Type:** String. The value must match one of the following values.
+  - **Possible Values:**
+    - Concept – _Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept._
+    - WIP – _Initial development is in progress, but there has not yet been a stable, usable release suitable for the public._
+    - Suspended – _Initial development has started, but there has not yet been a stable, usable release; work has been stopped for the time being but the author(s) intend on resuming work._
+    - Abandoned – _Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development._
+    - Active – _The project has reached a stable, usable state and is being actively developed._
+    - Inactive – _The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows._
+    - Unsupported – _The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired._
+    - Moved - _The project has been moved to a new location, and the version at that location should be considered authoritative. This status should be accompanied by a new URL._

specification/security-artifacts.md

@@ -0,0 +1,65 @@
+# Security Artifacts
+
+The "`security-artifacts`" section provides additional security-focused documentation (e.g., threat model, self-assessment) that project maintainers can share. These documents can help the community to better evaluate the security maturity of the project.
+
+```yaml
+security-artifacts:
+  threat-model:
+    threat-model-created: true
+    evidence-url:
+    - https://foo.com/model.html
+    comment: |
+      foo bar
+  self-assessment:
+    self-assessment-created: true
+    evidence-url:
+    - https://foo.com/assessment.html
+    comment: |
+      foo bar
+  other-artifacts:
+    - artifact-name: example-artifact
+      artifact-created: true
+      evidence-url:
+        - https://foo.com/artifact.html
+      comment: |
+        foo bar
+```
+
+- `threat-model`
+  - `threat-model-created` (Required)
+    - **Description:** Define if a threat model has been created for the project. A false value may be used to add comments regarding the status of the assessment.
+    - **Type:** Boolean.
+  - `evidence-url` (Conditionally required)
+    - **Description:** Evidence of the project threat model.
+    - **Type:** Array. Every provided item must be a string that meets the IRI standard (RFC 3987) and begin with `https://`.
+    - **Condition:** This value is required if `threat-model-created` is `true`.
+  - `comment`
+    - **Description:** Provide shortly additional context to the linked threat model.
+    - **Type:** String. At most 560 characters.
+- `self-assessment`
+  - `self-assessment-created` (Required)
+    - **Description:** Define whether a security self-assessment for the project has been created. A false value may be used to add comments regarding the status of the assessment.
+    - **Type:** Boolean.
+  - `evidence-url` (Conditionally required)
+    - **Description:** Evidence of the self-assessments of the project.
+    - **Type:** Array. Every provided item must be a string that meets the IRI standard (RFC 3987) and begin with `https://`.
+    - **Condition:** This value is required if `self-assessment-created` is `true`.
+  - `comment`
+    - **Description:** Provide shortly additional context to the linked self-assessments.
+    - **Type:** String. At most 560 characters.
+- `other-artifacts`
+  - **Description:** List of other artifacts created for the project.
+  - **Type:** Array.
+    - `artifact-name`
+      - **Description:** Name of the provided artifact.
+      - **Type:** String.
+    - `artifact-created`
+      - **Description:** Define whether an additional artifact for the project has been created. A false value may be used to add comments regarding the status of the assessment.
+      - **Type:** Boolean.
+    - `evidence-url` (Conditionally required)
+      - **Description:** URI to the artifact.
+      - **Type:** Array. Every provided item must be a string that meets the IRI standard (RFC 3987) and begin with `https://`.
+      - **Condition:** This value is required if `artifact-created` is `true`.
+    - `comment`
+      - **Description:** Provide shortly additional context to the linked artifact.
+      - **Type:** String. At most 560 characters.