Files and how to run them
The machine-readable files that make up the example: six PKIC CBOM profiles, four schemas, sixteen example CBOMs built on Keycloak 26.7.3, two policies with three results, six perspectives and five tools. The commands reproduce every conformance result and policy result shown in the methodology. Every choice they embody is recorded in decision 0025.
Profiles
| File | Description |
|---|---|
| profile-interface-enumeration.rules.json | Entry depth, v0.3. The shallowest set of rules that still produces a usable inventory record. Accepts products and deployments at every stage, including intended. See Maturity |
| profile-interface-disclosure.rules.json | The baseline, v0.9. Document-level rules P1 to P6, per-interface rules I1 to I11 and reference rules R1 to R6. Accepts products and deployments at implemented, configured and observed |
| profile-deployment-disclosure.rules.json | Deployment records, v0.1, extending the baseline. Cited documents by BOM-Link and SHA-256, correspondsTo, observation method and window, and four context pointers |
| profile-pqc-migration.rules.json | PQC migration, v0.8, extending the baseline. Capability attributes I1 to I12, capability per purpose (G1), and the support-lifecycle (R1) and roadmap (R2) pointers. Products at implemented |
| profile-pqc-migration-extended.rules.json | PQC migration, extended depth, v0.1, extending pqc-migration. Key management and storage (decision 0022) |
| profile-procurement.rules.json | Procurement, v0.1, extending the baseline. A storage interface or a stated reason for none, coverage all or all-external, and an implementing library that may not be withheld |
Every profile declares the carrier range min 1.6, tested 2.0. See Versioning.
Schemas
| File | Description |
|---|---|
| profile.schema.json | The schema for a rules file. A third party can use it to validate a profile without our checker. It does not replace requirements C1 to C18: a schema can check that objective has a decision string, but not whether the decision is one a consumer could act on |
| claim.schema.json | The schema for a conformance claim. It enforces two consistency rules: a refused entry carries no rule results, and an entry that claims conformance may not list a failed MUST rule |
| policy.schema.json | The schema for a policy: versioned data plus a named evaluation method |
| policy-result.schema.json | The schema for a policy result. A result names the policy id, version and digest, the evaluation date, every CBOM it read by SHA-256 digest, and what it does not assert |
Example CBOMs
All examples describe Keycloak 26.7.3. The product records describe the container image as the vendor builds it. The deployment records describe an illustrative operator, Example Org, running sso.example.org, where TLS ends at an nginx ingress using OpenSSL 3.5 and Keycloak runs with its HTTP listener enabled behind it. Every file is CycloneDX 2.0, except the two under examples/legacy/, which are CycloneDX 1.7.
| File | What it shows | Expected verdict |
|---|---|---|
| cbom-keycloak-product.cdx.json | The vendor's build record of the container image, with 13 cryptographic interfaces | Conforms to enumeration, baseline, pqc-migration, pqc-migration-extended and procurement |
| legacy/cbom-keycloak-product-1.7.cdx.json | The same facts in CycloneDX 1.7 | The same verdicts, flagged legacy |
| cbom-keycloak-product-fail-R5.cdx.json | The HTTPS listener states deployment-defined without a pointer to the configuration guide | Fails baseline R5 only |
| cbom-keycloak-product-fail-P2.cdx.json | The management interfaces are left out, with no reason given | Fails baseline P2; conforms to entry |
| cbom-keycloak-product-disclosure-states.cdx.json | The four disclosure outcomes, spread across three interfaces: the OIDC library withheld, the cluster authentication unknown and the SAML encryption undeclared | Fails I5 (unknown) and I4 (undeclared); the withheld library is permitted; conforms to entry |
| cbom-keycloak-product-fail-pqc-I12.cdx.json | The storage interface's key-wrapping capability is missing | Fails pqc-migration I12 only |
| cbom-keycloak-product-fail-ext-I3.cdx.json | The key types the Admin API can generate are missing | Fails extended I3 only |
| cbom-keycloak-product-fail-procurement-P5.cdx.json | The storage interface is missing | Fails procurement P5 only |
| cbom-keycloak-product-intended.cdx.json | A design record for Keycloak 27.0 with ML-DSA-65 | Fails baseline I8 on every interface, and I3 to I5 where it repeats build-time literals; conforms to entry |
| legacy/cbom-keycloak-scanner-output.cdx.json | Untargeted scanner output in CycloneDX 1.7 | Fails entry P1, P3, P4, P5 and P6 |
| cbom-keycloak-deployment-configured.cdx.json | Example Org's configured record. It cites the product record | Conforms to the deployment profile |
| cbom-keycloak-deployment-configured-fail-literal.cdx.json | peer-defined kept at configured | Fails I3, I4 and I5 on the database connection |
| cbom-keycloak-deployment-observed.cdx.json | The deployment observed from 18 to 25 October 2026, with an observation method per interface. It cites the configured record and the product record | Conforms to the deployment profile |
| cbom-keycloak-deployment-observed-fail-unknown.cdx.json | The database group is unknown, because the observer had only pg_stat_ssl | Fails baseline I3; conforms to entry. A record with gaps lands one depth down |
| cbom-keycloak-deployment-observed-fail-P1.cdx.json | The configured record it cites has changed since | Fails deployment P1 (hash mismatch) when the configured record is supplied |
| cbom-postgres-deployment-configured.cdx.json | The database team's configured record for the PostgreSQL cluster Keycloak connects to. Its TLS interface names Keycloak's int-db as the far end with peerInterface | conforms to deployment disclosure v0.2 |
| cbom-keycloak-deployment-observed-outside.cdx.json | An outside assessor's observation. The management port was not reached | P2 passes through not-reached; fails I9 on the ingress, whose library is not visible; conforms to entry |
Context documents
The Keycloak product record points to four documents it does not carry. They are committed under examples/context/, so every pointer can be followed and every hash checked. They are examples of what a supplier publishes beside its record. See Context Pointers.
| File | Pointed to by | What it is |
|---|---|---|
| keycloak-26.7.3-sbom.cdx.json | interface-disclosure#R1, and each library's BOM-Link | Companion SBOM of the image, CycloneDX 2.0. An illustrative subset of components, declared incomplete. |
| keycloak-26.7.3-vex.cdx.json | interface-disclosure#R2 | Vulnerability statements, CycloneDX 2.0: resolved, not affected, in triage. Illustrative identifiers, not CVEs; upstream Keycloak publishes no VEX. |
| keycloak-configuration-guidance.json | interface-disclosure#R5 | Who decides each value the product leaves open, and the Keycloak setting that decides it. |
| keycloak-pqc-roadmap.json | pqc-migration#R2 | Planned post-quantum availability per purpose, with blockers, dependencies and target releases. |
To check the hashes while validating, supply the CycloneDX documents:
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-interface-disclosure.rules.json \
--with examples/context/keycloak-26.7.3-sbom.cdx.json --with examples/context/keycloak-26.7.3-vex.cdx.json
Policies and results
| File | Description |
|---|---|
| policies/policy-readiness-gap.policy.json | Example policy, method readiness-gap. Joins a product record, a configured record and an observed record, and places each interface and purpose in one gap class |
| policies/policy-algorithm-transition.policy.json | Example policy, method algorithm-transition. Classifies each disclosed algorithm against the schedule in the NIST IR 8547 initial public draft (November 2024, not final as of October 2026) |
| examples/results/result-readiness-gap-sso-prod.json | The readiness gap for sso.example.org, evaluated on 2026-10-25 from the product, configured and observed records. Ingress key establishment is enabled-not-negotiated; the plaintext proxy hop and the management port are unprotected; token signing and Keycloak's own TLS are not-capable; the product HTTPS listener is not-deployed |
| policies/policy-edge-posture.policy.json | Example policy, method edge-posture. Joins the two ends of each connection along peerInterface and names the end that limits it (decision 0026) |
| examples/results/result-edge-posture-sso-db.json | The edge posture of the connection from Keycloak to PostgreSQL, evaluated on 2026-10-25. Key establishment is limited by Keycloak's end |
| examples/results/result-algorithm-transition-keycloak-product.json | The algorithm-transition policy applied to the product record on 2026-10-25 |
| examples/results/result-algorithm-transition-sso-prod-observed.json | The algorithm-transition policy applied to the observed deployment record on 2026-10-25 |
See Policy Evaluation.
Perspectives
Each profile has one CycloneDX 2.0 perspective in perspectives/: interface-enumeration, interface-disclosure, deployment-disclosure, pqc-migration, pqc-migration-extended and procurement. A perspective lists the JSONPath expressions a generic 2.0 tool can check for presence. It is generated from the rules file and is informative only. The rules file is normative. See Formats.
Tools
| File | Description |
|---|---|
| validate_cbom.py | Validates a CBOM against a profile. Reads CycloneDX 2.0 and 1.x, resolves profile composition, follows joins to cited documents given with --with, and issues and verifies conformance claims. Exit 0 conforms, 1 does not conform, 2 usage error, 3 profile error, 4 refused, 5 claim mismatch |
| check_profile.py | Checks a profile against requirements C1 to C18 of Conformance. C18 requires every reference rule to name a defined context kind carried by real CycloneDX reference types |
| evaluate_policy.py | Evaluates CBOMs against a policy at a stated date and writes a policy result |
| compare_stages.py | Lays the product, configured and observed records side by side, one row per interface, by following correspondsTo. It makes no judgement |
| cdx17_to_20.py | Converts a CycloneDX 1.6 or 1.7 CBOM to CycloneDX 2.0. Its docstring lists every conversion |
Other files
| File | Description |
|---|---|
| claim-example.json | A conformance claim for the Keycloak product record, bound to it by SHA-256 digest. It covers the baseline v0.9, pqc-migration v0.8 and pqc-migration-extended v0.1, each with its whole chain |
| demo-reports.json | The reports the Demo page renders. Generated by the validator; do not edit |
| profile-interface-disclosure.md | Prose specification of the baseline |
| mapping-cyclonedx-spdx.md | The full mapping of every rule and attribute to CycloneDX 2.0, CycloneDX 1.6/1.7 (legacy) and SPDX 3.0.1 |
| versioning-and-legacy-cboms.md | Treatment of older CBOM files: the carrier range, legacy reading, conversion and re-pinning |
Files in the repository
Some files are not published with the site, because they build or check what is published.
tools/build_keycloak_examples.pywrites every example CBOM. It builds each document in CycloneDX 1.7 form fromtools/keycloak/source-product-1.7.jsonand converts it withcdx17_to_20.py. It writes a cited document before the document that cites it, so every citation carries the right hash.tools/build_perspectives.pywrites the six perspectives from the rules files.tools/build_demo_reports.pywritesdemo-reports.jsonwith the validator.tests/schemas/cyclonedx-2.0/holds the CycloneDX 2.0 schema pinned toCycloneDX/specificationbranch2.0-dev, commit76f185c(23 October 2026).tests/run-profile-tests.shruns the test suite. It checks every example's verdicts, validates the examples and perspectives against their CycloneDX schema, and checks that the demonstration matches the validator. Seetests/README.md.
Running the validator
Run the commands from docs/methodology/.
# conforms to the baseline (CycloneDX 2.0)
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-interface-disclosure.rules.json
# does not conform; fails P2 (no management interface, and no reason given)
python3 validate_cbom.py examples/cbom-keycloak-product-fail-P2.cdx.json profile-interface-disclosure.rules.json
# the same document at the family's entry depth, which does not require a
# management interface: conforms. See Maturity.
python3 validate_cbom.py examples/cbom-keycloak-product-fail-P2.cdx.json profile-interface-enumeration.rules.json
# JSON output, for integration into a continuous-integration gate
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-interface-disclosure.rules.json --json
Deployment records and joins
A deployment record cites the records it builds on. Give the validator the cited records with --with, and it checks each citation's serial number, version and hash, and follows correspondsTo to inherit the implementing library.
# the configured record, with the product record it cites: conforms
python3 validate_cbom.py examples/cbom-keycloak-deployment-configured.cdx.json profile-deployment-disclosure.rules.json \
--with examples/cbom-keycloak-product.cdx.json
# the observed record, with both records it cites: conforms
python3 validate_cbom.py examples/cbom-keycloak-deployment-observed.cdx.json profile-deployment-disclosure.rules.json \
--with examples/cbom-keycloak-product.cdx.json --with examples/cbom-keycloak-deployment-configured.cdx.json
# the cited configured record has changed: fails deployment-disclosure#P1
python3 validate_cbom.py examples/cbom-keycloak-deployment-observed-fail-P1.cdx.json profile-deployment-disclosure.rules.json \
--with examples/cbom-keycloak-product.cdx.json --with examples/cbom-keycloak-deployment-configured.cdx.json
Without --with, the validator checks each citation for form only. It reports an inherited value as unresolved, not failed. cbom-keycloak-deployment-observed-fail-P1.cdx.json therefore conforms when the configured record is not supplied, because the evaluator cannot see that the record has changed.
Reproducing the version bands
# four bands need four inputs: the 2.0 example, the 1.7 legacy example, and two copies
python3 - <<'PY'
import json
b = json.load(open("examples/cbom-keycloak-product.cdx.json"))
b["specVersion"] = "2.1"
json.dump(b, open("cbom-2.1.json", "w"))
b = json.load(open("examples/legacy/cbom-keycloak-product-1.7.cdx.json"))
b["specVersion"] = "1.5"
json.dump(b, open("cbom-1.5.json", "w"))
PY
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-interface-disclosure.rules.json # target: exit 0
python3 validate_cbom.py examples/legacy/cbom-keycloak-product-1.7.cdx.json profile-interface-disclosure.rules.json # legacy: accepted with a warning, exit 0
python3 validate_cbom.py cbom-2.1.json profile-interface-disclosure.rules.json # newer: accepted, review advised, exit 0
python3 validate_cbom.py cbom-1.5.json profile-interface-disclosure.rules.json # refused: not assessed, exit 4
The last of these commands is the most useful one to run. A refusal is not a failure. The document was never assessed, so the validator exits with 4 rather than 1 and reports no rule results for it. A pipeline that treats any non-zero exit code as a rejection will penalise a supplier for the age of its carrier format. The distinct exit code exists to prevent that.
The derived profiles
pqc-migration, pqc-migration-extended and procurement extend the baseline, directly or through pqc-migration, so evaluating against one of them also evaluates every baseline rule. The validator resolves the base, applies the overrides, and rejects any override that would relax an inherited rule.
# the product record conforms to all three
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-pqc-migration.rules.json
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-pqc-migration-extended.rules.json
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json profile-procurement.rules.json
# each failing example fails one rule of one depth
python3 validate_cbom.py examples/cbom-keycloak-product-fail-pqc-I12.cdx.json profile-pqc-migration.rules.json # pqc-migration#I12
python3 validate_cbom.py examples/cbom-keycloak-product-fail-ext-I3.cdx.json profile-pqc-migration-extended.rules.json # pqc-migration-extended#I3
python3 validate_cbom.py examples/cbom-keycloak-product-fail-procurement-P5.cdx.json profile-procurement.rules.json # procurement#P5
Conformance claims
# issue a claim for several profiles at once, bound to the document by digest
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json \
profile-interface-disclosure.rules.json profile-pqc-migration.rules.json profile-pqc-migration-extended.rules.json --claim
# re-check a claim against the document and the profiles it names: exit 0, or 5 on a mismatch
python3 validate_cbom.py examples/cbom-keycloak-product.cdx.json claim-example.json --verify-claim
Checking a profile
A profile can itself be checked, against requirements C1 to C18 of Conformance. C1 to C7 and C11 to C18 are MUST requirements and determine the result. C8 to C10 are reported as warnings unless --strict is given.
# all six profiles are well-formed
for p in profile-*.rules.json; do python3 check_profile.py "$p"; done
# require the SHOULD material as well: exclusions, companion artifacts, changelog
python3 check_profile.py profile-interface-disclosure.rules.json --strict
# machine-readable findings
python3 check_profile.py profile-pqc-migration.rules.json --json
The test suite carries one deliberately defective profile per MUST requirement, so that each check is itself tested. See tests/fixtures/ and tests/README.md in the repository.
Policies and stages
# the readiness gap for sso.example.org, at the fixed evaluation date
python3 evaluate_policy.py policies/policy-readiness-gap.policy.json \
examples/cbom-keycloak-product.cdx.json examples/cbom-keycloak-deployment-configured.cdx.json \
examples/cbom-keycloak-deployment-observed.cdx.json --date 2026-10-25 --out result.json
# the algorithm-transition policy applied to the product record
python3 evaluate_policy.py policies/policy-algorithm-transition.policy.json \
examples/cbom-keycloak-product.cdx.json --date 2026-10-25 --out result.json
# what each stage reports for each interface, side by side
python3 compare_stages.py examples/cbom-keycloak-product.cdx.json \
examples/cbom-keycloak-deployment-configured.cdx.json examples/cbom-keycloak-deployment-observed.cdx.json
# convert a CycloneDX 1.7 CBOM to 2.0
python3 cdx17_to_20.py examples/legacy/cbom-keycloak-product-1.7.cdx.json converted-2.0.json
A policy result points to the CBOMs it read, by digest. A CBOM never points to a result.
Sources for the Keycloak facts
The example CBOMs cite these sources for the product facts:
- Keycloak, Configuring TLS: https://www.keycloak.org/server/enabletls (the operator-supplied server certificate)
- Keycloak, Configuring the management interface: https://www.keycloak.org/server/management-interface (port 9000, health and metrics)
- Keycloak issue #39933, realm key material stored in plaintext: https://github.com/keycloak/keycloak/issues/39933
- Keycloak issue #43690, ML-DSA token signing: https://github.com/keycloak/keycloak/issues/43690
- JEP 527, the Java runtime change that post-quantum key exchange in Keycloak's own TLS waits on: https://openjdk.org/jeps/527
- Keycloak security advisories and security policy: https://github.com/keycloak/keycloak/security/advisories, https://github.com/keycloak/keycloak/security/policy