Skip to content
Hands-on IT IT Drills

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-compile from pip-tools, poetry.lock or uv.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.json

Expected 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.*.json

Expected: 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 than localhost, you need SYFT_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 -c

Expected: 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.json

Now 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.txt

Expected: 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 -20

Expected: 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 -u

Expected 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 attest or verify-attestation report errors about the signing config or transparency log, --use-signing-config=false helps. When in doubt, check cosign 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-apiserver

Wait 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: 6g the lab runs stably if Docker has at least 8 GB in total. Stop large containers from other chapters (GitLab, Nexus) first.

Security: latest is used here only for lab convenience. Determine the digest with crane digest dependencytrack/apiserver:latest and enter image@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:

  1. Administration → Vulnerability Sources → Google OSV Advisories.
  2. Enable it and select the PyPI ecosystem (plus Debian for the operating system packages).
  3. Save. The sync runs in the background.

API key. Pipelines log in with an API key, never with a user account:

  1. Administration → Access Management → Teams → open the Automation team.
  2. Under Permissions, check or add: BOM_UPLOAD, PROJECT_CREATION_UPLOAD, VIEW_PORTFOLIO, VIEW_VULNERABILITY, VIEW_POLICY_VIOLATION.
  3. 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/project

Expected: 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.json

Expected 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/$TOKEN

Expected: 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 -20

Expected: 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

  1. Create Policy, name Keine hohen oder kritischen Schwachstellen (“no high or critical vulnerabilities”).
  2. Operator: Any, Violation State: Fail.
  3. Add conditions: Severity is Critical and Severity is High.

Policy 2: Licenses

  1. Create Policy, name Copyleft prüfen (“check copyleft”).
  2. Operator: Any, Violation State: Warn.
  3. Condition: License Group is Copyleft (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 | head

Expected: 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 .uuid

Expected: 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 10001
docker build -t localhost:5001/tools/sbom:1.0.0 - < Dockerfile.tools
docker push localhost:5001/tools/sbom:1.0.0

Expected: 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 days

A few explanations:

  • IMAGE_NAME is the variable from the pipeline in Chapter 1. The job reads the digest from image-digest.txt, the artifact of the build job; needs: ["build"] downloads it automatically. IMAGE_REF thus contains the image with its digest, so syft never works with a movable tag.
  • stage: build with needs pointing to a job in the same stage has been allowed since GitLab 14.2. The rule adopts the condition of the build job, which runs only on the default branch; otherwise the job that needs points 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 projectVersion from 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_tokens as 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 0

Tip: 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=dtrack

Expected: 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:

  1. In ~/seclab/demo-app/requirements.txt, raise the version of requests to 2.32.3, build the image as localhost:5001/demo-app:1.0.1 and push it.
  2. Generate a CycloneDX SBOM for the new image (by digest).
  3. Use jq to show which components differ in name or version between 1.0.0 and 1.0.1.
  4. Upload the SBOM to Dependency-Track as project version 1.0.1 and 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.purls

Expected 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}'
done

Expected: 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.