Skip to content

Software bill of materials (SBOM)

Danbyte exports a CycloneDX 1.6 JSON SBOM of your devices and virtual machines: each host, the operating system it runs and every application installed on it, with name, version, supplier and licence. Regenerate it whenever you need it - just before a hand-in, for example - so it shows what is recorded at that moment.

Where the software list comes from

The SBOM lists what Danbyte has recorded; it does not scan hosts. The packages discovery reads from Linux hosts are kept apart, on the host's Packages tab, and are not SBOM components. Each host contributes:

  • its platform (the OS), at the host's Software version, as an operating-system component;
  • its installed software, each as an application component.

Installs are recorded in any of three ways:

  • By hand on the device's or VM's Software tab, or by assigning an application group.
  • CSV import of installed software - see Import & export.
  • The REST API - POST /api/installed-software/, for example from Ansible after gathering package_facts over SSH.

No agent runs on the host and the host needs no access to a package repository: Ansible reads the package list over its usual SSH connection and posts it to Danbyte.

Example: post installed packages from Ansible

The play reads the package list, makes sure each package exists in the application catalog, then records the install. Danbyte answers 400 for a version already recorded on the host, so a re-run changes nothing.

- hosts: all
  gather_facts: false
  vars:
    danbyte: https://danbyte.example
    headers:
      Authorization: "Token {{ lookup('env', 'DANBYTE_TOKEN') }}"
    # The packages to report; leave it out to report all of them.
    report: [openssh-server, nginx, postgresql-16]
  tasks:
    - name: Read the installed packages
      ansible.builtin.package_facts:

    - name: Find the host in Danbyte
      ansible.builtin.uri:
        url: "{{ danbyte }}/api/devices/?search={{ inventory_hostname | urlencode }}&picker=1"
        headers: "{{ headers }}"
      register: host
      delegate_to: localhost

    - name: Add the applications to the catalog
      ansible.builtin.uri:
        url: "{{ danbyte }}/api/applications/"
        method: POST
        headers: "{{ headers }}"
        body_format: json
        body: { name: "{{ item }}", slug: "{{ item }}" }
        status_code: [201, 400]   # 400: already in the catalog
      loop: "{{ report | intersect(ansible_facts.packages.keys()) }}"
      delegate_to: localhost
      run_once: true

    - name: Look up the application ids
      ansible.builtin.uri:
        url: "{{ danbyte }}/api/applications/?search={{ item }}&picker=1"
        headers: "{{ headers }}"
      loop: "{{ report | intersect(ansible_facts.packages.keys()) }}"
      register: apps
      delegate_to: localhost

    - name: Record what is installed
      ansible.builtin.uri:
        url: "{{ danbyte }}/api/installed-software/"
        method: POST
        headers: "{{ headers }}"
        body_format: json
        body:
          application_id: >-
            {{ (item.json.results | selectattr('slug', 'equalto', item.item)
                | first).id }}
          device_id: >-
            {{ (host.json.results | selectattr('name', 'equalto', inventory_hostname)
                | first).id }}
          version: "{{ ansible_facts.packages[item.item][0].version }}"
        status_code: [201, 400]   # 400: this version is already recorded
      loop: "{{ apps.results }}"
      delegate_to: localhost

For a virtual machine, look it up on /api/virtual-machines/ and post virtual_machine_id instead of device_id. The token needs add on installed software (and on applications for the catalog step).

Licences

Every component carries a licence when one is known. A licence is an SPDX licence expression: an identifier such as MIT or Apache-2.0, a LicenseRef-… for a licence not on the SPDX list, or identifiers joined with AND, OR, WITH and parentheses - (MIT OR Apache-2.0) AND BSD-3-Clause. Danbyte checks the form, not the SPDX list, so a new identifier works straight away.

Where
Application License on the application form and its Overview. Every install of it inherits it.
Install License in the Software tab's dialog: an override for this install only, e.g. a dual-licensed product run under its commercial licence. Blank uses the application's.
Platform License on the platform form: the OS's licence.

The Software tab's License column shows the licence the SBOM reports, with an override chip where the install sets its own. All three fields are in import and export as the license column.

An unknown licence is left out of the SBOM, never guessed. The document counts the gaps so you can fill them before you hand it in (see Metadata).

Package URLs and CPEs

A scanner such as Dependency-Track or OSV matches vulnerabilities on a component's package URL (purl) or its CPE 2.3 name. Without one, it finds nothing. Danbyte writes both when they resolve.

