Documentation

1. Purpose

This guide explains how to configure the CBOM Discover_Files sensor to scan the Linux system trust store directories for cryptographic certificate assets. The sensor connects in a read-only manner and does not modify any files on the target system.

Cryptographic material discovered includes:

CA root and intermediate certificates stored in PEM and DER format
Custom CA certificates added by system administrators
Trust anchor certificates used by the operating system and applications
Expired, revoked, or soon-to-expire certificates present in the trust store

Directories covered:

Path	Distribution
`/etc/ssl/certs/`	Debian / Ubuntu
`/usr/local/share/ca-certificates/`	Debian / Ubuntu (custom CAs)
`/etc/pki/tls/certs/`	RHEL / CentOS / Fedora
`/etc/pki/ca-trust/source/`	RHEL trust anchors

This guide covers creating a low-privilege scanner account, granting the minimum required read permissions, and configuring the CBOM sensor YAML to point at all relevant paths.

2. Prerequisites

Before proceeding, ensure the following conditions are met:

You have root or sudo access on the Linux host to be scanned.
The target host is running one of the following distributions: - Debian 10+ or Ubuntu 20.04+ - RHEL 7/8/9, CentOS 7/8, AlmaLinux 8/9, Rocky Linux 8/9, or Fedora 36+
The CBOM sensor agent package is installed on the host or on a host with network access to the target (for agentless mode).
The CBOM platform endpoint URL and a valid sensor authentication token are available.
Outbound HTTPS (port 443) is permitted from the sensor host to the CBOM platform.
openssl is installed on the target host for validation steps.

3. Create a Low-Privilege Scanner Account

The CBOM sensor requires a dedicated system account with no login shell and no home directory. This account is used exclusively to read certificate files.

3.1 Create the System User

Run the following command as root or with sudo:

sudo useradd -r -s /sbin/nologin -d /nonexistent -c "CBOM Scanner Service Account" cbom-scanner

Flags explained:

-r — creates a system account (UID below 1000, no aging)
-s /sbin/nologin — prevents interactive login
-d /nonexistent — no home directory is created
-c — descriptive comment for auditing purposes

3.2 Verify the Account Was Created

Confirm the account exists and has the correct attributes:

id cbom-scanner
getent passwd cbom-scanner

Expected output:

uid=998(cbom-scanner) gid=998(cbom-scanner) groups=998(cbom-scanner)
cbom-scanner:x:998:998:CBOM Scanner Service Account:/nonexistent:/sbin/nologin

The UID value may differ depending on existing accounts on the system.

4. Grant Read Access to Trust Store Directories

Linux trust store directories are typically world-readable by default. This section verifies existing permissions and applies corrections where needed.

4.1 Verify Default Permissions

Check that the primary certificate directories are readable by all users:

ls -ld /etc/ssl/certs/
ls -ld /usr/local/share/ca-certificates/
ls -ld /etc/pki/tls/certs/
ls -ld /etc/pki/ca-trust/source/

Expected output (Debian/Ubuntu example):

drwxr-xr-x 4 root root 20480 Jun 15 09:00 /etc/ssl/certs/
drwxr-xr-x 2 root root  4096 Jun 15 09:00 /usr/local/share/ca-certificates/

The r-x bits for group and other confirm world-readable access. No changes are needed if you see this output.

4.2 Apply Read Permissions if Missing

If any directory is not world-readable, apply the minimum required permissions:

# Debian / Ubuntu
sudo chmod o+rx /etc/ssl/certs/
sudo chmod o+rx /usr/local/share/ca-certificates/

# RHEL / CentOS / Fedora
sudo chmod o+rx /etc/pki/tls/certs/
sudo chmod o+rx /etc/pki/ca-trust/source/

4.3 Ensure Certificate Files Are Readable

Verify that individual certificate files within the directories are also readable:

sudo find /etc/ssl/certs/ -type f ! -readable -ls
sudo find /etc/pki/tls/certs/ -type f ! -readable -ls 2>/dev/null

If any files are returned, apply read permissions selectively:

sudo chmod o+r /etc/ssl/certs/<filename>.pem

4.4 Verify Access as cbom-scanner

Confirm the scanner account can list and read certificate files:

sudo -u cbom-scanner ls -la /etc/ssl/certs/ | head -20
sudo -u cbom-scanner openssl x509 -in /etc/ssl/certs/DigiCert_Global_Root_CA.pem -noout -subject -dates

