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-systemcomponent; - its installed software, each as an
applicationcomponent.
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 gatheringpackage_factsover 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
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 startscpe:2.3:and has 13 colon-separated parts (parta,oorh). 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
devicecomponent, its supplier the device type's manufacturer; a virtual machine is aplatformcomponent. Their properties carry the kind, id, site, role, cluster and device type. - The platform is a nested
operating-systemcomponent at the host's Software version, its supplier the platform's manufacturer. - Each install is a nested
applicationcomponent at its version, its supplier the application's manufacturer. purlandcpeare 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 aLicenseRef-…as{"expression": …}. dependencieslinks 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
affectsevery component of the document it matched: the host'soperating-systemcomponent for a platform match, the install'sapplicationcomponent 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.stateisexploitablefor a record in CISA KEV andin_triageotherwise. Exceptions will set their own analysis (not_affectedwith a justification, orexploitablewithwill_not_fix); matches of one record with different analyses are then separate entries.propertiescarry 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.