Documentation

1. Purpose

This guide describes how to configure the CBOM Discover_Keystore sensor to discover and inventory PKCS#12 (.p12, .pfx) keystores across your infrastructure.

PKCS#12 is a binary archive format that bundles a private key together with its certificate chain inside a single password-protected container. It is widely used in Java application servers, web servers, CI/CD pipelines, and certificate management workflows.

The Discover_Keystore sensor performs read-only scanning of configured filesystem paths and extracts the following cryptographic metadata from each PKCS#12 file it locates:

Certificate subject and issuer distinguished names (DN)
Certificate serial number and validity period (not-before / not-after)
Public key algorithm (RSA, EC, DSA) and key size in bits
Signature algorithm (e.g., SHA256withRSA)
Subject Alternative Names (SANs)
Key usage and extended key usage extensions
Certificate fingerprints (SHA-1, SHA-256)

The sensor never reads, stores, or transmits private key material. The keystore password is used solely to open the container and enumerate entries; private key bytes are explicitly excluded from all data collection.

This guide covers:

Locating existing PKCS#12 files on your hosts
Exporting a PKCS#12 from a Java KeyStore (JKS) using keytool
Exporting a PKCS#12 from PEM files using OpenSSL
Granting the CBOM sensor the minimum filesystem permissions required
Configuring the Discover_Keystore sensor YAML
Validating the integration and troubleshooting common errors

2. Prerequisites

Before starting, ensure the following are in place:

CBOM platform access — You have credentials to log in to the CBOM portal and permissions to create or edit sensor configurations.
Sensor host access — The Discover_Keystore sensor agent is installed on the host(s) where PKCS#12 files reside, or on a host with network-mounted paths to those files.
PKCS#12 files present — At least one .p12 or .pfx file exists in the target scan directories.
Keystore passwords known — You have the export/store passwords for every PKCS#12 file the sensor will open. These are supplied to the sensor as secrets; they are not logged or persisted in plaintext.
Java 8+ or OpenSSL 1.1+ — Required only if you need to create or convert keystores before scanning. If keystores already exist in PKCS#12 format, no Java or OpenSSL is needed on the sensor host.
Operating system — Linux (RHEL 7+, Ubuntu 18.04+) or Windows Server 2016+. The sensor agent supports both.
Service account — A dedicated OS-level user account (cbom-sensor) with read-only access to the scan directories. Do not run the sensor as root or Administrator.

3. Locate and Prepare PKCS#12 Files

3.1 Discover Existing PKCS#12 Files

Before configuring the sensor, identify where PKCS#12 files are stored on your hosts. Run the following command as a user with sufficient read permissions:

find /opt/certs /etc/ssl /var/lib/certs -type f \( -name "*.p12" -o -name "*.pfx" \) 2>/dev/null

For a broader system-wide search (may be slow on large filesystems):

find / -type f \( -name "*.p12" -o -name "*.pfx" \) \
  -not -path "/proc/*" \
  -not -path "/sys/*" \
  2>/dev/null

Record the directories that contain PKCS#12 files. These paths will be entered into the sensor configuration in Section 6.

3.2 Verify a PKCS#12 File is Readable

Confirm that a discovered file is a valid, password-protected PKCS#12 bundle before configuring the sensor:

openssl pkcs12 -info -in /opt/certs/server.p12 -noout -passin pass:changeit

A successful response lists the certificate bag attributes without printing key material. A Mac verify error indicates an incorrect password.

4. Export a PKCS#12 from a Java KeyStore (JKS)

If your certificates are currently stored in a JKS keystore, export them to PKCS#12 format so the sensor can parse them.

4.1 Export All Entries from JKS to PKCS#12

keytool -importkeystore \
  -srckeystore keystore.jks \
  -srcstoretype JKS \
  -srcstorepass <jks-store-password> \
  -destkeystore out.p12 \
  -deststoretype PKCS12 \
  -deststorepass <p12-store-password> \
  -noprompt

Replace <jks-store-password> with the source JKS password and <p12-store-password> with the password you want to set on the output PKCS#12 file.

4.2 Export a Single Alias

If the JKS contains multiple aliases and you only want one certificate-key pair:

keytool -importkeystore \
  -srckeystore keystore.jks \
  -srcstoretype JKS \
  -srcstorepass <jks-store-password> \
  -srcalias myserver \
  -destkeystore myserver.p12 \
  -deststoretype PKCS12 \
  -deststorepass <p12-store-password> \
  -destalias myserver \
  -noprompt

4.3 Verify the Exported File

