v2 Proposal

[jmeridth]

Following a working session with @eddie-knight, I'd like to propose this restructuring of the security insights specification. This groups similar things and reduces redundant prefixing.

Details

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
  license: https://git.foo/license

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

supply-chain:
  third-party-packages: true
  lists:
    - https://github.com/foo/packages.json
  latest-sbom:
    - url: https://foo.bar/sbom
      format: CycloneDX
    - url: https://foo.bar/sbom2
      format: spdx
  lifecycle:
    url: https://example.org
    comment: |
      foo bar
  policy:
    url: https://example.org
    comment: |
      foo bar

lifecycle:
  status: active
  roadmap: https://foo.bar/roadmap.html
  bug-fixes-only: false
  release:
    cycle: https://foo/release
    process: |
      foo bar
  distribution-points:
    - https://example.com/foo
    - pkg:npm/foobar
  latest-release:
    url: https://foo.bar/release
    name: '1.2.0'
    date: '2021-09-01'
    changelog: https://github.com/foo/changelog.md

development:
  documentation:
    - http://foo.bar/wiki
  core-team:
    - name: Alice White
      contact: github:example
    - name: Joe Dohn
      contact: [email protected]
  security-testing:
    - tool-type: sca
      tool-name: Dependabot
      tool-version: 1.2.3
      tool-url: https://example.org
      tool-rulesets:
        - built-in
      integration:
        ad-hoc: false
        ci: true
        before-release: true
      comment: |
        foo bar
  security-contacts:
    - type: email
      value: [email protected]
      primary: true
    - type: email
      value: [email protected]
      primary: false

security-artifacts:
  self-assessment:
    evidence-url: https://foo.com/assessment.html
    comment: |
      foo bar
  third-party-assessments:
    - name: example-artifact
      evidence-url: https://foo.com/artifact.html
      date: '2021-09-01'
      comment: |
        foo bar

vulnerability-reporting:
  accepts-vulnerability-reports: true
  email-contact: [email protected]
  security-policy: https://foo.bar/reporting.html
  bug-bounty-available: true
  bug-bounty-url: https://foo.bar/bugs.html
  in-scope:
    - broken access control
    - other
  out-scope:
    - other
  pgp-key: |
    your-key-here
  comment: |
    Lorum ipsum...

[eddie-knight]

Thanks for capturing this @jmeridth! I'll look at integrating this with #93 as well for the upcoming changes.

[eddie-knight]

Here's what I came up with after going back through the OSPS baseline and as the suggestions from #93.

Some fields are removed or renamed, and others are entirely new.

Would appreciate feedback if anyone has suggestions for improvement.

Click to expand

# r = required

header: # r
  schema-version: 1.0.0  # r
  last-updated: '2021-09-01' # r
  last-reviewed: '2022-09-01' # r
  repo-url: https://foo.bar # r
  repo-status: active # r

project: # r
  name: Foo # r
  roadmap: https://foo.bar/roadmap.html
  homepage-url: https://foo.bar # r
  administrators: # r
    - name: Joe Dohn # r
      employer: Foo # r
      contact: [email protected] # r
  documentation:
    user-guide: https://foo.bar/user-guide
    code-of-conduct: https://example.com/code-of-conduct.html
    release-process: https://foo.bar/release-process
    provenance-verification: https://foo.bar/provenance-verification
    governance: https://foo.bar/governance
  release:
    automated-pipeline: true
    CPE: cpe:2.3:a:foo:bar:1.2.0
    distribution-points:
      - https://example.com/foo
      - pkg:npm/foobar
    latest:
      url: https://foo.bar/release
      name: '1.2.0'
      date: '2021-09-01'
      changelog: https://foo.bar/changelog.md
      license:
        url: https://foo.bar/license
        expression: MIT AND Apache-2.0
      sbom:
        - url: https://foo.bar/sbom1
          format: cyclonedx
        - url: https://foo.bar/sbom2
          format: spdx
      provenance:
        cryptography:
          attestation: https://foo.bar/attestation
          algorithm: sha256
        vex-data: https://foo.bar/vex
        hash-manifest: https://foo.bar/hash-manifest
  subprojects:
    - name: bar
      url: https://foo.bar/foo
      comment: |
        Bar is a subproject that is built into Foo to accomplish foobar.
  vulnerability-reporting: # r
    accepts-vulnerability-reports: true # r
    email-contact: [email protected]
    security-policy: https://foo.bar/reporting.html
    bug-bounty-available: true
    bug-bounty-url: https://foo.bar/bugs.html
    in-scope:
      - broken access control
      - other
    out-scope:
      - other
    pgp-key: |
      your-key-here
    comment: |
      Lorum ipsum...
  security: # r
    artifacts: # r
      self-assessment: # r
        evidence-url: https://foo.com/assessment.html
        comment: | # r
          foo bar
      third-party-assessments:
        - name: example-artifact
          evidence-url: https://foo.com/artifact.html
          date: '2021-09-01'
          comment: |
            foo bar
    contacts:
      - type: email
        value: [email protected]
        primary: true
      - type: email
        value: [email protected]
        primary: false
    testing:
      - tool-type: sca
        tool-name: Dependabot
        tool-version: 1.2.3
        tool-url: https://example.org
        tool-rulesets:
          - built-in
        integration:
          ad-hoc: false
          ci: true
          before-release: true
        comment: |
          foo bar

