doc/interoperability/cyclonedx.md

   1 # CycloneDX {#chap-interop-cyclonedx}
   2
   3 [OWASP](https://owasp.org/) [CycloneDX](https://cyclonedx.org/) is a Software [Bill of Materials](https://en.wikipedia.org/wiki/Bill_of_materials) (SBOM) standard.
   4 The standards described here are for including Nix specific information within SBOMs in a way that is interoperable with external SBOM tooling.
   5
   6 ## `nix` Namespace Property Taxonomy  {#sec-interop.cylonedx-nix}
   7
   8 The following tables describe namespaces for [properties](https://cyclonedx.org/docs/1.6/json/#components_items_properties) that may be attached to components within SBOMs.
   9 Component properties are lists of name-value-pairs where values must be strings.
  10 Properties with the same name may appear more than once.
  11 Names and values are case-sensitive.
  12
  13 | Property         | Description |
  14 |------------------|-------------|
  15 | `nix:store_path` | A Nix store path for the given component. This property should be contextualized by additional properties that describe the production of the store path, such as those from the `nix:narinfo:` and `nix:fod` namespaces. |
  16
  17
  18 | Namespace     | Description |
  19 |---------------|-------------|
  20 | [`nix:narinfo`](#sec-interop.cylonedx-narinfo) | Namespace for properties that are specific to how a component is stored as a [Nix archive](https://nixos.org/manual/nix/stable/glossary#gloss-nar) (NAR) in a [binary cache](https://nixos.org/manual/nix/stable/glossary#gloss-binary-cache). |
  21 | [`nix:fod`](#sec-interop.cylonedx-fod) | Namespace for properties that describe a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation). |
  22
  23
  24 ### `nix:narinfo` {#sec-interop.cylonedx-narinfo}
  25
  26 Narinfo properties describe component archives that may be available from binary caches.
  27 The `nix:narinfo` properties should be accompanied by a `nix:store_path` property within the same property list.
  28
  29 | Property                  | Description |
  30 |---------------------------|-------------|
  31 | `nix:narinfo:store_path`  | Store path for the given store component. |
  32 | `nix:narinfo:url`         | URL path component. |
  33 | `nix:narinfo:nar_hash`    | Hash of the file system object part of the component when serialized as a Nix Archive. |
  34 | `nix:narinfo:nar_size`    | Size of the component when serialized as a Nix Archive. |
  35 | `nix:narinfo:compression` | The compression format that component archive is in. |
  36 | `nix:narinfo:file_hash`   | A digest for the compressed component archive itself, as opposed to the data contained within. |
  37 | `nix:narinfo:file_size`   | The size of the compressed component archive itself. |
  38 | `nix:narinfo:deriver`     | The path to the derivation from which this component is produced. |
  39 | `nix:narinfo:system`      | The hardware and software platform on which this component is produced. |
  40 | `nix:narinfo:sig`         | Signatures claiming that this component is what it claims to be. |
  41 | `nix:narinfo:ca`          | Content address of this store object's file system object, used to compute its store path. |
  42 | `nix:narinfo:references`  | A whitespace separated array of store paths that this component references. |
  43
  44 ### `nix:fod` {#sec-interop.cylonedx-fod}
  45
  46 FOD properties describe a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation).
  47 The `nix:fod:method` property is required and must be accompanied by a `nix:store_path` property within the same property list.
  48 All other properties in this namespace are method-specific.
  49 To reproduce the build of a component the `nix:fod:method` value is resolved to an [appropriate function](#chap-pkgs-fetchers) within Nixpkgs whose arguments intersect with the given properties.
  50 When generating `nix:fod` properties the method selected should be a stable function with a minimal number arguments.
  51 For example, the `fetchFromGitHub` is commonly used within Nixpkgs but should be reduced to a call to the function by which it is implemented, `fetchzip`.
  52
  53 | Property         | Description |
  54 |------------------|-------------|
  55 | `nix:fod:method` | Nixpkg function that produces this FOD. Required. Examples: `"fetchzip"`, `"fetchgit"` |
  56 | `nix:fod:name`   | Derivation name, present when method is `"fetchzip"` |
  57 | `nix:fod:ref`    | [Git ref](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefrefaref), present when method is `"fetchgit"` |
  58 | `nix:fod:rev`    | [Git rev](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefrevisionarevision), present when method is `"fetchgit"` |
  59 | `nix:fod:sha256` | FOD hash |
  60 | `nix:fod:url`    | URL to fetch |
  61
  62
  63 `nix:fod` properties may be extracted and evaluated to a derivation using code similar to the following, assuming a fictitious function `filterPropertiesToAttrs`:
  64
  65 ```nix
  66 { pkgs, filterPropertiesToAttrs, properties }:
  67 let
  68   fodProps = filterPropertiesToAttrs "nix:fod:" properties;
  69
  70   methods = {
  71     fetchzip =
  72       { name, url, sha256, ... }:
  73       pkgs.fetchzip {
  74         inherit name url sha256;
  75       };
  76   };
  77
  78 in methods.${fodProps.method} fodProps
  79 ```