keytool -list -v \
  -keystore out.p12 \
  -storetype PKCS12 \
  -storepass <p12-store-password>

Confirm the certificate subject, issuer, and validity dates appear in the output.

5. Export a PKCS#12 from PEM Files Using OpenSSL

If your certificate and private key are stored as separate PEM files, combine them into a PKCS#12 bundle:

5.1 Bundle Certificate and Key

openssl pkcs12 -export \
  -in cert.pem \
  -inkey key.pem \
  -out bundle.p12 \
  -name "myserver" \
  -passout pass:<p12-store-password>

5.2 Include the Full Certificate Chain

If you have intermediate and root CA certificates in a separate file (chain.pem), include them with -certfile:

openssl pkcs12 -export \
  -in cert.pem \
  -inkey key.pem \
  -certfile chain.pem \
  -out bundle-with-chain.p12 \
  -name "myserver" \
  -passout pass:<p12-store-password>

5.3 Verify the Bundle

openssl pkcs12 -info -in bundle.p12 -noout -passin pass:<p12-store-password>

The output should list Certificate bag and PKCS7 Encrypted data sections without errors.

6. Grant Read-Only Filesystem Permissions to the Sensor Account

The CBOM sensor must run as a dedicated, least-privilege OS account. Granting this account read access to keystore directories is the only permission change required.

6.1 Create the Sensor Service Account (Linux)

sudo useradd --system --no-create-home --shell /sbin/nologin cbom-sensor

6.2 Grant Read Access to Keystore Directories

sudo setfacl -R -m u:cbom-sensor:rX /opt/certs
sudo setfacl -R -m u:cbom-sensor:rX /etc/ssl/private

If ACLs are not available, add cbom-sensor to the group that owns the keystore directory:

sudo usermod -aG certsgroup cbom-sensor

6.3 Verify Access

Switch to the sensor account and confirm it can list and read keystores:

sudo -u cbom-sensor ls -l /opt/certs/
sudo -u cbom-sensor openssl pkcs12 -info -in /opt/certs/server.p12 \
  -noout -passin pass:<p12-store-password>

Both commands must succeed without permission errors before proceeding.

7. Configure CBOM Sensor

Add a Discover_Keystore sensor configuration block to your CBOM sensor configuration file. By default this file is located at /etc/cbom/sensors.yaml on Linux or C:\ProgramData\CBOM\sensors.yaml on Windows.

sensors:
  - name: Discover_Keystore
    enabled: true
    schedule: "0 2 * * *"          # Run daily at 02:00 local time (cron syntax)
    options:
      scan_paths:
        - /opt/certs
        - /etc/ssl/private
        - /var/lib/tomcat/conf
      file_extensions:
        - .p12
        - .pfx
      recursive: true
      follow_symlinks: false
      max_file_size_mb: 50         # Skip files larger than 50 MB
      keystore_credentials:
        - path: /opt/certs/server.p12
          password_env: CBOM_KS_SERVER_PASSWORD
        - path: /opt/certs/wildcard.pfx
          password_env: CBOM_KS_WILDCARD_PASSWORD
        - path: /var/lib/tomcat/conf/keystore.p12
          password_env: CBOM_KS_TOMCAT_PASSWORD
      default_password_env: CBOM_KS_DEFAULT_PASSWORD   # Fallback for unlisted files
      exclude_paths:
        - /opt/certs/archive
        - /opt/certs/expired
      timeout_seconds: 120
    output:
      format: cbom-json
      destination: platform          # Send results to the CBOM platform API

Set each referenced environment variable on the host where the sensor agent runs. Do not embed passwords directly in the YAML file.

# /etc/cbom/sensor.env  (loaded by the cbom-agent systemd unit)
CBOM_KS_SERVER_PASSWORD=<server-p12-password>
CBOM_KS_WILDCARD_PASSWORD=<wildcard-pfx-password>
CBOM_KS_TOMCAT_PASSWORD=<tomcat-p12-password>
CBOM_KS_DEFAULT_PASSWORD=<default-fallback-password>

Restrict access to the environment file:

sudo chown root:cbom-sensor /etc/cbom/sensor.env
sudo chmod 640 /etc/cbom/sensor.env

Reload and restart the CBOM agent after editing the configuration:

sudo systemctl daemon-reload
sudo systemctl restart cbom-agent
sudo systemctl status cbom-agent

8. Validation

After restarting the sensor agent, confirm the integration is working correctly.

Check agent logs — Verify that the sensor started without errors:

sudo journalctl -u cbom-agent -n 100 --no-pager

Look for lines similar to:

