Introduction
No prior knowledge of bills of materials is assumed. A buyer asks a question about one product. The product's CBOM cannot answer it. A profile changes that, by stating which facts the CBOM must contain. Every other section expands on a step in this example.
The problem, in one example
A vendor supplies Keycloak, an open-source identity server, as a container image, and with it a CBOM. Keycloak 26.7.3 is the example used throughout the methodology. From the CBOM you learn that the main HTTPS listener runs TLS 1.3 with the key exchange of the JDK 21 in the image (X25519 first), that tokens are signed with RS256 by default, and that the operator supplies the server certificate. Every statement in it is true.
Document A, as supplied
────────────────────────────────────────────────────────────
subject Keycloak 26.7.3 (container image)
stage implemented (the vendor's build record)
interfaces 11 declared
[1] TLS on the main listener (port 8443) service
protocol TLS 1.3
key exchange X25519 first (JDK 21 defaults)
encryption AES-256-GCM
authentication deployment-defined (the operator
supplies the server certificate)
[2] OIDC token issuance service
authentication RS256
... nine more: SAML, the plaintext HTTP listener,
the connections to the database, directory, mail
server and identity providers, the cluster
transport and the realm key storage
not declared the Admin REST API and Admin Console
the management listener (port 9000)
Three months later a weakness is published that affects the interfaces an administrator uses to manage the server. The question that lands on your desk is whether this product is affected, and if it is, which of the several hundred instances you operate.
Document A cannot answer. It describes the interfaces that serve users and connect to other systems. It says nothing about the interfaces an administrator connects to. The vendor was not careless. It described eleven interfaces accurately and in full. Nothing required it to declare the management interfaces as well.
A CBOM format defines what a document may record. It does not define what a document must record. A vendor that answers a request for a CBOM with Document A has complied with the format and left the buyer no better off.
Document A is not an unusual document. It is the ordinary result of asking a supplier for a CBOM without saying what the CBOM is for.
Why asking for everything does not work
The obvious remedy is to ask for everything, and it makes matters worse. A large product performs thousands of cryptographic operations. A document listing all of them buries the two or three facts that any particular decision depends on. Covering everything does not make a document useful, and in practice no supplier would produce such a document.
There is no absolute standard of completeness for a CBOM. Completeness is relative to a purpose. The question "does this document contain everything?" therefore has no answer. The question "does it contain what this decision needs?" does have one. That second question can be answered only if the decision has first been written down in a form that a machine, and not only a person, can check.
What a profile is
A profile is a short list of rules stating which attributes a CBOM must carry to support one stated decision, for one stated reader. It is a minimum reporting requirement. It is not a schema, and it is not a format.
The example used throughout: the Interface Disclosure Baseline
Every profile begins by naming who reads the document and what they are deciding. Without a named reader and a named decision, there is no principled point at which to stop adding rules.
| The Interface Disclosure Baseline, v0.9 | |
|---|---|
| Reader | An operator or purchaser holding a product it did not build and cannot inspect, keeping a cryptographic inventory across an estate. |
| Decision | When a weakness is published against an algorithm, a protocol version or a library, which of the deployed interfaces are affected. And, set beside the record from last quarter, what has changed. |
| Actions | Record the interfaces and take no further action. Act on an affected interface by reconfiguring, upgrading or isolating it. Ask the producer for a fuller disclosure. Reject the submission as insufficient to inventory. |
Naming the four actions is what allows the rest of the profile to be justified or challenged. A reader with only one available action is not making a decision. A profile written for such a reader has no test for whether it asks for the right things.
The baseline has twenty-three rules, of three kinds. Product rules constrain the document as a whole. Interface rules constrain each interface. Reference rules constrain the pointers the document carries to context it does not contain.
Product rules: constraints on the set of interfaces
| # | The document must | Level | Because |
|---|---|---|---|
| P1 | declare at least one cryptographic interface | MUST | A CBOM describing no interface answers nothing. |
| P2 | declare at least one management interface, or state that there is none | MUST | This is the rule Document A fails. A hardware token with no configuration surface hides nothing by not having one. A statement that there is no management interface therefore satisfies the rule. Saying nothing does not. |
| P3 | identify the subject it describes | MUST | An unidentified record cannot be matched to a deployment, or compared with the same product's record from last quarter. |
| P4 | state how complete its list of interfaces is | MUST | Otherwise a missing interface is uninterpretable. It could mean the interface does not exist, or that the producer chose not to list it. |
| P5 | declare its subject type, product or deployment | MUST | A vendor writes a product record. An operator writes a deployment record. The reader needs to know which one it holds. P3 depends on the answer: a product is identified by a package URL, and a deployment by a tag URI (RFC 4151), such as tag:example.org,2026:deployment/sso-prod. |
| P6 | declare one lifecycle stage for the whole document | MUST | A value means something different at each stage. At implemented it is the product's default as shipped. At configured it is the set the deployment permits. At observed it is the set seen during the observation window. One document therefore carries one stage. |
P1 and P2 catch omissions, which no rule about a single attribute can do. A document can describe its service interface impeccably, pass every attribute rule, and still fail P2.
Interface rules: constraints on each one
These apply uniformly to every interface the document declares, however many that is.
| # | Attribute | Level | What it answers |
|---|---|---|---|
| I1 | protocol | MUST | TLS, SSH, IPsec, and similar |
| I2 | protocolVersion | MUST | Which version, since an advisory usually names one |
| I3 | keyExchange | MUST | How the session key is agreed |
| I4 | encryption | MUST | What protects the traffic once the key is agreed |
| I5 | authentication | MUST | How each end proves who it is |
| I6 | endpointRoles | MUST | Who is at each end, so the interface can be located in a topology |
| I7 | interfaceType | MUST | One of five values, among them service, management and interconnect. P2 is checked against this |
| I8 | lifecycleStage | MUST | Whether the value was implemented, configured or observed, which is how much weight the reader should give it. It must agree with the stage the document declares under P6. The baseline does not accept intended |
| I9 | implementationPurl | MUST | Which library implements it, so an advisory against that library can be matched. This is the only rule in the profile that a producer may answer by withholding the value |
| I10 | keyWrapping | MUST | On a storage interface: how stored keys are protected. Keycloak stores its realm key material in the database in plaintext |
| I11 | defaultState | SHOULD | At implemented: whether the interface is enabled or disabled as shipped. Keycloak's plaintext HTTP listener is disabled by default |
Some products do not fix a value themselves. Keycloak does not choose its server certificate; the operator does. For this reason I3 to I5 accept a literal value in place of an algorithm. none means that no algorithm does this job, and it is accepted at any stage. deployment-defined means that the operator chooses. peer-defined means that the other endpoint decides, or that the value is negotiated with it, as on the connection Keycloak opens to its database. These two literals are accepted only at implemented, because a deployment record knows the answer. The reason is set out in decision 0012: a rule that no honest subject can satisfy is wrong, not strict.
Reference rules: pointers to context
A CBOM does not carry everything a reader needs. It points to some things instead: the software bill of materials, the vendor's vulnerability statements, the advisory feed. The reference rules require those pointers. The validator checks the pointer and never the target. See Context Pointers.
| # | The document points to | Level | Because |
|---|---|---|---|
| R1 | its software bill of materials (SBOM) | MUST | Product records only. The SBOM lists the components; the CBOM does not repeat it. |
| R2 | the vendor's vulnerability statements, or a statement that none are published | MUST | Product records only. Upstream Keycloak publishes no VEX statements, so its record says not-published. |
| R3 | an advisory source and its access protocol | SHOULD | For Keycloak, the OSV API. The reader queries it with the library package URLs from I9. |
| R4 | a security contact | SHOULD | The reader needs to know where to report a problem. |
| R5 | configuration guidance, on any interface where I3 to I5 is deployment-defined | MUST | If the operator chooses the value, the operator needs to know where to set it. |
| R6 | a design document | MAY | Design intent is context, not a stage of the record. |
Twenty-three rules is the entire profile. It is short on purpose. It names the minimum needed to support one decision and then stops. Because the profile is short, a vendor can satisfy it and a buyer can insist on it.
What the profile does not say
No rule asks whether the cryptography is any good. Whether a product is post-quantum ready is not a fact about the product. It is a judgement made against criteria that change over time, and it is kept outside the document, in versioned policy. The CBOM carries the facts. The policy reaches the verdict. The verdict is dated so that a reader can tell which criteria produced it.
Evaluating two documents against the profile
Document A is the one above, published as cbom-keycloak-product-fail-P2.cdx.json. Document B is the vendor's full build record, cbom-keycloak-product.cdx.json. It declares all thirteen interfaces, including the Admin REST API and the management listener.
| Rule | Document A | Document B |
|---|---|---|
| P1 at least one cryptographic interface | passes | passes |
| P2 a management interface, or a statement that there is none | FAILS | passes |
| P3 the subject is identified | passes | passes |
| P4 the interface list states its completeness | passes | passes |
| P5, P6 subject type and one lifecycle stage | passes | passes |
| I1 to I11 on every declared interface | passes (11 interfaces) | passes (13 interfaces) |
| R1 to R6 pointers to context | passes | passes |
| Verdict | does not conform | conforms |
The Demo shows the reports the reference validator produced for both records, and for the other Keycloak records: the four disclosure outcomes, a design record, the deployment records and the CycloneDX 1.7 legacy form.
The four disclosure outcomes
One refinement recurs throughout the methodology. Suppose the vendor does not want to name the library behind the OIDC interface. The record then carries a marker saying the value is withheld, and rule I9 accepts that, because I9 is the one rule in this profile marked withholdable. The example cbom-keycloak-product-disclosure-states.cdx.json does this.
The marker matters to the reader of the document. A withheld value is a position the producer has taken, and the reader can challenge it in a negotiation. An absent value could mean anything. For this reason the methodology distinguishes four outcomes for any attribute. The CBOM formats distinguish only two: present and absent.
| Outcome | What it says about the producer | Satisfies a MUST rule? |
|---|---|---|
| value | It knows the value and has published it | Yes |
| withheld | It knows the value and has decided not to publish it | Only where the rule is marked withholdable |
| unknown | It does not know the value | No, but it is reported separately from an attribute that is simply missing |
| undeclared | Nothing was said, and the reader cannot tell which of the other three applies | No |
In the same example the cluster transport declares its authentication unknown, and the SAML interface leaves its encryption undeclared. The record therefore fails I5 and I4, and the report names each outcome. The first three outcomes can be acted on. The fourth can only be guessed at. A buyer who cannot tell a deliberate omission from an oversight has no basis for asking the supplier to fix it.
Where to go next
Everything above can be understood without the rest of the documentation. The other sections expand on it.
Demo
Read the validator's reports for the Keycloak records, rule by rule, including the four disclosure outcomes and the deployment joins.
Overview
What each section covers, and two suggested routes through the material, depending on why you are reading.
Challenges
Why CBOMs behave the way Document A did, and what SBOM adoption already established about it.
Method
The twelve steps for defining a profile, if you are here to write one rather than to read one.
Terms is a glossary and sits in the Reference group. Use it to look up an unfamiliar word. It is not intended to be read first.
The methodology works a single example all the way through: Keycloak 26.7.3, expressed in CycloneDX 2.0, with a CycloneDX 1.7 legacy form. The material is a draft for comment from the PKIC CBOM Profiles Working Group. Its positions are settled provisionally and can be reopened.