Documentation

3.3.1 Certificate Inventory

A CBOM Secure deployment involves several distinct certificates and key pairs with different purposes and lifecycles. Confusing them is the main source of certificate incidents, so the inventory is set out here before any procedure.

External server certificate: presented by the reverse proxy to browsers and to remote sensors. Must name every address in use. Customer-supplied in production.
Internal service certificates: where service-to-service TLS is enabled within the platform network.
Collector token signing key and certificate: used to sign the tokens that authorise sensor submissions. Versioned, with the previous version retained so in-flight tokens validate across a rotation.
Per-host certificates: each registered host has its own certificate, held in the host inventory, against which the collector verifies that host submissions.
Per-host signing and key-exchange key pairs: used by the host to sign discovered material and to establish the shared key that encrypts the payload.
Identity provider certificates: the provider signing certificate, and any federation certificates for SAML or OIDC.
Credential encryption key: not a certificate, but belongs in this inventory because it has the same handling requirements and the same consequences if lost. Credentials encrypted under a lost key are unrecoverable and must be re-entered.

3.3.2 Installer-Generated Certificates

The setup helper generates a self-signed external certificate. It is suitable for evaluation only.
Collector signing keys and per-host material are generated by the platform as part of normal host registration and token issuance. These are not customer-supplied and require no manual step.
Where a self-signed external certificate is in use, every sensor host must be configured to trust it explicitly. Disabling verification instead is not an acceptable substitute and should not be documented as an option.

3.3.3 Bring Your Own Certificates

Production deployments supply their own external certificate. There are two scopes, and they have very different effort profiles.

External only: replace the reverse proxy certificate, leave internal and platform-generated material as issued. This is the common case and is a short procedure.
All certificate material: replace internal service certificates as well, from the customer own certificate authority. Larger effort, needed where policy requires all TLS to chain to an enterprise CA.

Procedure for the external certificate:

Decide the full name set — every hostname and IP that users and sensors will use.
Generate a key pair and certificate signing request with that name set.
Have it issued by the enterprise or public certificate authority.
Install the leaf, the full chain and the private key at the paths the proxy configuration expects, with file permissions restricting the key to the service account.
Restart the proxy and verify from a browser, and separately from a sensor host — the sensor is the one that will fail if a name is missing from the certificate, and it will fail silently from the portal point of view.
Confirm ingestion still succeeds after the change, before considering the change complete.

3.3.4 Collector Token and Signing Key Rotation

Signing keys are versioned. Creating a new signing key makes it active for newly issued tokens.
The previous signing certificate remains retrievable so that tokens already issued continue to validate until they expire. Do not remove the previous certificate until the longest-lived token issued under it has expired.
Host tokens are issued with a bounded lifetime and rotated per deployment. The configured lifetime determines how long a decommissioned host can still submit.
Revoking a host is done by removing the host from the inventory, which removes the certificate its submissions are verified against. This takes effect immediately and does not depend on token expiry, which makes it the correct step in an offboarding procedure.

3.3.5 Renewal Procedures

External certificate: schedule renewal well before expiry. Follow the same procedure as initial installation, and validate from both a browser and a sensor host afterwards.
Identity provider federation certificates: a SAML or OIDC signing certificate expiring at the provider end breaks login with no change on the platform side. Track its expiry as a platform dependency, not as somebody else problem.
Client secrets for OIDC: these expire. Section 4.3 covers the maintenance procedure.
Per-host material: renewed as part of redeployment. A host that has not been redeployed within the token lifetime stops submitting; the alert in 3.2.4 on ingestion dropping to zero for a known host is what catches this.
Set calendar reminders for every dated item in the inventory, and keep a table of what expires, how it is renewed, and what breaks when it lapses.

3.3.6 External Certificate — Step by Step

3.3.3 sets out the procedure in outline. This is the same procedure with the commands, the checks at each stage, and the mistakes each check catches.

What the certificate must carry

Requirement	Detail
Subject alternative names	Every address people and agents will use — the public name, any internal alias, and the address if anything connects by address. The common name is not consulted by modern clients; only the SAN list is.
Key type	RSA 2048 or larger, or ECDSA P-256 or larger.
Signature	SHA-256 or stronger.
Extended key usage	Server authentication.
Validity	Within whatever maximum your clients accept.
Chain	The leaf plus every intermediate, in order.

! The name in the certificate and the platform's configured public address must match. Sign-in redirects are validated against the configured address, so a mismatch is not a browser warning that can be clicked through — authentication fails outright. Set the public address and issue the certificate for the same name.

Obtaining it

Generate the key and request on a machine you control, not on the certificate authority:

openssl req -new -newkey rsa:2048 -nodes \
  -keyout cbom.key \
  -out cbom.csr \
  -subj "/C=US/O=Example Corp/CN=cbom.example.com" \
  -addext "subjectAltName=DNS:cbom.example.com,DNS:cbom-internal.example.com"

Confirm the request carries the names before submitting it — a request missing a SAN produces a certificate missing it, and you find out at the end:

openssl req -in cbom.csr -noout -text | grep -A2 "Subject Alternative Name"

Submit to your internal CA or public CA, and ask for the full chain in PEM.

Assembling the chain

The proxy wants one file: the leaf first, then each intermediate in issuing order, root last or omitted.

cat leaf.pem intermediate.pem > cert.pem

Order matters and the wrong order fails selectively. A chain in the wrong order is accepted by browsers that already hold the intermediate and rejected by clients that do not — so it works on the workstation it was tested from and fails for agents. Verify before installing:

openssl verify -untrusted intermediate.pem leaf.pem
openssl crl2pkcs7 -nocrl -certfile cert.pem | openssl pkcs7 -print_certs -noout

The second command lists the chain in file order. Read it and confirm each certificate's issuer is the subject of the next.

Confirm the key matches the certificate — these two must print the same hash:

openssl x509 -noout -modulus -in cert.pem | openssl sha256
openssl rsa  -noout -modulus -in cbom.key | openssl sha256

Installing it

Place cert.pem and key.pem in the certificate directory the deployment mounts into the proxy, keeping those file names.
Set the private key readable only by its owner: chmod 600 key.pem.
Reload rather than restart — a reload picks the certificate up without dropping connections:

docker compose exec nginx nginx -t        # validate first
docker compose exec nginx nginx -s reload

Verify from a machine that is not the platform host, so the client's own trust store is exercised:

openssl s_client -connect cbom.example.com:443 -servername cbom.example.com < /dev/null

Check the returned chain, the verify result, and the dates.

Sign in through a browser. The round trip through the identity provider exercises the redirect handling, which a command-line check does not.

The identity provider reads the same certificate in the shipped deployment, so it is covered by the same step.

Encrypted private keys

An encrypted key cannot be used — the proxy would need the passphrase at every start, with nowhere safe to put it. Decrypt before installing, and protect the file with permissions:

openssl rsa -in encrypted.key -out key.pem
chmod 600 key.pem

Converting from PKCS#12

Certificates issued through a Windows CA usually arrive as a .pfx:

openssl pkcs12 -in cbom.pfx -clcerts -nokeys  -out leaf.pem
openssl pkcs12 -in cbom.pfx -cacerts -nokeys  -out chain.pem
openssl pkcs12 -in cbom.pfx -nocerts -nodes   -out key.pem
cat leaf.pem chain.pem > cert.pem

Check chain.pem — PKCS#12 does not guarantee chain order, and this is the most common source of a wrongly ordered chain.

3.3.7 Renewal and Expiry Monitoring

Set a reminder for 30 days before expiry, in a calendar someone reads. An expired external certificate stops the console, the API and every agent submission at once. It is the most predictable outage this platform has and the most common.

Renewal is the installation procedure again, with one addition: keep the previous certificate and key until the new one is confirmed working, so rolling back is a file copy and a reload.

If the key is unchanged, only cert.pem needs replacing. Generating a fresh key each renewal is better practice and costs one extra command.

# How long have you got?
openssl x509 -in cert.pem -noout -enddate

# Across the whole estate, from a monitoring host
echo | openssl s_client -connect cbom.example.com:443 -servername cbom.example.com 2>/dev/null \
  | openssl x509 -noout -enddate

The platform will also discover and report on its own certificate once an HTTPS discovery task includes its address. Pointing the product at itself is a reasonable thing to do and gives you expiry alerting through the notification engine for free.

3.3.8 Certificates Behind an Outer Proxy

Where an existing load balancer or WAF fronts the platform, the externally trusted certificate belongs on that device. The platform's own proxy still needs a certificate — the hop between them is still TLS — but it can be self-signed or internally issued, since only the outer device validates it.

Set the public addresses to the outer device's name. The inner certificate's name does not need to match, provided the outer device is not verifying it.

3.3.9 Platform-Managed Certificates

Certificate	Lifecycle
Collector token signing	Generated by the platform and versioned, with the previous version retained so tokens in flight still validate across a rotation
Per-host certificates	Issued at host registration; re-issued by re-registering the host
Per-host key pairs	Generated on the host
Identity provider signing	Managed in the identity provider; rotating it requires re-establishing any federation trust

None of these needs an operator procedure in normal operation. The one to know about is the identity provider's signing certificate: rotating it invalidates the trust a federated identity provider has in it, so a rotation there is coordinated with whoever administers the corporate directory.

3.3.10 The Credential Encryption Key

Not a certificate, but it belongs in this section because losing it has the worst consequences of anything here.

Every target credential the platform stores is encrypted under this key. Lose it and every stored credential is unrecoverable — not merely unreadable, but gone, and each one has to be re-entered by hand against every host and integration that held one.

Rule	Why
Back it up separately from the database	A backup encrypted under a key that is only in the same backup protects nothing
Store it in a credential manager or an HSM	It is the single highest-value secret in the deployment
Keep it identical across nodes	A second node with a different key cannot read the first node's credentials
Restore it alongside the database	A restore without it gives a working platform with no usable credentials

Rotating it means re-encrypting every stored credential, so it is not a routine operation. Treat it as something to protect rather than something to rotate.

3.3.11 Certificate Troubleshooting

Browser warns that the certificate is not trusted. The chain is incomplete or in the wrong order. Check with openssl s_client from a machine that has not visited the site before — a browser that already cached the intermediate hides the fault.

Agents fail to submit while browsers work. The classic incomplete-chain symptom. Browsers fetch missing intermediates; the agents' TLS stack does not.

Sign-in fails with a redirect error after installing a certificate. The certificate name and the configured public address disagree. Fix the configured address, or reissue for the name in use.

The proxy will not reload. nginx -t first. A malformed certificate or a key that does not match the certificate is the usual cause — check the modulus hashes above.

The certificate was replaced and the old one is still served. The proxy was not reloaded, or the files were written somewhere other than the mounted directory. Confirm with openssl s_client rather than by looking at the file.

Everything works internally and fails from outside. Two different addresses, and only one is in the SAN list.

CBOM Secure

3.3 Certificate Management