A successful read with no permission errors confirms the scanner account has correct access.

5. Configure the CBOM Sensor

Create or update the sensor configuration file for the Discover_Files sensor. The configuration below covers all standard trust store paths and can be adjusted to include or exclude specific directories.

5.1 Sensor Configuration YAML

sensor:
  name: Discover_Files
  enabled: true
  description: "Linux system trust store certificate discovery"

connection:
  platform_url: "https://cbom.your-organization.com"
  auth_token: "cbom-sensor-token-xxxxxxxxxxxxxxxxxxxxxxxx"
  verify_tls: true

identity:
  run_as_user: cbom-scanner

scan_targets:
  - id: debian_ubuntu_system_certs
    description: "Debian/Ubuntu system CA bundle directory"
    path: /etc/ssl/certs/
    enabled: true
    recursive: true
    follow_symlinks: true
    file_patterns:
      - "*.pem"
      - "*.crt"
      - "*.cer"
      - "*.der"
      - "ca-certificates.crt"

  - id: debian_ubuntu_custom_cas
    description: "Debian/Ubuntu custom CA certificates"
    path: /usr/local/share/ca-certificates/
    enabled: true
    recursive: true
    follow_symlinks: false
    file_patterns:
      - "*.crt"
      - "*.pem"

  - id: rhel_system_certs
    description: "RHEL/CentOS/Fedora system certificate directory"
    path: /etc/pki/tls/certs/
    enabled: true
    recursive: true
    follow_symlinks: true
    file_patterns:
      - "*.pem"
      - "*.crt"
      - "*.cer"
      - "ca-bundle.crt"
      - "ca-bundle.trust.crt"

  - id: rhel_trust_anchors
    description: "RHEL/CentOS/Fedora trust anchor sources"
    path: /etc/pki/ca-trust/source/
    enabled: true
    recursive: true
    follow_symlinks: false
    file_patterns:
      - "*.pem"
      - "*.crt"
      - "*.p7b"

scan_options:
  parse_bundles: true
  extract_metadata: true
  include_expired: true
  min_key_size_rsa: 0
  hash_algorithms:
    - SHA1
    - SHA256
    - MD5
  schedule_cron: "0 2 * * *"
  timeout_seconds: 300

output:
  log_level: INFO
  log_path: /var/log/cbom/discover-files.log
  report_format: json

5.2 Place the Configuration File

Save the configuration to the standard sensor configuration directory:

sudo mkdir -p /etc/cbom/sensors/
sudo cp discover-files-linux-truststore.yaml /etc/cbom/sensors/discover-files-linux-truststore.yaml
sudo chmod 640 /etc/cbom/sensors/discover-files-linux-truststore.yaml
sudo chown root:cbom-scanner /etc/cbom/sensors/discover-files-linux-truststore.yaml

5.3 Create the Log Directory

sudo mkdir -p /var/log/cbom/
sudo chown cbom-scanner:cbom-scanner /var/log/cbom/
sudo chmod 750 /var/log/cbom/

6. Validation

After applying the configuration, verify the sensor discovers certificates correctly.

6.1 Run a Test Scan

Execute a dry-run scan to confirm the sensor can reach the configured paths:

sudo -u cbom-scanner cbom-sensor scan \
  --config /etc/cbom/sensors/discover-files-linux-truststore.yaml \
  --dry-run \
  --verbose

Expected output excerpt:

[INFO] Discover_Files sensor initialized
[INFO] Scanning path: /etc/ssl/certs/ (recursive=true)
[INFO] Found 142 certificate files
[INFO] Scanning path: /usr/local/share/ca-certificates/ (recursive=true)
[INFO] Found 3 certificate files
[INFO] Dry-run complete. Total assets to report: 145

6.2 Validate a Single Certificate File

Independently verify that the scanner account can parse a certificate:

sudo -u cbom-scanner openssl x509 \
  -in /etc/ssl/certs/DigiCert_Global_Root_CA.pem \
  -noout -subject -issuer -dates

6.3 Confirm Assets Appear in CBOM Platform

Log in to the CBOM platform at your configured platform_url.
Navigate to Assets > Certificates.
Filter by Source: Discover_Files and Host: \<your-hostname\>.
Confirm that the expected certificate count matches the dry-run output.
Verify that certificate metadata (subject, issuer, expiry date, key algorithm) is populated correctly.

7. Common Errors and Resolution

Error 1: Permission Denied Reading Certificate Directory

[ERROR] Failed to open directory /etc/ssl/certs/: Permission denied

