CBOMProfiles /Methodology ← Working group site
REFERENCE

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

FileDescription
profile-interface-enumeration.rules.jsonEntry 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.jsonThe 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.jsonDeployment 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.jsonPQC 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.jsonPQC migration, extended depth, v0.1, extending pqc-migration. Key management and storage (decision 0022)
profile-procurement.rules.jsonProcurement, 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

FileDescription
profile.schema.jsonThe 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.jsonThe 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.jsonThe schema for a policy: versioned data plus a named evaluation method
policy-result.schema.jsonThe 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.

FileWhat it showsExpected verdict
cbom-keycloak-product.cdx.jsonThe vendor's build record of the container image, with 13 cryptographic interfacesConforms to enumeration, baseline, pqc-migration, pqc-migration-extended and procurement
legacy/cbom-keycloak-product-1.7.cdx.jsonThe same facts in CycloneDX 1.7The same verdicts, flagged legacy
cbom-keycloak-product-fail-R5.cdx.jsonThe HTTPS listener states deployment-defined without a pointer to the configuration guideFails baseline R5 only
cbom-keycloak-product-fail-P2.cdx.jsonThe management interfaces are left out, with no reason givenFails baseline P2; conforms to entry
cbom-keycloak-product-disclosure-states.cdx.jsonThe four disclosure outcomes, spread across three interfaces: the OIDC library withheld, the cluster authentication unknown and the SAML encryption undeclaredFails I5 (unknown) and I4 (undeclared); the withheld library is permitted; conforms to entry
cbom-keycloak-product-fail-pqc-I12.cdx.jsonThe storage interface's key-wrapping capability is missingFails pqc-migration I12 only
cbom-keycloak-product-fail-ext-I3.cdx.jsonThe key types the Admin API can generate are missingFails extended I3 only
cbom-keycloak-product-fail-procurement-P5.cdx.jsonThe storage interface is missingFails procurement P5 only
cbom-keycloak-product-intended.cdx.jsonA design record for Keycloak 27.0 with ML-DSA-65Fails baseline I8 on every interface, and I3 to I5 where it repeats build-time literals; conforms to entry
legacy/cbom-keycloak-scanner-output.cdx.jsonUntargeted scanner output in CycloneDX 1.7Fails entry P1, P3, P4, P5 and P6
cbom-keycloak-deployment-configured.cdx.jsonExample Org's configured record. It cites the product recordConforms to the deployment profile
cbom-keycloak-deployment-configured-fail-literal.cdx.jsonpeer-defined kept at configuredFails I3, I4 and I5 on the database connection
cbom-keycloak-deployment-observed.cdx.jsonThe deployment observed from 18 to 25 October 2026, with an observation method per interface. It cites the configured record and the product recordConforms to the deployment profile
cbom-keycloak-deployment-observed-fail-unknown.cdx.jsonThe database group is unknown, because the observer had only pg_stat_sslFails baseline I3; conforms to entry. A record with gaps lands one depth down
cbom-keycloak-deployment-observed-fail-P1.cdx.jsonThe configured record it cites has changed sinceFails deployment P1 (hash mismatch) when the configured record is supplied
cbom-postgres-deployment-configured.cdx.jsonThe 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 peerInterfaceconforms to deployment disclosure v0.2
cbom-keycloak-deployment-observed-outside.cdx.jsonAn outside assessor's observation. The management port was not reachedP2 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.

FilePointed to byWhat it is
keycloak-26.7.3-sbom.cdx.jsoninterface-disclosure#R1, and each library's BOM-LinkCompanion SBOM of the image, CycloneDX 2.0. An illustrative subset of components, declared incomplete.
keycloak-26.7.3-vex.cdx.jsoninterface-disclosure#R2Vulnerability statements, CycloneDX 2.0: resolved, not affected, in triage. Illustrative identifiers, not CVEs; upstream Keycloak publishes no VEX.
keycloak-configuration-guidance.jsoninterface-disclosure#R5Who decides each value the product leaves open, and the Keycloak setting that decides it.
keycloak-pqc-roadmap.jsonpqc-migration#R2Planned 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

FileDescription
policies/policy-readiness-gap.policy.jsonExample 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.jsonExample 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.jsonThe 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.jsonExample 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.jsonThe 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.jsonThe algorithm-transition policy applied to the product record on 2026-10-25
examples/results/result-algorithm-transition-sso-prod-observed.jsonThe 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

FileDescription
validate_cbom.pyValidates 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.pyChecks 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.pyEvaluates CBOMs against a policy at a stated date and writes a policy result
compare_stages.pyLays the product, configured and observed records side by side, one row per interface, by following correspondsTo. It makes no judgement
cdx17_to_20.pyConverts a CycloneDX 1.6 or 1.7 CBOM to CycloneDX 2.0. Its docstring lists every conversion

Other files

FileDescription
claim-example.jsonA 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.jsonThe reports the Demo page renders. Generated by the validator; do not edit
profile-interface-disclosure.mdProse specification of the baseline
mapping-cyclonedx-spdx.mdThe 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.mdTreatment 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.

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:

PKIC CBOM Profiles Working Group ยท draft for comment.