Where
Application Package URL and CPE templates on the application form and its Overview (purl_template, cpe_template). Every install of it fills them in.
Install Package URL and CPE in the Software tab's dialog (purl, cpe): a finished value for this install only. Blank uses the application's template.
Platform Package URL and CPE templates on the platform form (purl_template, cpe_template), for the OS component.

A template takes two placeholders:

Placeholder Filled with
{version} The install's version for an application; the host's Software version for a platform.
{os_version} The host's Software version (the running platform version).

FRRouting 10.3-3+deb13u1 on a Debian host at software version 13, with the application template

pkg:deb/debian/frr@{version}?arch=amd64&distro=debian-{os_version}

writes pkg:deb/debian/frr@10.3-3%2Bdeb13u1?arch=amd64&distro=debian-13, and with cpe:2.3:a:frrouting:frrouting:{version}:*:*:*:*:*:*:* it writes cpe:2.3:a:frrouting:frrouting:10.3-3\+deb13u1:*:*:*:*:*:*:*.

  • Values are escaped where they land: percent-encoded in a purl (+ is %2B, : is %3A, a space %20), backslash-quoted in a CPE (anything but letters, digits, ., - and _). Write the rest of the template already escaped.
  • A template whose placeholder has no value - an install without a version, a host without a software version - writes nothing, rather than a half-filled identifier. An install's own value is written as it is.
  • The check is loose: a purl starts pkg:<type>/, a CPE starts cpe:2.3: and has 13 colon-separated parts (part a, o or h). Any other {placeholder} is refused.
  • The Software tab's Package URL and CPE columns (hidden by default) show what the SBOM writes, with an override chip where the install sets its own. The API returns it as effective_purl / effective_cpe.
  • All six fields are in import and export under their field names.

The application's purl_template is the package identity the planned vulnerability matching reads, so a template set now is reused there.

Export

  • Devices and Virtual machines lists: Import / Export → SBOM (CycloneDX) exports the rows the list shows now, with its filters and search applied. While vulnerability data is on, SBOM with vulnerabilities exports the same document with its vulnerabilities section.
  • Site page: Export ▸ SBOM exports the site's devices and VMs.
  • API: GET /api/sbom/ (below).

The file is named sbom-<site name>-<date>.cdx.json for one site and sbom-selection-<date>.cdx.json otherwise.

The document

{
  "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
  "metadata": {
    "timestamp": "2026-11-03T09:30:00Z",
    "tools": {"components": [
      {"type": "application", "name": "Danbyte", "version": "0.19.0"}
    ]},
    "component": {"type": "platform", "bom-ref": "danbyte:site:…", "name": "AMS"},
    "properties": [
      {"name": "danbyte:hosts", "value": "2"},
      {"name": "danbyte:components", "value": "3"},
      {"name": "danbyte:components_without_license", "value": "1"},
      {"name": "danbyte:unlicensed", "value": "IOS-XE"}
    ]
  },
  "components": [
    {
      "type": "device", "bom-ref": "danbyte:device:…", "name": "rtr-01",
      "supplier": {"name": "Cisco"},
      "properties": [{"name": "danbyte:kind", "value": "device"}, …],
      "components": [
        {"type": "operating-system", "bom-ref": "danbyte:device:…:os",
         "name": "IOS-XE", "version": "17.9.4", "supplier": {"name": "Cisco"}}
      ]
    },
    {
      "type": "platform", "bom-ref": "danbyte:virtual_machine:…", "name": "db-01",
      "components": [
        {"type": "operating-system", "bom-ref": "danbyte:virtual_machine:…:os",
         "name": "Ubuntu", "version": "24.04", "supplier": {"name": "Canonical"},
         "licenses": [{"license": {"id": "GPL-2.0-only"}}]},
        {"type": "application", "bom-ref": "danbyte:installedsoftware:…",
         "name": "PostgreSQL", "version": "16.4", "supplier": {"name": "PGDG"},
         "licenses": [{"license": {"id": "PostgreSQL"}}]}
      ]
    }
  ],
  "dependencies": [
    {"ref": "danbyte:site:…", "dependsOn": ["danbyte:device:…", "danbyte:virtual_machine:…"]},
    {"ref": "danbyte:device:…", "dependsOn": ["danbyte:device:…:os"]},
    {"ref": "danbyte:virtual_machine:…", "dependsOn": ["danbyte:virtual_machine:…:os", "danbyte:installedsoftware:…"]}
  ]
}
  • A device is a device component, its supplier the device type's manufacturer; a virtual machine is a platform component. Their properties carry the kind, id, site, role, cluster and device type.
  • The platform is a nested operating-system component at the host's Software version, its supplier the platform's manufacturer.
  • Each install is a nested application component at its version, its supplier the application's manufacturer.
  • purl and cpe are written on the operating-system and application components when they resolve (Package URLs and CPEs).
  • A licence that is one SPDX identifier is written as {"license": {"id": …}}; an expression or a LicenseRef-… as {"expression": …}.
  • dependencies links the site (or the selection) to its hosts, and each host to what runs on it.
  • Blank facts - no version, no manufacturer, no licence - are left out.