Cause: The cbom-scanner account does not have read or execute permission on the target directory.

Resolution:

# Verify current permissions
ls -ld /etc/ssl/certs/

# Grant world-readable and world-executable on the directory
sudo chmod o+rx /etc/ssl/certs/

# Confirm the fix
sudo -u cbom-scanner ls /etc/ssl/certs/ | wc -l

Error 2: Authentication Token Invalid or Expired

[ERROR] Platform authentication failed: HTTP 401 Unauthorized — token invalid or expired

Cause: The auth_token value in the sensor configuration is incorrect, has expired, or has been revoked in the CBOM platform.

Resolution:

Log in to the CBOM platform.
Navigate to Settings > Sensor Tokens.
Revoke the old token and generate a new one.
Update the configuration file:

sudo nano /etc/cbom/sensors/discover-files-linux-truststore.yaml
# Update the auth_token field with the new token value

Restart the sensor:

sudo systemctl restart cbom-sensor

Error 3: No Certificate Files Found in Path

[WARN] Scan target rhel_trust_anchors: path /etc/pki/ca-trust/source/ — 0 files matched configured patterns

Cause: The directory exists but contains no files matching the configured file_patterns, or the directory does not exist on this distribution (e.g., a Debian host configured with RHEL paths).

Resolution:

Verify the directory exists and contains files:

ls -la /etc/pki/ca-trust/source/
find /etc/pki/ca-trust/source/ -type f

If the path does not exist (wrong distribution), disable the scan target in the YAML:

  - id: rhel_trust_anchors
    enabled: false   # Set to false on non-RHEL systems

If files exist but have unexpected extensions, add the extension to file_patterns:

    file_patterns:
      - "*.pem"
      - "*.crt"
      - "*.p7b"
      - "*.trust"   # Add any non-standard extension observed

8. Security Recommendations

Principle of least privilege: The cbom-scanner system account must have no sudo rights, no login shell, and access only to the specific certificate directories required. Do not grant access to /etc/ssl/private/ or any directory containing private keys.
Protect the sensor configuration file: The configuration file contains the platform authentication token. Ensure it is owned by root, readable only by root and cbom-scanner (mode 640), and never committed to version control.
Rotate authentication tokens regularly: Generate new sensor tokens at least every 90 days and immediately upon suspected compromise. The CBOM platform supports token rotation without sensor downtime.
Audit scanner account activity: Enable auditd rules to log any file access performed by the cbom-scanner account. This provides a tamper-evident record of sensor activity:

sudo auditctl -a always,exit -F arch=b64 -S open,openat \
  -F uid=$(id -u cbom-scanner) -k cbom-scanner-access

Do not scan private key directories: Explicitly exclude /etc/ssl/private/, /etc/pki/tls/private/, and any application-specific private key directories from scan targets. The CBOM Files sensor is designed for public certificate discovery only and must never be pointed at directories that store private key material.

9. Conclusion

The CBOM Discover_Files sensor provides agentless, read-only discovery of all X.509 certificates stored in the Linux system trust store across both Debian/Ubuntu and RHEL-family distributions. By running under a dedicated low-privilege system account, the sensor adheres to the principle of least privilege while delivering full visibility into CA certificates, custom trust anchors, and any expired or weak-algorithm certificates present on the host. Once configured, the sensor reports discovered cryptographic assets to the CBOM platform on a scheduled basis, enabling continuous certificate lifecycle management and compliance reporting.

CBOM Secure

Linux System Trust Store Setup Guide for CBOM Files Sensor

1. Purpose

2. Prerequisites

3. Create a Low-Privilege Scanner Account

3.1 Create the System User

3.2 Verify the Account Was Created

4. Grant Read Access to Trust Store Directories

4.1 Verify Default Permissions

4.2 Apply Read Permissions if Missing

4.3 Ensure Certificate Files Are Readable

4.4 Verify Access as cbom-scanner

5. Configure the CBOM Sensor

5.1 Sensor Configuration YAML

5.2 Place the Configuration File

5.3 Create the Log Directory

6. Validation

6.1 Run a Test Scan

6.2 Validate a Single Certificate File

6.3 Confirm Assets Appear in CBOM Platform

7. Common Errors and Resolution

Error 1: Permission Denied Reading Certificate Directory

Error 2: Authentication Token Invalid or Expired

Error 3: No Certificate Files Found in Path

8. Security Recommendations

9. Conclusion

On this Page: