From 2af57908a304e5f6cb9b96922dd132ad72f661ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adolfo=20Garc=C3=ADa=20Veytia=20=28Puerco=29?= Date: Wed, 17 Aug 2022 00:36:24 -0500 Subject: [PATCH] add spec to reference designs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Adolfo García Veytia (Puerco) --- semantics/oci-image.md | 54 +++++++++++++++++++++++++++++++- semantics/oci-layer.md | 24 ++++++++++++++ semantics/oci-multiarch-index.md | 25 +++++++++++++-- 3 files changed, 99 insertions(+), 4 deletions(-) diff --git a/semantics/oci-image.md b/semantics/oci-image.md index a490caa..a5e9af6 100644 --- a/semantics/oci-image.md +++ b/semantics/oci-image.md @@ -62,4 +62,56 @@ class SourceCode { Image --> Layer2: CONTAINS Image --> Layer3: CONTAINS -``` \ No newline at end of file +``` + +## Design Specification + +The goal of this design is to allow maximum flexibility when adding metadata +to the image components. + +### Package Structure + +The top level package represents the container image and references its manifest. +The name of the package should be the digest of the image manifest, preceded as +usual by the algorithm, eg `sha256:923784e51e709f...`. + +The image package can con contain three types of packages: + +#### Container Layer + +Each of the image layers hould be represented in a package. Ideally, the image +SBOM should describe the whole container image structure. Just as the image, +layers should also be named using their digests. The can layer can contain a +purl of type OCI to reference it. + +#### Base Image + +Images often are derived from other images. When the described image uses as a +base another image, the SBOM can reference it using a package. In order to ensure +that tools can discern the base image from other OCI artifacts, the base image +package should be related to the image via a `DESCENDANT_OF` relationship. + +#### Source Package + +The SBOM describing the image should also reference the VCS URL where the source +to build the image lives. To describe the build code, the image SBOM should have +a package pointing to the source repository. This package should be related to the +image package using a `GENERATED_FROM` relationship. + +### Software Identifiers + +The image package, the layers and the base image should contain external references +to the OCI artifacts using purls. The purl should of type [`oci`](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#oci) and does not require adding data about the registry, +repository or tags (but it may). WHen including os/arch metadata in the purl, only +the image should have it. + +The source code package should include a pointer to the repository containing the +code that generated the image. + +**Note:** This is not a reference to the application source code, it is a reference +to the code that was used to build the image (eg its Dockerfile). + +The purl referncing the source repository should be of type [github](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#github) if the code lives there. Check for other +suitable types if the source is not hosted in GitHub. + + diff --git a/semantics/oci-layer.md b/semantics/oci-layer.md index 8f80e5e..2523eba 100644 --- a/semantics/oci-layer.md +++ b/semantics/oci-layer.md @@ -35,3 +35,27 @@ Layer --> busybox: CONTAINS Layer --> cacertificatesbundle: CONTAINS ``` +## Design Specification + +The goal of this design is to allow maximum flexibility when adding metadata +to the layer package. Generally, a layer abstracts a filesystem so it can +potentially contain anything. This is why the layer abstraction should have +room for current and unexpected uses. + +### Package Structure + +The package in this design represents a layer in a container image. Separating the +layers into their own packages ensures that adding data about packages can be added +to the appropiate section of the SBOM. For example, a layer can express an added file +via a `curl` pull while another can add child packages detailing the installed OS +dependencies. + +Things inside of images should be added as SPDX Packages and Files and related using a +CONTAINS relationship. + +### Software Identifiers + +The package representing a layer should have a purl of type `oci` referencing the +layer in a registry-neutral way. No os/arch data needs be added to the purl as +the layer will mostl likely live under an image SBOM which should include the platform +info. diff --git a/semantics/oci-multiarch-index.md b/semantics/oci-multiarch-index.md index b8fd98d..744565c 100644 --- a/semantics/oci-multiarch-index.md +++ b/semantics/oci-multiarch-index.md @@ -14,14 +14,13 @@ in the purl external reference. ## Structure Diagram - ```mermaid classDiagram direction LR class ImageIndex{ - PackageName: sha256:923784 + PackageName: sha256:923784e51e709f ExternalRef: PACKAGE_MANAGER purl pkg:oci/alpine@sha256:923[...] - PackageChecksum: SHA256 923784 + PackageChecksum: SHA256 923784e51e709f } class Image{ PackageName: sha256:5fbbc2112ee51e709f374c9c01e @@ -37,3 +36,23 @@ class Image2 { ImageIndex --> Image: VARIANT_OF ImageIndex --> Image2: VARIANT_OF ``` + +## Design Specification + +### Package Structure + +The top level package represents the image index. The name of the package should be +the digest of its manifest, preceded as usual by the algorithm, +eg `sha256:923784e51e709f...`. + +Each container image fronted by the image must be represented by another package, also +named as its digest. Each of these packages should be related to the index using a +`VARIANT_OF` SPDX relationship. + +### Software Identifiers + +Each of the packages in this design should contain a reference to the OCI object using +a [purl of type `oci`](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#oci). +Packages representing the single arch images must contain the os/arch metadata and optionally +can add tag and repository metadata. +