[Discussion] Update and complete the specification.

[stupendoussuperpowers]

Refer to the per-section subissues created for updating the spec for v0.3. All discussions pertaining to spec changes should be discussed on these sub-issues. Any filed PRs should use the branch draft-v0.3.0 as the base branch.

The specification.md file on this branch has been updated to reflect this new structure with repurposed content.

specification.md hasn't been updated since July 2023 and is still marked as unstable. This spec hasn't been updated in a while, and in its current state is neither complete nor up-to-date. It's worth revisiting the entire spec as a whole for claims, goals/non-goals, and other policy prescriptions, I'm starting by putting together a todo list of some broader issues I found which can be discussed either here or in breakout issues/PRs)

Unfinished Passages

• 4.2.2 SIT detailed format: TODO….
• 4.1.2 SBOMit Document detailed format: just an embedded image, no schema.
• 2.4 System Workflow Example: image only, no text.
• 5.1.X Add in-toto required evidence and predicateTypes #41 5.1.1: "the layout is required to include certain information such as, …" this is exactly the field list needed for SIT population which just trails off.

Absent forward references

• "ISO or JSON patch format" (2.3, 3.1.3, 4.1.1): JSON Patch (RFC 6902) is real; "ISO patch format" isn't found anywhere.
• Intermediate format "X" (5.1.2): "matches the NTIA format" but no fields ever described.
• TUF integration (1.6.3): claims it's "detailed" but isn't present in this spec.
• "more detailed analysis" backing the threat model (end of 2.2): not present.

Additional Information Required

• (+) 4.1.3: Standard attestation types. (~) 5.1.1 #31: Spec mentions in-toto attestations (2.1.2, 3.1.1) but never specifies which in-toto attestation types/predicates should be standard, and what information these must compulsorily contain. For instance, opened files, spawned processes, and network accesses can be defined either through witness specs or through runtime-trace.
• Evidence to package entry: Specify the path from an opened file to an SBOM document, policy on evidence that can't be attributed to a package, how we reconcile SCA-scanner data, and other details. (Not exact algorithmic details but at least higher level guarantees/assumptions should be ideally listed?)
• 2.2 asserts strong security properties per attacker class and points to "a more detailed analysis that shows why these properties hold". This analysis isn't linked or present anywhere.