repository: # r
  bug-fixes-only: false # r
  accepts-change-request: true # r
  accepts-automated-change-request: true # r
  automated-tools:
    - automated-tool: example/security-research
      action: denied
      path:
        - main/foo/bar
        - main/examples
      comment: |
        foo bar
  core-team: # r
    - name: Alice White # r
      contact: email, social, github, etc # r
  documentation:
    contributing-guide: https://foo.bar/contributing-guide
    review-policy: https://foo.bar/review-policy
    security-policy: https://example.com/security-policy.html
  license: # r
    url: https://foo.bar/LICENSE # r
    expresion: MIT # r
  security: # r
    artifacts: # r
      self-assessment: # r
        evidence-url: https://foo.com/assessment.html
        comment: |
          foo bar
      third-party-assessments:
        - name: example-artifact
          evidence-url: https://foo.bar/artifact.html
          date: '2021-09-01'
          comment: |
            foo bar
    champions:
      - type: email
        value: [email protected]
        primary: true
    testing:
      - tool-type: sca
        tool-name: Dependabot
        tool-version: 1.2.3
        tool-url: https://example.org
        tool-rulesets:
          - built-in
        integration:
          ad-hoc: false
          ci: true
          before-release: true
        comment: |
          foo bar
  supply-chain: 
    third-party-packages: true
    lists:
      - https://foo.bar/packages.json
    management-policy:
      url: https://foo.bar/dependency-management-policy
      comment: |
        foo bar

cc/ @mlieberman85 @funnelfiasco @puerco @david-a-wheeler @jmeridth

[eddie-knight]

I've applied the cleanup suggestions here and then added feedback from all of the previous PRs into #96.

That PR also has a CI check to validate the Cue schema on PR.

I'm beginning to work on documentation updates now as well.

[mlieberman85]

(Some of my below comments are based on having a human created SECURITY-INSIGHTS.yml that exists in the repo as it's used today.)

My worry about some of the above here is that it conflates static information with dynamic information. For example:

latest-sbom:
    - url: https://foo.bar/sbom
      format: CycloneDX
    - url: https://foo.bar/sbom2
      format: spdx

This means that the security-insights file would need to update every single time there's a new SBOM. If it doesn't it becomes impossible to differentiate two separate releases' SBOMs.

I personally think something like security insights should be more of an API, e.g. how github allows you to label things with what attestation they are allowing the end user to pull information regarding a particular release, where something like security insights would be a report, e.g. "this release when created had these properties." As it stands there's still a lot of ambiguity.

[puerco]

Somewhat related to @mlieberman85's comments above, my feeling is that SI should only act as the glue that binds together the data and artifacts that automated tools can't easily find today. One located, the specialized formats should take over. For example:

        - url: https://foo.bar/sbom2
          format: spdx

I assume this is pointing to the SBOM itself, we are still in Mike's scenario above. Instead of individual links, SI should define a pointer to look for the documents. Having written lots of SBOM tools, the most difficult part is knowing where to look for the documents: Is it published in the GitHub releases? Is it in a bucket? Fetch it from a URL? What's the naming convention?

To answer those questions, SI should define a fixed locator to retrieve the data. For example, these URL templates point to all the Kubernetes SBOMs since the first pair was published:

https://sbom.k8s.io/{version}/release
https://sbom.k8s.io/{version}/source

This approach should be enough for some of the other metadata and evidence about some of the above entries.

[puerco]

Another suggestion, SI should have a unified data structure for common types. For example, having two data structures to describe a person is problematic:

  administrators: # r
    - name: Joe Dohn # r
      employer: Foo # r
      contact: [email protected] # r
...
  contacts:
    - type: email
      value: [email protected]
      primary: true

[eddie-knight]

Just pushed up a commit to #96 that incorporates the suggestions above into the template, along with some elements that @puerco and I just worked on together via zoom. I'm still working on updating the schema and docs accordingly, but I'm quite happy with the direction this is going. Thanks y'all.

[eddie-knight]

#96 is now merged! I've opened Issue #97 to discuss any pending work related to the upcoming release.

Thanks for the nudge on this @jmeridth! We've made some great progress here.