Metadata

metadata.component is the site when the export covers exactly one you may view, else selection: a site outside your scope reads like an unknown id, so its name is in neither the document nor the file name. metadata.properties reports:

Property
danbyte:hosts Devices and VMs in the document.
danbyte:components Operating-system and application components.
danbyte:components_without_license Of those, how many have no licence.
danbyte:unlicensed Their names, de-duplicated - the applications and platforms to fix.
danbyte:vulnerabilities With vex=1: entries in the vulnerabilities section.

Vulnerabilities (VEX)

vex=1 (GET /api/sbom/?vex=1, or "vex": true in a POST body) adds a CycloneDX vulnerabilities section while vulnerability data is on - a VEX for the same components, to hand in next to the SBOM. Without vex, or with the feature off, the document has no such section.

"vulnerabilities": [
  {
    "bom-ref": "danbyte:vulnerability:CVE-2023-20198",
    "id": "CVE-2023-20198",
    "source": {"name": "NVD", "url": "https://nvd.nist.gov/vuln/detail/CVE-2023-20198"},
    "ratings": [{"source": {"name": "NVD"}, "score": 10.0, "severity": "critical",
                 "method": "CVSSv31", "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"}],
    "cwes": [420],
    "description": "…",
    "published": "2023-10-16T16:15:09Z",
    "affects": [{"ref": "danbyte:device:…:os",
                 "versions": [{"version": "17.9.4", "status": "affected"}]}],
    "analysis": {"state": "exploitable",
                 "detail": "Listed in CISA Known Exploited Vulnerabilities."},
    "properties": [{"name": "danbyte:priority", "value": "fix_first"},
                   {"name": "danbyte:kev_added", "value": "2023-10-16"}, …]
  }
]
  • One entry per record, listing in affects every component of the document it matched: the host's operating-system component for a platform match, the install's application component for an application match, with the version tested. Only open matches are included.
  • Only components already in the document are named. A host or an install you may not view is in neither the SBOM nor its VEX - the filters and your scope apply to both alike.
  • analysis.state is exploitable for a record in CISA KEV and in_triage otherwise. Exceptions will set their own analysis (not_affected with a justification, or exploitable with will_not_fix); matches of one record with different analyses are then separate entries.
  • properties carry Danbyte's priority, the KEV dates and the EPSS score.

API

GET /api/sbom/ answers the document as an attachment (application/vnd.cyclonedx+json). Filters take ids, repeated or comma-separated; several values of one filter match any of them, and filters combine:

Filter
site Site ids, or site names or slugs (DKW01, dkw01, dkw-01).
tag Tag ids or slugs.
role Device role ids.
device Device ids.
virtual_machine Virtual machine ids.
vex 1 adds the vulnerabilities section.

Given device or virtual_machine, only the listed hosts of each kind are included; without either, every device and VM that matches the other filters.

A site value that is not an id is looked up among the sites you may view: the name as typed first, then the name in any case, then the slug of the name (DKW 01 is dkw-01). Two sites whose names differ only in case both match a case-insensitive spelling; type the name exactly, or use the id, to pick one. A name that matches no site you may view - an unknown name or a site outside your scope - matches no host, the same as an unknown id, and the subject is selection. POST /api/sbom/ takes the same filters as a JSON body ({"device": ["…", "…"]}) for a selection longer than a URL holds; a read-only API token uses GET.

curl -H "Authorization: Token $TOKEN" -o sbom.cdx.json \
  "https://danbyte.example/api/sbom/?site=…&tag=openstack,proxmox"

The document covers the active tenant only, and only the devices and VMs you may view; the installs need view on installed software too. Another tenant's ids, or hosts outside your sites, are left out.