Java KeyStore (JKS) Setup Guide for CBOM Keystore Sensor
1. Purpose
The CBOM Keystore Sensor (Discover_Keystore) scans Java KeyStore (JKS) files on target hosts and extracts cryptographic asset metadata for inclusion in the Cryptographic Bill of Materials (CBOM). JKS is Java's native proprietary keystore format, used extensively in Java-based applications, application servers (Tomcat, JBoss, WebSphere), and middleware to store:
PrivateKeyEntry — private keys paired with their certificate chains
TrustedCertificateEntry — trusted CA or peer certificates
The sensor operates in read-only mode. It does not modify, export, or delete any keystore content. This guide covers:
Locating JKS files on the target filesystem
Verifying keystore contents using
keytoolConfiguring read-only access for the CBOM sensor
Providing keystore passwords securely to the sensor
Validating sensor connectivity and data ingestion
Note: The JKS format is deprecated since JDK 9. Oracle recommends migrating to PKCS12. The CBOM sensor supports both formats; see the PKCS12 Setup Guide for migration guidance.
2. Prerequisites
Before configuring the CBOM Keystore Sensor for JKS discovery, ensure the following are in place:
JDK 8 or later is installed on the host where keystores reside. The
keytoolutility (bundled with the JDK) is required for inspection and validation.CBOM Agent (version 2.4.0 or later) is installed on the target host or a host with filesystem access to the JKS files.
Keystore file paths are known or discoverable. JKS files typically carry the
.jksor.keystoreextension.Keystore passwords are available. The sensor requires the store password to enumerate entries. Key passwords (if different from the store password) are not required for metadata-only discovery.
Read-only filesystem access to all JKS files the sensor will scan. The OS user running the CBOM agent must have read permission on each keystore file.
CBOM platform credentials — a valid API token for the CBOM platform to which the sensor will report. Contact your CBOM administrator if you do not have one.
Network connectivity from the agent host to the CBOM platform endpoint on port
443(HTTPS).
3. Locate and Inventory JKS Files
Before configuring the sensor, identify all JKS keystores on the target system. This section covers filesystem discovery and manual inspection.
3.1 Locate JKS Files on the Filesystem
Run the following command as a user with sufficient filesystem privileges (typically root or a dedicated service account):
find /opt -name "*.jks" -o -name "*.keystore" 2>/dev/nullTo search across common application directories:
find /opt /etc /home /var/lib /usr/local \
\( -name "*.jks" -o -name "*.keystore" \) \
-type f 2>/dev/nullRecord all discovered paths. These will be provided to the sensor configuration in Section 6.
3.2 Inspect Keystore Contents with keytool
For each discovered keystore, list its entries to confirm the type and quantity of cryptographic material:
keytool -list -keystore /opt/app/conf/keystore.jks -storepass changeitTo display full certificate details for each entry:
keytool -list -v -keystore /opt/app/conf/keystore.jks -storepass changeitExample output:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 2 entries
Alias name: myserver
Creation date: Jan 15, 2024
Entry type: PrivateKeyEntry
Certificate chain length: 2
...
Alias name: trusted-ca
Creation date: Mar 10, 2023
Entry type: trustedCertEntry
...Note the alias names, entry types, and certificate details. The CBOM sensor will extract the same metadata automatically.
4. Configure a Dedicated OS Service Account
The CBOM agent should run under a dedicated, least-privilege OS account. This account must have read access to each JKS file but no write or execute permissions beyond what is operationally required.
4.1 Create the cbom-sensor User
sudo useradd --system --no-create-home --shell /sbin/nologin cbom-sensor4.2 Grant Read Access to JKS Files
For each keystore file identified in Section 3.1, grant read permission to the cbom-sensor user using ACLs (preferred) or group membership.
Using POSIX ACLs (recommended):
sudo setfacl -m u:cbom-sensor:r /opt/app/conf/keystore.jks
sudo setfacl -m u:cbom-sensor:r /opt/middleware/security/server.keystoreVerify the ACL was applied:
getfacl /opt/app/conf/keystore.jksAlternatively, using a shared group:
sudo groupadd keystoreReaders
sudo usermod -aG keystoreReaders cbom-sensor
sudo chown root:keystoreReaders /opt/app/conf/keystore.jks
sudo chmod 640 /opt/app/conf/keystore.jks4.3 Verify Read Access
Switch to the cbom-sensor user and confirm the keystore can be read:
sudo -u cbom-sensor keytool -list \
-keystore /opt/app/conf/keystore.jks \
-storepass changeitIf the command lists keystore entries without error, access is correctly configured.
5. Store Keystore Passwords Securely
The CBOM sensor requires the keystore store password to enumerate entries. Passwords must never be stored in plaintext within the sensor configuration file.
5.1 Using the CBOM Secret Store
The CBOM agent includes a local encrypted secret store. Register each keystore password as a named secret:
cbom-agent secret set jks_keystore_password "changeit"
cbom-agent secret set jks_server_keystore_password "s3cr3tP@ssw0rd"Secrets are stored encrypted on disk and referenced by name in the sensor configuration (see Section 6).
5.2 Using Environment Variables (Alternative)
If the CBOM agent is managed by a systemd unit, secrets can be injected via an EnvironmentFile:
Create the environment file with restricted permissions:
sudo touch /etc/cbom/jks-secrets.env
sudo chmod 600 /etc/cbom/jks-secrets.env
sudo chown cbom-sensor:cbom-sensor /etc/cbom/jks-secrets.envAdd the password variables:
JKS_STORE_PASS=changeit
JKS_SERVER_STORE_PASS=s3cr3tP@ssw0rdReference the file in the systemd unit:
[Service]
EnvironmentFile=/etc/cbom/jks-secrets.env6. Configure CBOM Sensor
Create or update the sensor configuration file at /etc/cbom/sensors/discover_keystore.yaml. The example below configures the Discover_Keystore sensor for JKS discovery across multiple keystore paths.
sensor:
name: Discover_Keystore
enabled: true
format: jks
cbom_platform:
endpoint: "https://cbom.example.com"
api_token: "${CBOM_API_TOKEN}"
organization_id: "org-abc123"
discovery:
keystores:
- path: "/opt/app/conf/keystore.jks"
store_password: "${secret:jks_keystore_password}"
alias_filter: [] # Empty = discover all aliases
entry_types:
- PrivateKeyEntry
- TrustedCertificateEntry
- path: "/opt/middleware/security/server.keystore"
store_password: "${secret:jks_server_keystore_password}"
alias_filter:
- "myserver"
- "trusted-ca"
entry_types:
- PrivateKeyEntry
filesystem_scan:
enabled: true
scan_roots:
- "/opt"
- "/etc"
- "/var/lib"
patterns:
- "*.jks"
- "*.keystore"
exclude_paths:
- "/opt/jdk"
- "/opt/cbom-agent"
max_depth: 10
follow_symlinks: false
schedule:
cron: "0 2 * * *" # Daily at 02:00 UTC
timeout_seconds: 3600
reporting:
include_certificate_metadata: true
include_key_algorithm: true
include_key_size: true
include_validity_dates: true
include_subject_dn: true
include_issuer_dn: true
include_serial_number: true
include_fingerprint: true
include_san: true
agent:
run_as_user: "cbom-sensor"
log_level: "INFO"
log_file: "/var/log/cbom/discover_keystore.log"Apply the configuration and reload the agent:
sudo cbom-agent config validate /etc/cbom/sensors/discover_keystore.yaml
sudo systemctl reload cbom-agent7. Validation
After configuring the sensor, confirm that discovery is functioning correctly.
Trigger a manual sensor run:
sudo cbom-agent sensor run Discover_Keystore --config /etc/cbom/sensors/discover_keystore.yamlCheck the sensor log for successful discovery messages:
tail -f /var/log/cbom/discover_keystore.logExpected log output:
[INFO] Discover_Keystore: Starting JKS discovery run
[INFO] Discover_Keystore: Processing keystore /opt/app/conf/keystore.jks
[INFO] Discover_Keystore: Found 2 entries (1 PrivateKeyEntry, 1 TrustedCertificateEntry)
[INFO] Discover_Keystore: Processing keystore /opt/middleware/security/server.keystore
[INFO] Discover_Keystore: Found 1 entries (1 PrivateKeyEntry)
[INFO] Discover_Keystore: Filesystem scan completed. 0 additional keystores found.
[INFO] Discover_Keystore: Reported 3 cryptographic assets to CBOM platform
[INFO] Discover_Keystore: Run completed successfully in 4.2sLog in to the CBOM platform and navigate to Assets > Keystores. Confirm that the discovered entries appear with correct alias names, algorithms, key sizes, and validity dates.
Verify the asset count matches the expected number of entries identified during the manual
keytool -listinspection in Section 3.2.
8. Common Errors and Resolution
Error 1: java.io.IOException: Keystore was tampered with, or password was incorrect
Cause: The store password provided in the sensor configuration does not match the keystore's actual password, or the keystore file is corrupted.
Resolution:
Verify the password manually:
keytool -list -keystore /opt/app/conf/keystore.jks -storepass <your-password>If the password is correct but the error persists, the keystore may be corrupt. Verify file integrity:
md5sum /opt/app/conf/keystore.jksUpdate the secret in the CBOM secret store if the password has changed:
cbom-agent secret set jks_keystore_password "new-correct-password"Error 2: Permission denied: /opt/app/conf/keystore.jks
Cause: The OS user running the CBOM agent (cbom-sensor) does not have read permission on the keystore file.
Resolution:
Check current file permissions:
ls -la /opt/app/conf/keystore.jks
getfacl /opt/app/conf/keystore.jksGrant read access using ACL:
sudo setfacl -m u:cbom-sensor:r /opt/app/conf/keystore.jksConfirm fix:
sudo -u cbom-sensor keytool -list -keystore /opt/app/conf/keystore.jks -storepass changeitError 3: Keystore type JKS is not supported by provider SUN in FIPS mode
Cause: The JVM on the target host is running in FIPS-compliant mode, which disables the legacy JKS keystore type. JKS uses a proprietary algorithm that is not FIPS-approved.
Resolution:
Convert the JKS keystore to PKCS12 format, which is FIPS-compatible:
keytool -importkeystore \
-srckeystore /opt/app/conf/keystore.jks \
-destkeystore /opt/app/conf/keystore.p12 \
-deststoretype PKCS12 \
-srcstorepass changeit \
-deststorepass changeitUpdate the sensor configuration to reference the new PKCS12 file and set
format: pkcs12.Update the application to use the PKCS12 keystore. JKS is deprecated since JDK 9; PKCS12 migration is the recommended long-term resolution.
9. Security Recommendations
Never store keystore passwords in plaintext. Always use the CBOM secret store or an external secrets manager (HashiCorp Vault, AWS Secrets Manager) to supply passwords to the sensor.
Use a dedicated least-privilege OS account (
cbom-sensor) for the agent. Grant file-level read access only to the specific keystore paths required; avoid broad directory permissions.Migrate from JKS to PKCS12. JKS is deprecated since JDK 9 and uses a proprietary, non-standard algorithm. PKCS12 offers broader interoperability and stronger cryptographic protection of the keystore itself.
Restrict keystore file permissions to the minimum necessary. Keystores containing private keys should be readable only by the owning application process and the CBOM sensor account (
chmod 640, owned by the application user and a shared group).Rotate keystore passwords periodically and update the CBOM secret store accordingly. Use CBOM's certificate expiry alerts to proactively identify certificates approaching expiration within discovered keystores.
10. Conclusion
The CBOM Discover_Keystore sensor provides automated, read-only discovery of cryptographic assets stored in Java KeyStore (JKS) files, including private key entries and trusted certificate entries. By following this guide, you have located JKS files on the target filesystem, configured least-privilege access for the sensor agent, and securely supplied keystore passwords through the CBOM secret store. As JKS is deprecated since JDK 9, organizations are encouraged to use the CBOM discovery data as an opportunity to plan and execute migration to the PKCS12 format, improving both interoperability and cryptographic hygiene across their Java-based infrastructure.