Chapter 7: SBOM in CycloneDX/SPDX and dependency analysis (Syft, Dependency-Track)
In this chapter you will learn:
- what a software bill of materials (SBOM) is and what it has to contain
- the differences between CycloneDX and SPDX and the role of PURL, CPE and VEX
- how to generate SBOMs from source code and container images with Syft and examine them with jq
- how to check an SBOM for vulnerabilities without rescanning the image, and attach it to the image as an attestation
- how Dependency-Track continuously monitors SBOMs, enforces policies and is integrated into the pipeline
What is this about?
Every box of cereal has an ingredients list. If a batch of hazelnuts is contaminated, the manufacturer can immediately say which products are affected, and if you have an allergy, you can see it at a glance. Without an ingredients list, every box would have to be sent to a lab.
Today, software is largely built from third-party ingredients: libraries, operating system packages, runtimes. An SBOM (Software Bill of Materials) is the ingredients list for it. When the Log4Shell vulnerability became known in December 2021, the most important question in every IT department was: “Where do we use log4j?” Those who had SBOMs answered it in minutes. Everyone else searched for weeks.
An SBOM on its own is only a snapshot, though. It becomes valuable when a system continuously matches it against new vulnerability reports. That is exactly what Dependency-Track does.
Source code Build Registry
+-----------+ +-----------+ +------------------+
| demo-app |----->| Image |--------->| reg-build:5000 |
| req.txt | +-----+-----+ | image + SBOM |
+-----+-----+ | | attestation |
| | syft +------------------+
| syft v
v +--------------+ grype +--------------------+
Source SBOM | Image SBOM |--------->| one-time result |
(direct deps) | CycloneDX | +--------------------+
| SPDX | API +--------------------+
+--------------+--------->| Dependency-Track |
| ongoing: CVEs, |
| licenses, policies |
+--------------------+
The concepts in plain terms
What is in an SBOM?
An SBOM is a machine-readable list of components with additional information. In 2021, the US agency NTIA defined minimum elements that still serve as a guideline today:
| Field | Meaning | Example |
|---|---|---|
| Supplier | who publishes the component | Python Software Foundation |
| Name | name of the component | requests |
| Version | exact version | 2.25.0 |
| Unique ID | machine-readable identifier | PURL, CPE |
| Relationship | who depends on whom | demo-app → requests |
| SBOM author | who created the list | Syft in CI |
| Timestamp | when it was created | 2026-10-08T10:15:00Z |
Licenses, checksums (hashes) and provenance information are often added.
CycloneDX and SPDX
There are two established formats. Both are open, and both are supported by all important tools.
| Feature | CycloneDX | SPDX |
|---|---|---|
| Origin | OWASP, standardized as ECMA-424 | Linux Foundation, ISO/IEC 5962 |
| Original focus | security, vulnerabilities | license compliance |
| Versions (as of this book) | 1.6 (widespread), 1.7 | 2.3 (widespread), 3.0 |
| File formats | JSON, XML, Protobuf | JSON, tag-value, YAML, RDF |
| VEX | built in | via OpenVEX / SPDX 3 |
| Dependency-Track | yes | no (4.x) |
In practice this means: for security analyses and Dependency-Track you use CycloneDX. If a customer or auditor requires SPDX (common in license audits), you simply generate both formats from the same scan. Syft can do that in one pass.
PURL and CPE: what is a component’s unique name?
The name requests on its own is ambiguous. There is a
Python package, but also npm packages with this name. That is why every
component needs a unique identifier.
The PURL (Package URL) describes a package the way it is named in its package ecosystem:
pkg:pypi/[email protected]
pkg:deb/debian/[email protected]~deb12u1?arch=amd64&distro=debian-12
pkg:oci/demo-app@sha256%3Aabc123...?repository_url=reg-build%3A5000
Structure:
pkg:<typ>/<namespace>/<name>@<version>?<qualifier>.
PURLs are the most important link to vulnerability databases such as OSV
and GitHub Advisories.
The CPE (Common Platform Enumeration) is older and comes from the NVD, the US vulnerability database:
cpe:2.3:a:python:requests:2.25.0:*:*:*:*:*:*:*
CPEs name vendor and product the way the NVD lists them. That often fits poorly with package names and leads to false matches. That is why Syft only generates guessed CPEs. Where possible, PURL-based matching is more accurate.
Direct and transitive dependencies
The demo-app’s requirements.txt lists three packages:
flask, gunicorn, requests. These
are the direct dependencies. But Flask itself needs
werkzeug, jinja2, click and more.
requests needs urllib3, idna,
certifi and chardet. These are
transitive dependencies, that is, dependencies of
dependencies.
demo-app
+-- flask 3.0.3
| +-- werkzeug, jinja2 (+ markupsafe), click, itsdangerous, blinker
+-- gunicorn 22.0.0
| +-- packaging
+-- requests 2.25.0
+-- urllib3, idna, certifi, chardet
Most vulnerabilities sit in transitive dependencies. Nobody chose them deliberately, and often nobody knows they are there.
Source SBOM and image SBOM
Where you scan determines what you see:
| Kind | Source | Sees | Does not see |
|---|---|---|---|
| Source SBOM | repo, manifests, lockfiles | what is declared | OS packages, unlocked transitives |
| Image SBOM | finished container image | what is actually installed | origin in the source code |
Without a lockfile, Syft only knows the three lines from
requirements.txt in the source directory. In the image, it
finds the Python packages actually installed, including all transitive
ones, as well as the base image’s Debian packages. For the question
“What runs in production?”, the image SBOM is what counts. The source
SBOM is available earlier and helps developers.
Tip: With a lockfile (for example
pip-compilefrompip-tools,poetry.lockoruv.lock), the source SBOM becomes complete too. Pinned versions including hashes are part of a reproducible build anyway (see Chapter 2).
VEX: “Does this affect us?”
A scanner reports: “requests 2.25.0 has CVE-2023-32681.”
Whether your application is really vulnerable as a result, the scanner
does not know. Maybe it does not use a proxy at all, and that is exactly
where the vulnerability lies.
VEX (Vulnerability Exploitability eXchange) is a machine-readable statement by the vendor about a vulnerability in a product. There are four states:
| Status | Meaning |
|---|---|
not_affected |
component included, but not exploitable (with justification) |
affected |
exploitable, action required |
fixed |
fixed in this version |
under_investigation |
still being investigated |
VEX exists as part of CycloneDX, as the standalone OpenVEX format and
in CSAF. Scanners such as Grype and Trivy can read VEX files and then
suppress the findings marked not_affected. Chapter 8 goes
deeper into how to assess findings with justification.
Licenses
Every component is under a license. In SBOMs, licenses are given as
SPDX license IDs, for example MIT, Apache-2.0,
BSD-3-Clause or GPL-2.0-only. Combinations are
written as an expression: MIT OR Apache-2.0. What matters
in practice is the classification:
- Permissive licenses (MIT, BSD, Apache): hardly any obligations besides attribution.
- Copyleft licenses (GPL, AGPL): whoever distributes modified versions must disclose the source code. With AGPL, this also applies to network services.
Container images almost always contain GPL software from the operating system. That is usually unproblematic as long as you only use it. A license policy should be able to tell the difference.
Regulatory context
SBOMs are becoming mandatory. You should know three sets of rules:
- US Executive Order 14028 (May 2021): obligated suppliers to US federal agencies to provide SBOMs. It kicked off the topic worldwide.
- EU Cyber Resilience Act (CRA, Regulation (EU) 2024/2847): applies to products with digital elements on the EU market. Manufacturers must record components and create an SBOM in a common, machine-readable format, at least for the top level of dependencies. The SBOM does not have to be published, but must be presented to market surveillance authorities on request. The reporting obligations for actively exploited vulnerabilities apply from September 2026, the other obligations from December 2027.
- BSI TR-03183 (a technical guideline of the BSI, the German Federal Office for Information Security, titled “Cyber Resilience Requirements for Manufacturers and Products”): Part 2 describes concretely what an SBOM should contain, for example CycloneDX or SPDX in specified minimum versions, complete transitive dependencies, licenses and hashes. Check the current edition, since the minimum versions are being raised.
Remember: Legally, the CRA only requires the top level. Technically sensible, and required by BSI TR-03183, is the complete list. An image SBOM from Syft meets that almost by itself.
Hands-on Lab: From ingredients list to continuous monitoring
You work in ~/seclab/kap07. Prerequisites:
reg-build is running on localhost:5001, the
image localhost:5001/demo-app:1.0.0 has been pushed there
(Chapter 0/1), and the Cosign key pair from Chapter 5 is in
~/seclab/kap05/.
Step 1: Preparation
mkdir -p ~/seclab/kap07 && cd ~/seclab/kap07
syft version | grep -E '^Version'
grype version | grep -E '^Version'
DIGEST=$(crane digest localhost:5001/demo-app:1.0.0)
IMAGE="localhost:5001/demo-app@${DIGEST}"
echo "$IMAGE"Expected: version information for Syft (1.x) and Grype (0.x), and a
line like localhost:5001/demo-app@sha256:4f2a.... As in all
chapters, you work with the digest, so that the SBOM belongs
unambiguously to exactly this image.
Step 2: Source SBOM from the demo-app directory
syft dir:$HOME/seclab/demo-app -o cyclonedx-json=sbom-src.cdx.json
jq -r '.components[] | "\(.name) \(.version)"' sbom-src.cdx.jsonExpected output:
flask 3.0.3
gunicorn 22.0.0
requests 2.25.0
There is nothing more in requirements.txt. Syft only
read what is declared. Transitive dependencies are missing, because
there is no lockfile.
Step 3: Image SBOM in two formats
syft "$IMAGE" \
-o cyclonedx-json=sbom.cdx.json \
-o spdx-json=sbom.spdx.json \
-o table
ls -lh sbom.*.jsonExpected: Syft shows a table with the columns NAME,
VERSION, TYPE (for example
python, deb, binary) on screen
and writes both files. Several -o options with
=datei (file) produce all formats from a single scan.
Tip: If the image is also in the local Docker daemon, Syft may read it from there. With the
registry:prefix you force loading from the registry:syft registry:$IMAGE .... For HTTP registries other thanlocalhost, you needSYFT_REGISTRY_INSECURE_USE_HTTP=true.
Step 4: Examine the SBOM with jq
An SBOM is JSON. With jq you answer questions directly:
# How many components in total?
jq '.components | length' sbom.cdx.json
# Broken down by package type (from the PURL)
jq -r '.components[].purl // "ohne-purl"' sbom.cdx.json \
| cut -d/ -f1 | sort | uniq -cExpected: typically 100 to 150 components in total (depending on the
base image), of which about 80 to 100 are pkg:deb, a good
dozen pkg:pypi and a few pkg:generic (for
example the Python interpreter itself).
# Which requests version is in the image?
jq '.components[] | select(.name=="requests") | {name, version, purl}' sbom.cdx.json{
"name": "requests",
"version": "2.25.0",
"purl": "pkg:pypi/[email protected]"
}The same question in SPDX format. The structure is different, the answer the same:
jq '.packages | length' sbom.spdx.json
jq -r '.packages[] | select(.name=="requests") | .versionInfo' sbom.spdx.jsonNow the comparison of source against image. Which Python packages exist only in the image?
jq -r '.components[] | select((.purl // "") | startswith("pkg:pypi")) | .name' \
sbom.cdx.json | sort > image-py.txt
jq -r '.components[].name' sbom-src.cdx.json | sort > src-py.txt
comm -13 src-py.txt image-py.txtExpected: a list like blinker, certifi,
chardet, click, idna,
itsdangerous, jinja2, markupsafe,
packaging, urllib3, werkzeug
(possibly also pip, setuptools,
wheel). These are the transitive dependencies that appear
in no file of your repo.
Finally, a look at licenses:
jq -r '.components[]
| [.name, (.licenses[0].license.id // .licenses[0].license.name
// .licenses[0].expression // "-")] | @tsv' sbom.cdx.json \
| sort -k2 | head -20Expected: pairs of name and license, for example
flask BSD-3-Clause or Debian packages with
GPL-2.0-only. Some entries have -, because no
license was detected. That, too, is a finding.
Step 5: Check the SBOM for vulnerabilities
Instead of an image, Grype can read an SBOM directly. That is fast and also works where the image itself is not available, for example in a different security zone (see Chapter 4):
grype sbom:./sbom.cdx.json --only-fixed
grype sbom:./sbom.cdx.json -o json \
| jq -r '.matches[] | select(.artifact.name=="requests")
| "\(.vulnerability.id) \(.vulnerability.severity)"' | sort -uExpected output (excerpt; the list grows over time):
NAME INSTALLED FIXED-IN TYPE VULNERABILITY SEVERITY
requests 2.25.0 2.31.0 python GHSA-j8r2-6x86-q33q Medium
requests 2.25.0 2.32.0 python GHSA-9wx4-h78v-vm56 Medium
urllib3 1.26.x ... python GHSA-... Medium
...
Newer Grype versions show additional columns such as
EPSS or RISK. GHSA-j8r2-6x86-q33q
corresponds to CVE-2023-32681 (leaking proxy credentials). The second jq
query lists all identifiers for requests only. Grype uses
the PURLs from the SBOM to find matching entries in its database.
Remember: The SBOM is generated once; the matching can be repeated as often as you like. Tomorrow, the same SBOM can yield new findings without anything having changed in the image.
Step 6: Attach the SBOM to the image as an attestation
An SBOM lying around somewhere as a file proves nothing. Who says it belongs to exactly this image and has not been changed? You know the solution from Chapter 5: you sign the SBOM as an attestation (signed statement) and store it next to the image in the registry.
cosign attest --key ~/seclab/kap05/cosign.key \
--type cyclonedx --predicate sbom.cdx.json \
--tlog-upload=false "$IMAGE"Expected: after you enter the key password, Cosign reports that the
attestation was written to the registry. With
crane ls localhost:5001/demo-app you see a new tag of the
form sha256-....att.
Verify and read it:
cosign verify-attestation --key ~/seclab/kap05/cosign.pub \
--type cyclonedx --insecure-ignore-tlog=true "$IMAGE" \
| jq -r '.payload' | base64 --decode \
| jq '{predicateType, komponenten: (.predicate.components | length)}'Expected: "predicateType": "https://cyclonedx.org/bom"
and the same number of components as in Step 4 (under the key
komponenten, “components”). Before that, Cosign reports on
stderr that the signature was verified against the key.
Warning: With cosign v3, some defaults change. If
attestorverify-attestationreport errors about the signing config or transparency log,--use-signing-config=falsehelps. When in doubt, checkcosign attest --help.
In Chapter 9 you will have Kyverno verify exactly this attestation at deployment time: no image without a signed SBOM.
Step 7: Start Dependency-Track
Dependency-Track consists of an API server (Java, with an embedded H2 database for lab use) and a web frontend. Create a Compose file:
cat > docker-compose.yml <<'EOF'
services:
dtrack-apiserver:
image: dependencytrack/apiserver:latest
mem_limit: 6g
ports:
- "8080:8080"
volumes:
- dtrack-data:/data
restart: unless-stopped
dtrack-frontend:
image: dependencytrack/frontend:latest
depends_on:
- dtrack-apiserver
environment:
API_BASE_URL: "http://localhost:8080"
ports:
- "8088:8080"
restart: unless-stopped
volumes:
dtrack-data: {}
EOF
docker compose up -d
docker compose logs -f dtrack-apiserverWait until a line with Dependency-Track is ready or
Started appears in the log. The first start takes a few
minutes. Exit the log view with Ctrl+C and check:
curl -s http://localhost:8080/api/version | jq '{application, version}'Expected: "application": "Dependency-Track" and the
version number, for example 4.x.
Warning: The API server is memory-hungry. The project states at least 4.5 GB of RAM, with 16 GB recommended. With
mem_limit: 6gthe lab runs stably if Docker has at least 8 GB in total. Stop large containers from other chapters (GitLab, Nexus) first.
Security:
latestis used here only for lab convenience. Determine the digest withcrane digest dependencytrack/apiserver:latestand enterimage@sha256:.... In a real environment, you pull both images from your mirror registry (see Chapter 3).
Step 8: First login, data sources and API key
Open http://localhost:8088. Log in with
admin / admin. You must set a new password
immediately. Choose a lab password and write it down.
Data sources. On first start, Dependency-Track downloads the NVD data. Without an NVD API key this can take a long time. For Python packages, the OSV database is faster and more accurate:
- Administration → Vulnerability Sources → Google OSV Advisories.
- Enable it and select the
PyPIecosystem (plusDebianfor the operating system packages). - Save. The sync runs in the background.
API key. Pipelines log in with an API key, never with a user account:
- Administration → Access Management →
Teams → open the
Automationteam. - Under Permissions, check or add:
BOM_UPLOAD,PROJECT_CREATION_UPLOAD,VIEW_PORTFOLIO,VIEW_VULNERABILITY,VIEW_POLICY_VIOLATION. - Under API Keys, create a key with the plus icon and copy it.
read -rs DT_API_KEY && export DT_API_KEY
curl -s -o /dev/null -w '%{http_code}\n' \
-H "X-Api-Key: $DT_API_KEY" http://localhost:8080/api/v1/projectExpected: 200. With read -rs, the key does
not end up in the shell history. A 401 means a wrong key, a
403 missing permissions.
Step 9: Upload the SBOM via the API
curl -sS -X POST http://localhost:8080/api/v1/bom \
-H "X-Api-Key: $DT_API_KEY" \
-F "autoCreate=true" \
-F "projectName=demo-app" \
-F "projectVersion=1.0.0" \
-F "[email protected]" | tee upload.jsonExpected output:
{"token":"9b3c1e8a-5d2f-4c71-a0e4-2f6b9d1c7e55"}autoCreate=true creates the project if it does not exist
yet. This requires the PROJECT_CREATION_UPLOAD permission.
Processing runs asynchronously. You query the status with the token:
TOKEN=$(jq -r .token upload.json)
curl -s -H "X-Api-Key: $DT_API_KEY" \
http://localhost:8080/api/v1/bom/token/$TOKENExpected: first {"processing":true}, after a few seconds
{"processing":false}.
Remember: Upload the CycloneDX file, not the SPDX file. Dependency-Track 4.x only processes CycloneDX.
Step 10: Review the findings
In the frontend, under Projects, you will find the project
demo-app in version 1.0.0. The
Components, Audit Vulnerabilities and Policy
Violations tabs show the current state. Under Components
you can search for requests and see the associated
vulnerabilities.
The same via the API, the way a pipeline would do it:
UUID=$(curl -s -H "X-Api-Key: $DT_API_KEY" \
"http://localhost:8080/api/v1/project/lookup?name=demo-app&version=1.0.0" \
| jq -r .uuid)
curl -s -H "X-Api-Key: $DT_API_KEY" \
http://localhost:8080/api/v1/finding/project/$UUID \
| jq -r '.[] | [.component.name, .component.version,
.vulnerability.vulnId, .vulnerability.severity] | @tsv' \
| sort -u | head -20Expected: lines like
requests 2.25.0 GHSA-j8r2-6x86-q33q MEDIUM. If the list
is empty, the sync with the data sources is still running. Wait a few
minutes and trigger the analysis again in the project via
Reanalyze.
The metrics for a dashboard:
curl -s -H "X-Api-Key: $DT_API_KEY" \
http://localhost:8080/api/v1/metrics/project/$UUID/current \
| jq '{critical, high, medium, low, policyViolationsTotal}'The decisive difference from Grype in Step 5: Dependency-Track keeps
the SBOM and re-matches it regularly. If a vulnerability in
werkzeug becomes known tomorrow, it appears in the project
without anyone starting the pipeline. Under Notifications you
can set up alerts for this via webhook, email or chat.
Under Audit Vulnerabilities you can assess each finding
(analysis state such as NOT_AFFECTED,
EXPLOITABLE, FALSE_POSITIVE) and justify it.
Dependency-Track can export these assessments as CycloneDX VEX.
Step 11: Create policies
Policies turn findings into rules. Create two in the frontend under Policy Management:
Policy 1: Security
- Create Policy, name
Keine hohen oder kritischen Schwachstellen(“no high or critical vulnerabilities”). - Operator:
Any, Violation State:Fail. - Add conditions:
SeverityisCriticalandSeverityisHigh.
Policy 2: Licenses
- Create Policy, name
Copyleft prüfen(“check copyleft”). - Operator:
Any, Violation State:Warn. - Condition:
License GroupisCopyleft(one of the bundled license groups).
Policies initially apply to all projects. Via Projects in the policy, you can restrict them to specific projects or tags.
Policy evaluation runs on every upload and every analysis. Upload the SBOM again (Step 9) and query the violations:
curl -s -H "X-Api-Key: $DT_API_KEY" \
http://localhost:8080/api/v1/violation/project/$UUID \
| jq -r '.[] | [.policyCondition.policy.violationState,
.policyCondition.policy.name, .component.name] | @tsv' \
| sort | uniq -c | sort -rn | headExpected: violations with WARN for
Copyleft prüfen on Debian packages under GPL. Whether
FAIL violations of the security policy show up depends on
which high vulnerabilities the base image currently has. If there are
none, that is a good sign for the image, not for the policy. To test,
change the condition to Severity is Medium; then
requests triggers it.
Policies can also be created via the API (permission
POLICY_MANAGEMENT). That is the way to manage them as code
in Git:
POLICY=$(curl -s -X PUT http://localhost:8080/api/v1/policy \
-H "X-Api-Key: $DT_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Keine kritischen (API)","operator":"ANY","violationState":"FAIL"}' \
| jq -r .uuid)
curl -s -X PUT http://localhost:8080/api/v1/policy/$POLICY/condition \
-H "X-Api-Key: $DT_API_KEY" -H "Content-Type: application/json" \
-d '{"subject":"SEVERITY","operator":"IS","value":"CRITICAL"}' | jq .uuidExpected: a UUID for the new condition. For this, you first have to
give the Automation team the POLICY_MANAGEMENT
permission. In practice, you use a separate key with its own team for
administrative tasks.
Step 12: Integrate the upload into the pipeline
For GitLab CI you need a tools image with syft,
curl and jq. The official Syft image contains
only the binary, without a shell. So build yourself a small tools image
(for building images, see Chapters 1 and 2). Save the following content
as ~/seclab/kap07/Dockerfile.tools:
FROM alpine:3.20
RUN apk add --no-cache curl jq ca-certificates
COPY --from=anchore/syft:v1.18.0 /syft /usr/local/bin/syft
USER 10001docker build -t localhost:5001/tools/sbom:1.0.0 - < Dockerfile.tools
docker push localhost:5001/tools/sbom:1.0.0Expected: the push reports a digest. The job in the demo-app’s
.gitlab-ci.yml:
variables:
DT_URL: "http://dtrack-apiserver.example.internal:8080"
# DT_API_KEY: as a masked, protected CI/CD variable or from Vault
SYFT_REGISTRY_INSECURE_USE_HTTP: "true" # reg-build speaks HTTP only (lab)
sbom:
stage: build
image: reg-build:5000/tools/sbom:1.0.0
needs: ["build"]
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # same as the build job
script:
- IMAGE_REF="${IMAGE_NAME}@$(cat image-digest.txt)"
- syft "registry:${IMAGE_REF}" -o cyclonedx-json=sbom.cdx.json
-o spdx-json=sbom.spdx.json
- >
curl -sS --fail-with-body -X POST "${DT_URL}/api/v1/bom"
-H "X-Api-Key: ${DT_API_KEY}"
-F "autoCreate=true"
-F "projectName=${CI_PROJECT_NAME}"
-F "projectVersion=${CI_COMMIT_REF_NAME}"
-F "[email protected]"
| tee dt-upload.json
artifacts:
paths: [sbom.cdx.json, sbom.spdx.json, dt-upload.json]
expire_in: 90 daysA few explanations:
IMAGE_NAMEis the variable from the pipeline in Chapter 1. The job reads the digest fromimage-digest.txt, the artifact of thebuildjob;needs: ["build"]downloads it automatically.IMAGE_REFthus contains the image with its digest, so syft never works with a movable tag.stage: buildwithneedspointing to a job in the same stage has been allowed since GitLab 14.2. The rule adopts the condition of thebuildjob, which runs only on the default branch; otherwise the job thatneedspoints to would be missing.--fail-with-body(curl 7.76 and later) makes the job fail on HTTP errors and still shows the response. Older curl versions use--fail.- Taking
projectVersionfrom the branch or tag name results in a separate project per release in Dependency-Track. For tags, that is exactly right. - Ideally, you fetch the API key from Vault via
id_tokensas in Chapter 6, instead of storing it as a CI variable.
If the job should fail on policy violations, you wait for processing to finish and evaluate the violations:
sbom-gate:
stage: build
image: reg-build:5000/tools/sbom:1.0.0
needs: ["sbom"]
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- TOKEN=$(jq -r .token dt-upload.json)
- |
for i in $(seq 1 30); do
curl -s -H "X-Api-Key: ${DT_API_KEY}" \
"${DT_URL}/api/v1/bom/token/${TOKEN}" | grep -q '"processing":false' && break
sleep 10
done
- Q="name=${CI_PROJECT_NAME}&version=${CI_COMMIT_REF_NAME}"
- 'H="X-Api-Key: ${DT_API_KEY}"'
- >
UUID=$(curl -s -H "$H" "${DT_URL}/api/v1/project/lookup?${Q}"
| jq -r .uuid)
- >
FAILS=$(curl -s -H "$H" "${DT_URL}/api/v1/violation/project/${UUID}"
| jq '[.[] | select(.policyCondition.policy.violationState=="FAIL")]
| length')
- echo "FAIL-Verstoesse: ${FAILS}"
- test "${FAILS}" -eq 0Tip: Instead of your own scripts, there are ready-made uploaders such as the CycloneDX CLI or plugins for Jenkins. The small curl script has the advantage, though, that you see exactly what happens and do not pull another dependency into the pipeline.
How strict such a gate should be and how to deal with legitimate exceptions is covered in Chapter 8 and Chapter 10.
Step 13: Clean up
cd ~/seclab/kap07
docker compose down
docker compose down -v # only if you no longer need the data
docker ps --filter name=dtrackExpected: the last output no longer shows any running
dtrack containers. With -v you also delete the
volume with the database and vulnerability data. That saves space, but
costs the complete initial sync again on the next start. The SBOM files
and the attestation in reg-build are kept. You need them in
Chapters 9 and 11.
Save your progress? Sign up for free
Common pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| Source SBOM has only 3 packages | no lockfile | Generate a lockfile or scan the image |
| Upload: HTTP 401 | API key wrong or header mistyped | Check X-Api-Key |
| Upload: HTTP 403 | Team lacks BOM_UPLOAD /
PROJECT_CREATION_UPLOAD |
Add the team’s permissions |
| Upload ok, project empty | SPDX uploaded instead of CycloneDX | Use sbom.cdx.json |
| No vulnerabilities in DT | Data sources not loaded yet | Enable OSV, wait, Reanalyze |
| API server restarts (OOM) | Too little RAM for Docker | Raise mem_limit, stop other containers |
| Frontend loads, shows no data | API_BASE_URL wrong |
Browser’s view: http://localhost:8080 |
syft: http: server gave HTTP response |
HTTP registry not marked as insecure | SYFT_REGISTRY_INSECURE_USE_HTTP=true |
| Many false matches for OS packages | CPE matching inaccurate | Prefer PURL-based sources, VEX |
Exercise: Upgrade with proof
A developer claims: “I upgraded requests to 2.32.3, so
the vulnerabilities are gone.” Check this with an SBOM and
Dependency-Track:
- In
~/seclab/demo-app/requirements.txt, raise the version ofrequeststo2.32.3, build the image aslocalhost:5001/demo-app:1.0.1and push it. - Generate a CycloneDX SBOM for the new image (by digest).
- Use jq to show which components differ in name or version between
1.0.0and1.0.1. - Upload the SBOM to Dependency-Track as project version
1.0.1and compare the number of findings of both versions via the metrics API.
Hint 1
For the comparison in point 3, generate a sorted list of the form
name@version from both SBOMs (easiest from the
purl field, but only for pkg:pypi). The
diff or comm tool then shows you the
differences.
Hint 2
Pay attention to the transitive packages. Newer requests
versions require a newer urllib3 major version and
charset-normalizer instead of chardet. So more
than one line should show up in the list. For point 4 you need the
project UUID per version via /api/v1/project/lookup.
Solution
cd ~/seclab/demo-app
sed -i.bak 's/^requests==.*/requests==2.32.3/' requirements.txt
docker build -t localhost:5001/demo-app:1.0.1 .
docker push localhost:5001/demo-app:1.0.1
cd ~/seclab/kap07
D2=$(crane digest localhost:5001/demo-app:1.0.1)
syft "localhost:5001/demo-app@${D2}" -o cyclonedx-json=sbom-1.0.1.cdx.json
for f in sbom.cdx.json sbom-1.0.1.cdx.json; do
jq -r '.components[].purl // empty | select(startswith("pkg:pypi"))' "$f" \
| sort > "${f%.cdx.json}.purls"
done
diff sbom.purls sbom-1.0.1.purlsExpected output (roughly):
< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
< pkg:pypi/[email protected]
---
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]
> pkg:pypi/[email protected]
The exact versions of urllib3, idna and
charset-normalizer depend on when the build happens,
because they are not pinned. That is yet another argument for a
lockfile.
Upload and comparison:
curl -sS -X POST http://localhost:8080/api/v1/bom -H "X-Api-Key: $DT_API_KEY" \
-F autoCreate=true -F projectName=demo-app -F projectVersion=1.0.1 \
-F "[email protected]"
sleep 30
for v in 1.0.0 1.0.1; do
U=$(curl -s -H "X-Api-Key: $DT_API_KEY" \
"http://localhost:8080/api/v1/project/lookup?name=demo-app&version=$v" \
| jq -r .uuid)
echo -n "$v: "
curl -s -H "X-Api-Key: $DT_API_KEY" \
http://localhost:8080/api/v1/metrics/project/$U/current \
| jq -c '{high, medium, low}'
doneExpected: version 1.0.1 has fewer findings; the
requests findings are gone. If the metrics still return
null, trigger Reanalyze in the frontend and wait
briefly. So the answer to the developer is: “Correct, and here is the
proof.” The remaining findings mostly come from the base image. With
git checkout requirements.txt or the .bak file
you restore the original state, because later chapters need the
vulnerable version.
Save your progress? Sign up for free
In practice
SBOM per release, not per commit. In
Dependency-Track, each projectVersion creates a project. If
you upload on every feature branch commit, you will soon have thousands
of projects and an unusable portfolio. What has proven itself: upload
only for tags and the main branch. For main, use a fixed
version such as main or snapshot that is
overwritten on every upload. From Dependency-Track 4.12 on, you can mark
versions as “latest” and deactivate old versions, so they do not skew
the metrics.
What is really running? The most important goal is
an answer to the Log4Shell question: “Where does component X run in
version Y?” For that, the projects in Dependency-Track have to be linked
to what is actually deployed. In practice, projects are given tags such
as env:prod or are updated from the GitOps repository (Argo
CD, Flux, see Chapter 1). The search via Components then shows
portfolio-wide where a component sits.
Zone boundaries and air-gapped. The SBOM travels across the zone boundary as a signed attestation with the image (see Chapter 4). In the target zone, the release office verifies the signature and loads the SBOM into its own Dependency-Track instance. That instance gets its vulnerability data via a mirrored feed. Dependency-Track supports mirroring NVD and OSV data via custom URLs for this. Plan a regular, controlled import process for this; otherwise the instance monitors against outdated data.
Operations. For continuous operation, replace the embedded H2 database with PostgreSQL. H2 is meant for testing only. Back up the database regularly, because it contains the teams’ audit decisions. Those are the actual knowledge and cannot be regenerated. Dependency-Track provides Prometheus metrics if you enable them in the configuration. Monitor queues, the last successful mirroring of the data sources and memory usage. Keep an eye on an upcoming major version jump (version 5 with a new architecture) and test it beforehand.
Permissions and responsibility. Each team sees its own portfolio; security officers see everything. Dependency-Track can connect users via OIDC or LDAP. Pipeline keys belong to dedicated teams with minimal permissions. A leaked upload key is annoying; a leaked admin key allows switching off all policies.
SBOMs from suppliers. The CRA and public-sector tenders increasingly require SBOMs for purchased software. Dependency-Track can also ingest third-party CycloneDX SBOMs. Create separate projects per supplied product and check the quality of incoming SBOMs (are versions, PURLs, licenses missing?). An SBOM with 20 components for a product with a Java stack is a warning sign.
Interview questions
Q: What is an SBOM, and what do you need it for?
A: A machine-readable list of all components of a piece of software with name, version, a unique identifier such as a PURL, licenses and dependencies. You need it to know quickly which products are affected by new vulnerabilities, for license compliance, and increasingly for regulatory obligations such as the CRA.
Q: CycloneDX or SPDX, which format do you use?
A: Both are established. CycloneDX comes from the security world, includes VEX and is the input format of Dependency-Track. SPDX is an ISO standard and strong in license compliance. When in doubt, I generate both from one scan and use CycloneDX for the security analysis.
Q: Why do SBOMs from source code and from the image differ?
A: The source SBOM shows what is declared. Without a lockfile, transitive dependencies are missing, and the base image’s operating system packages are always missing. The image SBOM shows what is actually installed and shipped. For assessing operational risk, the image SBOM is what counts.
Q: What is a PURL, and why is it more important than a CPE?
A: A Package URL names a package unambiguously in
the context of its ecosystem, for example
pkg:pypi/[email protected]. CPEs come from the NVD and often
map vendor and product to packages inaccurately. That produces false
matches. PURL-based matching against OSV or GitHub Advisories is more
precise.
Q: Why Dependency-Track, when Grype can also scan the SBOM?
A: Grype provides a snapshot during the pipeline run. Dependency-Track stores SBOMs permanently, continuously matches them against new vulnerability data, evaluates policies, stores audit decisions and shows portfolio-wide where a component sits. So it also monitors software that is not currently being built.
Q: What is VEX?
A: A machine-readable statement on whether a known
vulnerability affects a specific product, with a status such as
not_affected, affected, fixed or
under_investigation and a justification. Scanners can read
VEX and thus suppress false alarms permanently and traceably.
Q: How do you make sure an SBOM really belongs to a specific image?
A: I generate it for the image by digest and attach
it as a signed attestation (for example with
cosign attest --type cyclonedx) to exactly this digest.
Consumers verify the signature with their own trust anchor, and an
admission policy can enforce the proof before deployment.
Q: What does the Cyber Resilience Act require regarding SBOMs?
A: Manufacturers must record the components of their products and create an SBOM in a common machine-readable format, at least for the top-level dependencies. It does not have to be published, but must be presented to authorities on request. In Germany, BSI TR-03183 specifies the requirements in more detail, including complete transitive dependencies.
Summary
Here is what you learned:
- An SBOM is the ingredients list of your software: components with version, PURL, license and relationships.
- CycloneDX is security-oriented and the format for Dependency-Track; SPDX is an ISO standard with a license focus. Syft generates both in one run.
- Source SBOMs show what is declared, image SBOMs show what is installed. You only reliably find transitive dependencies and OS packages in the image or with a lockfile.
- With jq you query the SBOM directly; with
grype sbom:you check it without rescanning the image. - A signed attestation binds the SBOM to the image digest in a tamper-proof way.
- Dependency-Track continuously monitors SBOMs, enforces security and license policies, and can be integrated into any pipeline via API key and curl.
- VEX records why a finding does not affect a product and makes assessments machine-readable.
- The CRA, BSI TR-03183 and US EO 14028 turn SBOMs from good practice into an obligation.