Feed Hierarchy and Properties

SCITT defines a feed as:

an identifier chosen by the Issuer for the Artifact. For every Issuer and Feed, the Registry on a Transparency Service contains a sequence of Signed Statements about the same Artifact. In COSE, Feed is a dedicated header attribute in the protected header of the Envelope.

To provide more structure, we have a tracking issue: Refine Definition of Feed #11

This document outlines a potential structure for feeds, enabling submissions and queries around a specific platform and version of an artifact.

Although these may be header properties, rather than a hierarchical structure.

The proposed structure provides:

• For each platform/architecture a series of compatible versions are released.
• For each version, a series of statements are made.
• Statements for a specific platform/architecture and version would not apply to another platform/architecture and version.
• Each variant must be treated uniquely.

 .---------------.
| feed identifier |
 '----+----------'
      |  .---------------------.
      |'+ platform/architecture |
      |  '-+-------------------'
      |    |  .-------.
      |     '+ version |
      |       '-+-----'
      |         |  .-----------.
      |          '+ sub-version |
      |            '-+---------'
      |              |  +-------------+
      |               '-+ contentType |
      |                 +-------------+
      |  .---------------------.
       '+ platform/architecture |
         '-+-------------------'
           |  .-------.
            '+ version |
              '-+-----'
                |  .-----------.
                 '+ sub-version |
                   '-+---------'
                     |  +-------------+
                      '-+ contentType |
                        +-------------+

There's an intentional structure as the consumer of the netlog:v8 package running on linux/amd64 server has no need to query information about the mac (darwin/amd64) version.
The ability to query for updates to a specific versioned package on a specific platform/architecture enables a consumer to target just what they need.

 .-----------.
| net-monitor |
 '----+------'
      |   .------------.
      |'-+ darwin/amd64 |
      |   '-+----------'
      |     |   .--.
      |      '-+ v1 |
      |         '-+'
      |           |   .----.
      |            '-+ v1.1 |
      |               '-+--'
      |                 |  +-------+
      |                  '-+ ctype |
      |                    +-------+
      |
      |   .-----------.
      |'-+ linux/amd64 |
      |   '-+---------'
      |     |   .--.
      |      '-+ v1 |
      |         '-+'
      |           |   .----.
      |            '-+ v1.1 |
      |               '-+--'
      |                 |  +----------------------------------+
      |                 |'-+ ctype: example/sbom              |
      |                 |  | created: 2023-01-01T16:00:00.00Z |
      |                 |  +----------------------------------+
      |                 |
      |                 |  +----------------------------------+
      |                 |'-+ ctype: example/scan-result       |
      |                 |  | created: 2023-01-01T16:00:00.00Z |
      |                 |  +----------------------------------+
      |                 |
      |                 |  +----------------------------------+
      |                  '-+ ctype: example/scan-result       |
      |                    | created: 2023-01-03T10:30:00.00Z |
      |                    +----------------------------------+
      |
      |   .--------------.
       '-+ linux/arm64/v8 |
          '-+------------'
            |  .--.
            '-+ v1 |
               '-+'
                 |  +----------------------------------+
                  '-+ ctype: example/sbom              |
                    | created: 2023-01-03T10:30:00.00Z |
                    +----------------------------------+

Multiple Content Types Issued by Multiple Identities

For each version of a platform/architecture package, a series of statements may be made.
Note that the same statement (content type) may be made by different identities (issuers), or updated statements may be made as new information is discovered.

net-monitor
└─ linux/amd64
   └─── v1

Issuer	Type	Time Created
wabbit-networks	SPDX SBOM	2023-01-01T16:00:00.00Z
wabbit-networks	CycloneDX SBOM	2023-01-01T16:00:00.00Z
wabbit-networks	SDL Compliance	2023-01-01T16:00:00.00Z
wabbit-networks	Provenance	2023-01-01T16:00:00.00Z
wabbit-networks	GitBom	2023-01-01T16:00:00.00Z
cogswell-defender	Scan Result	2023-01-01T16:00:00.00Z
cogswell-defender	Scan Result	2023-01-03T10:30:00.00Z
cogswell-defender	Scan Result	…
clair	Scan Result	2023-04-01T18:30:00.00Z
cogswell-defender	Scan Result	2023-04-02T17:00:00.00Z
wabbit-networks	Patch Version Notification	2023-04-03T15:30:00.00Z
clair	Scan Result	2023-04-03T18:00:00.00Z
cogswell-defender	Scan Result	2023-04-03T18:00:00.00Z

Conceptual Feeds

A feed is a resource, identified by a URL.

Resources can be expressed in multiple content types.

application/scitt.feed+cbor is mandatory to support.

scitt.feed+cbor encodes a structure for paging a potentially infinite list.

Although these examples are YAML the actual representation would be CBOR.

Generic example, a feed identifies a list of receipts.

GET https://ts.example/feeds/42 –accept application/yaml

# todo paging...
items:
 - id: https://ts.example/signed-statements/receipts/0
   
   # consider the feed to be of receupts for artifacts that have been signed with cose sign1    
   # contentId: https://vendor.example/packages/cool-software/sbom/receipt
   contentType: application/scitt.receipt+cbor
   content: base64url encoded receipt (`application/scitt.receipt+cbor`)

   # consider that implementations might augment responses with artifacts by reference or by value. 
   # payloadId: https://vendor.example/packages/cool-software/sbom
   # payloadType: application/spdx+json
   # payload: base64url encoded payload

 - id: https://ts.example/signed-statements/receipts/1

Slightly more structure…

A feed exposes a list of receipts, filtered to specific elements.

GET https://ts.example/feeds/by-payload-content-type/application/spdx+json
GET https://ts.example/feeds/by-signed-statement-issuer/did:vendor.example:ci-server:53
GET https://ts.example/feeds/by-purl/pkg:docker/debian@sha256:2f04d3d33b6027bb74ecc81397abe780649ec89f1a2af18d7022737d0482cefe

Non software domain examples:

GET https://ts.example/feeds/facility/geohash
GET https://ts.example/feeds/facility/geohash/imports
GET https://ts.example/feeds/facility/geohash/exports

GET https://ts.example/feeds/address/tokens
GET https://ts.example/feeds/address/transactions

GET https://ts.example/feeds/physical-address/insurance-policies
GET https://ts.example/feeds/human-identifier/insurance-policies

GET https://ts.example/feeds/vehicle-identifier/titles
GET https://ts.example/feeds/vehicle-identifier/insurance
GET https://ts.example/feeds/vehicle-identifier/speeding-tickets

Seems there are actually 2 concepts hidden in 1 here…

"Feed" as a topic committed to by the issuer of the receipt.

For example application/spdx+json for pkg:docker/debian@sha256:2f04d3d33b6027bb74ecc81397abe780649ec89f1a2af18d7022737d0482cefe by docker.transparency.example

^ You will see the Feed for the first case in a COSE Sign1 protected header.

"Feed" as an aggregation over witnessed receipts related to "various related topics"

For example "all the receipts" for pkg:docker/debian@sha256 (any hash, all content types) by docker.transparency.example.

^ You won't ever see the Feed for the second case in a COSE Sign1 protected header.