INFO  Discover_Keystore: scan started, paths=[/opt/certs, /etc/ssl/private, /var/lib/tomcat/conf]
INFO  Discover_Keystore: found 3 PKCS#12 file(s)
INFO  Discover_Keystore: scan complete, 3 assets published

Trigger a manual scan — Run the sensor immediately without waiting for the scheduled cron time:
```
sudo cbom-ctl sensor run Discover_Keystore
```
Verify assets in the CBOM portal — Log in to the CBOM platform, navigate to Assets > Certificates, and confirm that the certificates from your PKCS#12 files appear with correct subject, expiry, and key algorithm metadata.
Confirm no private key data was collected — In the CBOM portal, open any discovered certificate asset and verify that the asset record contains only public metadata (subject, issuer, serial, validity, public key algorithm/size). There must be no private key field.
Check for skipped files — If a file was skipped due to a wrong password, the log will include a warning:
```
WARN  Discover_Keystore: could not open /opt/certs/legacy.p12 — MAC verify failure, check password
```
Update the credential mapping in sensors.yaml and re-run the scan.

9. Common Errors and Resolution

Error 1: MAC verify failure / incorrect password

ERROR Discover_Keystore: failed to open /opt/certs/server.p12 — MAC verify failure

Cause: The password supplied via the environment variable does not match the PKCS#12 file's store password. This can also occur if the file was created with a legacy encryption scheme incompatible with the OpenSSL version on the sensor host.

Fix: Confirm the correct password by running openssl pkcs12 -info -in server.p12 -noout -passin pass:<password> manually. If the file uses legacy RC2/3DES encryption (older keytool defaults), re-export it with modern encryption:

openssl pkcs12 -in legacy.p12 -passin pass:<old-password> \
  | openssl pkcs12 -export -out modern.p12 -passout pass:<new-password>

Error 2: Permission denied when reading keystore file

ERROR Discover_Keystore: cannot read /etc/ssl/private/server.p12 — permission denied

Cause: The cbom-sensor OS account does not have read permission on the file or its parent directory.

Fix: Verify current permissions with ls -la /etc/ssl/private/server.p12. Grant read access using ACLs or group membership as described in Section 6. Then re-run the sensor:

sudo cbom-ctl sensor run Discover_Keystore

Error 3: Sensor reports 0 assets found despite files being present

INFO  Discover_Keystore: scan complete, 0 assets published

Cause: The scan_paths in sensors.yaml do not match the actual filesystem paths where .p12/.pfx files are stored, or file_extensions is misconfigured (e.g., missing the leading dot).

Fix: Manually verify the scan path and extension configuration:

find /opt/certs /etc/ssl/private -type f \( -name "*.p12" -o -name "*.pfx" \)

Compare the output with the scan_paths and file_extensions values in sensors.yaml. Correct any mismatches, reload the configuration, and re-run the sensor:

sudo systemctl restart cbom-agent
sudo cbom-ctl sensor run Discover_Keystore

10. Security Recommendations

Use environment variables for all passwords. Never embed keystore passwords as plaintext values inside sensors.yaml. Reference them via password_env and store them in a restricted environment file or a secrets manager such as HashiCorp Vault or AWS Secrets Manager.
Run the sensor as a dedicated least-privilege account. The cbom-sensor account should have read-only access strictly limited to the directories containing keystores. It must not have write access, sudo rights, or an interactive login shell.
Restrict the environment file permissions. Set the sensor environment file to mode 640 owned by root:cbom-sensor. This prevents other system users from reading keystore passwords.
Rotate PKCS#12 store passwords periodically. Treat keystore passwords as secrets subject to your organization's secret rotation policy. When rotating, update the environment variable and restart the sensor agent to pick up the new value.
Exclude archived and expired keystores from scan paths. Adding stale directories to exclude_paths reduces noise in CBOM reports and prevents the sensor from attempting to open keystores whose passwords may no longer be known. Maintain a separate remediation workflow for expired certificates discovered during historical scans.

11. Conclusion

The CBOM Discover_Keystore sensor provides continuous, read-only visibility into PKCS#12 keystores across your infrastructure, extracting certificate and public key metadata without ever touching private key material. By following this guide — locating or exporting keystores, granting minimal filesystem permissions, and supplying passwords through environment variables — you can bring all PKCS#12 assets into your Cryptographic Bill of Materials within minutes. Once configured, the sensor runs on a schedule and automatically surfaces expiring certificates, weak key sizes, and deprecated signature algorithms through the CBOM platform dashboard.

CBOM Secure

PKCS#12 / PFX Keystore Setup Guide for CBOM Keystore Sensor