pyrox.dev
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.
4The 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
8The following tables describe namespaces for [properties](https://cyclonedx.org/docs/1.6/json/#components_items_properties) that may be attached to components within SBOMs.
9Component properties are lists of name-value-pairs where values must be strings.
10Properties with the same name may appear more than once.
11Names 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
26Narinfo properties describe component archives that may be available from binary caches.
27The `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
46FOD properties describe a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation).
47The `nix:fod:method` property is required and must be accompanied by a `nix:store_path` property within the same property list.
48All other properties in this namespace are method-specific.
49To 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.
50When generating `nix:fod` properties the method selected should be a stable function with a minimal number of arguments.
51For 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` | Nixpkgs 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{
67 pkgs,
68 filterPropertiesToAttrs,
69 properties,
70}:
71let
72 fodProps = filterPropertiesToAttrs "nix:fod:" properties;
73
74 methods = {
75 fetchzip =
76 {
77 name,
78 url,
79 sha256,
80 ...
81 }:
82 pkgs.fetchzip { inherit name url sha256; };
83 };
84
85in
86methods.${fodProps.method} fodProps
87```