OSPS-DO.yaml

groups:
  - id: DO
    title: Documentation
    description: |
      Documentation focuses on the information
      provided to users, contributors, and maintainers
      of the project. These controls help ensure that
      the project's documentation is comprehensive,
      accurate, and up-to-date, enabling users to
      understand the project's features and functionality, maintenance, support,
      security and release practices.
controls:
  - id: OSPS-DO-01
    title: |
      Publish User Guides for Basic Functionality
    objective: |
      Ensure that users have a clear and comprehensive understanding of the
      project's current features in order to prevent damage from misuse or
      misconfiguration.
    group: DO
    guidelines:
      - reference-id: BPB
        entries:
          - reference-id: B-B-1
          - reference-id: B-B-9
          - reference-id: B-S-7
          - reference-id: B-S-9
      - reference-id: CRA
        entries:
          - reference-id: 1.2b
          - reference-id: 1.2j
          - reference-id: 1.2k
      - reference-id: SSDF
        entries:
          - reference-id: PW.1.2
      - reference-id: CSF
        entries:
          - reference-id: GV.OC-04
          - reference-id: GV.OC-05
      - reference-id: ISO-18974
        entries:
          - reference-id: 4.1.4
      - reference-id: OpenCRE
        entries:
          - reference-id: 036-275
      - reference-id: PSSCRM
        entries:
          - reference-id: G5.1
          - reference-id: E3.5
      - reference-id: PCIDSS
        entries:
          - reference-id: 2.1.1
          - reference-id: 2.2.1
          - reference-id: 3.1.1
          - reference-id: 4.1.1
          - reference-id: 5.1.1
          - reference-id: 6.1.1
          - reference-id: 6.2.1
          - reference-id: 7.1.1
          - reference-id: 8.1.1
          - reference-id: 11.1.1
          - reference-id: 12.10.5
      - reference-id: UKSSCOP
        entries:
          - reference-id: 4.1
      - reference-id: 800-161
        entries:
          - reference-id: CM-2
          - reference-id: PL-2
          - reference-id: PL-8
          - reference-id: SA-15
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: BR.01          
    assessment-requirements:
      - id: OSPS-DO-01.01
        text: |
          When the project has made a release, the project documentation MUST
          include user guides for all basic functionality.
        applicability:
          - maturity-1
          - maturity-2
          - maturity-3
        recommendation: |
          Create user guides or documentation for all basic functionality of the
          project, explaining how to install, configure, and use the project's
          features. If there are any known dangerous or destructive actions
          available, include highly-visible warnings.

  - id: OSPS-DO-02
    title: |
      Provide Mechanisms for Reporting Defects
    objective: |
      Enable users and contributors to report defects or issues with the
      released software assets, facilitating communication and collaboration on
      defect fixes and improvements.
    group: DO
    guidelines:
      - reference-id: BPB
        entries:
          - reference-id: B-B-3
          - reference-id: R-B-1+
          - reference-id: R-B-1
          - reference-id: R-B-2
          - reference-id: R-S-2
      - reference-id: CRA
        entries:
          - reference-id: 1.2c
          - reference-id: 1.2l
          - reference-id: 2.1
          - reference-id: 2.2
          - reference-id: 2.5
          - reference-id: 2.6
      - reference-id: SSDF
        entries:
          - reference-id: PW.1.2
          - reference-id: RV.1.1
          - reference-id: RV.2.1
          - reference-id: RV.1.2
      - reference-id: CSF
        entries:
          - reference-id: RS.MA-02
          - reference-id: GV.RM-05
      - reference-id: ISO-18974
        entries:
          - reference-id: 4.2.1
      - reference-id: SAMM
        entries:
          - reference-id: Implementation -Defect Management -Defect Tracking Lvl1
          - reference-id: Implementation -Defect Management -Defect Tracking Lvl2
      - reference-id: PCIDSS
        entries:
          - reference-id: 6.3.2
          - reference-id: 6.3.3
          - reference-id: 6.5.1
          - reference-id: 6.5.2
          - reference-id: 12.10.2
      - reference-id: UKSSCOP
        entries:
          - reference-id: 1.1
          - reference-id: 1.3
      - reference-id: 800-161
        entries:
          - reference-id: IR-6
          - reference-id: SI-4
          - reference-id: SI-5          
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: QA.03
    assessment-requirements:
      - id: OSPS-DO-02.01
        text: |
          When the project has made a release, the project documentation MUST
          include a guide for reporting defects.
        applicability:
          - maturity-1
          - maturity-2
          - maturity-3
        recommendation: |
          It is recommended that projects use their VCS default issue tracker.
          If an external source is used, ensure that the project documentation
          and contributing guide clearly and visibly explain how to use the
          reporting system. It is recommended that project documentation also
          sets expectations for how defects will be triaged and resolved.

  - id: OSPS-DO-03
    title: |
      Publish Provenance Verification Instructions
    objective: |
      Enable users to verify the authenticity and integrity of the project's
      released software assets, reducing the risk of using tampered or
      unauthorized versions of the software.
    group: DO
    guidelines:
      - reference-id: BPB
        entries:
          - reference-id: CC-B-8
      - reference-id: CRA
        entries:
          - reference-id: 1.2d
      - reference-id: SSDF
        entries:
          - reference-id: PO.4.2
          - reference-id: PS.2
          - reference-id: PS.2.1
          - reference-id: PS.3.1
          - reference-id: RV.1.3
      - reference-id: OpenCRE
        entries:
          - reference-id: 171-222
      - reference-id: PSSCRM
        entries:
          - reference-id: G1.3
          - reference-id: G2.5
          - reference-id: P1.2
          - reference-id: P3.1
          - reference-id: P3.2
          - reference-id: P3.3
          - reference-id: E2.6
      - reference-id: PCIDSS
        entries:
          - reference-id: 3.1.1
          - reference-id: 3.5.1
          - reference-id: 4.1.1
          - reference-id: 5.1.1
          - reference-id: 6.1.1
          - reference-id: 6.2.1
          - reference-id: 7.1.1
          - reference-id: 8.1.1
          - reference-id: 11.1.1
      - reference-id: UKSSCOP
        entries:
          - reference-id: 3.1
      - reference-id: 800-161
        entries:
          - reference-id: CM-2
          - reference-id: IR-1
          - reference-id: MP-1
          - reference-id: SA-15
          - reference-id: SI-7
          - reference-id: SI-7(14)          
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: BR.01
          - reference-id: BR.03          
    assessment-requirements:
      - id: OSPS-DO-03.01
        text: |
          When the project has made a release, the project documentation MUST
          contain instructions to verify the integrity and authenticity of the
          release assets.
        applicability:
          - maturity-3
        recommendation: |
          Instructions in the project should contain information about the
          technology used, the commands to run, and the expected output.
          When possible, avoid storing this documentation in the same location
          as the build and release pipeline to avoid a single breach
          compromising both the software and the documentation for verifying the
          integrity of the software.
      - id: OSPS-DO-03.02
        text: |
          When the project has made a release, the project documentation MUST
          contain instructions to verify the expected identity of the person or
          process authoring the software release.
        applicability:
          - maturity-3
        recommendation: |
          The expected identity may be in the form of key IDs used to sign,
          issuer and identity from a sigstore certificate, or other similar
          forms.
          When possible, avoid storing this documentation in the same location
          as the build and release pipeline to avoid a single breach
          compromising both the software and the documentation for verifying the
          integrity of the software.

  - id: OSPS-DO-04
    title: |
      Publish Support Scope and Duration
    objective: |
      Provide users with clear expectations regarding the project's support
      lifecycle in such a way that enables downstream consumers to ensure the
      continued functionality and security of their systems.
    group: DO
    guidelines:
      - reference-id: BPB
        entries:
          - reference-id: R-B-3
      - reference-id: SSDF
        entries:
          - reference-id: PO.4.2
          - reference-id: PS.3.1
          - reference-id: RV.1.3
      - reference-id: ISO-18974
        entries:
          - reference-id: 4.1
          - reference-id: 4.3.1
      - reference-id: PSSCRM
        entries:
          - reference-id: E1.6
      - reference-id: SAMM
        entries:
          - reference-id: Operations -Operational Management -System Decommissioning -Legacy Management Lvl1
      - reference-id: PCIDSS
        entries:
          - reference-id: 2.1.1
          - reference-id: 3.1.1
          - reference-id: 3.2.1
          - reference-id: 4.1.1
          - reference-id: 5.1.1
          - reference-id: 6.1.1
          - reference-id: 6.3.3
          - reference-id: 7.1.1
          - reference-id: 8.1.1
          - reference-id: 11.1.1
      - reference-id: UKSSCOP
        entries:
          - reference-id: 4.1
          - reference-id: 4.2
      - reference-id: 800-161
        entries:
          - reference-id: PL-1
          - reference-id: PL-2
          - reference-id: SI-4          
      - reference-id: UKSSCOP
        entries:
          - reference-id: Claim 4.1.1
          - reference-id: Claim 4.1.2
          - reference-id: Claim 4.2.1
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: DE.01       
    assessment-requirements:
      - id: OSPS-DO-04.01
        text: |
          When the project has made a release, the project documentation MUST
          include a descriptive statement about the scope and duration of
          support for each release.
        applicability:
          - maturity-3
        recommendation: |
          In order to communicate the scope and duration of support for the
          project's released software assets, the project should have a
          SUPPORT.md file, a "Support" section in SECURITY.md, or
          other documentation explaining the support lifecycle,
          including the expected duration of support for each release, the
          types of support provided (e.g., bug fixes, security updates), and
          any relevant policies or procedures for obtaining support.

  - id: OSPS-DO-05
    title: |
      Document Security Update Scope and Duration
    objective: |
      Communicate when the project maintainers will no longer fix defects or
      security vulnerabilities.
    group: DO
    guidelines:
      - reference-id: CRA
        entries:
          - reference-id: 1.2c
          - reference-id: 2.6
      - reference-id: ISO-18974
        entries:
          - reference-id: 4.1.1
          - reference-id: 4.3.1
      - reference-id: OpenCRE
        entries:
          - reference-id: 673-475
          - reference-id: 053-751
      - reference-id: PSSCRM
        entries:
          - reference-id: E1.6
      - reference-id: SAMM
        entries:
          - reference-id: Operations -Operational Management -System Decommissioning -Legacy Management Lvl1
          - reference-id: Operations -Operational Management -System Decommissioning -Legacy Management Lvl2
      - reference-id: PCIDSS
        entries:
          - reference-id: 3.1.1
          - reference-id: 3.2.1
          - reference-id: 4.1.1
          - reference-id: 5.1.1
          - reference-id: 6.1.1
          - reference-id: 6.3.2
          - reference-id: 7.1.1
          - reference-id: 8.1.1
          - reference-id: 11.1.1
      - reference-id: UKSSCOP
        entries:
          - reference-id: 3.5
          - reference-id: 4.1
      - reference-id: 800-161
        entries:
          - reference-id: PL-1
          - reference-id: PL-2
          - reference-id: SI-4
          - reference-id: SI-5          
      - reference-id: UKSSCOP
        entries:
          - reference-id: Claim 4.1.1
          - reference-id: Claim 4.2.1
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: DE.01        
    assessment-requirements:
      - id: OSPS-DO-05.01
        text: |
          When the project has made a release, the project documentation MUST
          provide a descriptive statement when releases or versions will no
          longer receive security updates.
        applicability:
          - maturity-3
        recommendation: |
          In order to communicate the scope and duration of support for security
          fixes, the project should have a SUPPORT.md or other documentation
          explaining the project's policy for security updates.

  - id: OSPS-DO-06
    title: |
      Publish Dependency Management Policy
    objective: |
      Provide information about how the project selects, obtains, and tracks
      third-party components that are required for the software to function.
    group: DO
    guidelines:
      - reference-id: BPB
        entries:
          - reference-id: A-S-1
      - reference-id: CRA
        entries:
          - reference-id: 2.1
      - reference-id: OpenCRE
        entries:
          - reference-id: 613-286
          - reference-id: 053-751
      - reference-id: Scorecard
        entries:
          - reference-id: Pinned-Dependencies
      - reference-id: PSSCRM
        entries:
          - reference-id: G1.4
          - reference-id: G2.4
          - reference-id: P3.1
          - reference-id: P3.2
          - reference-id: P3.4
      - reference-id: SAMM
        entries:
          - reference-id: Design -Security Requirements -Supplier Security Lvl2
      - reference-id: PCIDSS
        entries:
          - reference-id: 2.1.1
          - reference-id: 3.1.1
          - reference-id: 4.1.1
          - reference-id: 5.1.1
          - reference-id: 6.1.1
          - reference-id: 6.3.2
          - reference-id: 6.4.3
          - reference-id: 7.1.1
          - reference-id: 8.1.1
          - reference-id: 11.1.1
          - reference-id: 12.5.2
      - reference-id: UKSSCOP
        entries:
          - reference-id: 1.2
          - reference-id: 3.3
      - reference-id: 800-161
        entries:
          - reference-id: CA-7
          - reference-id: CM-7(5)
          - reference-id: CM-8
          - reference-id: PM-30
          - reference-id: RA-3(1)
          - reference-id: SA-11
          - reference-id: SI-4
          - reference-id: SR-3
          - reference-id: SR-5
          - reference-id: SR-6
          - reference-id: SR-7          
      - reference-id: UKSSCOP
        entries:
          - reference-id: Claim 1.2.1
          - reference-id: Claim 1.2.2
      - reference-id: BSI-TR-03185-2
        entries:
          - reference-id: QA.01
    assessment-requirements:
      - id: OSPS-DO-06.01
        text: |
          When the project has made a release, the project documentation MUST
          include a description of how the project selects, obtains, and tracks
          its dependencies.
        applicability:
          - maturity-2
          - maturity-3
        recommendation: |
          It is recommended to publish this information alongside the project's
          technical & design documentation on a publicly viewable resource such
          as the source code repository, project website, or other channel.  
        
  - id: OSPS-DO-07
    title: |
      Provide Instructions on How to Build From Source
    objective: |
      Ensure that users have a clear and comprehensive instructions on how
      to build the software from source code.
    group: DO
    guidelines:
      - reference-id: 
        entries:
          - reference-id:
    assessment-requirements:
      - id: OSPS-DO-07.01
        text: |
          The project documentation MUST
          include instructions on how to build the software, including required
          libraries, frameworks, SDKs, and dependencies.
        applicability:
          - maturity-2
          - maturity-3
        recommendation: |
          It is recommended to publish this information alongside the project's
          contributor documentation, such as in `CONTRIBUTING.md` or other
          developer task documentation. This may also be documented using
          `Makefile` targets or other automation scripts.