Documentation

1. Purpose

The CBOM Discover_PGP sensor performs read-only discovery of OpenPGP key material stored in GnuPG keyring files on a target host. It inventories all public and secret key metadata present in the GnuPG home directory and reports findings to the CBOM platform for cryptographic asset tracking.

Discovered cryptographic material includes:

Public key metadata: key ID, full fingerprint, algorithm, key size, creation date, expiry date, and associated user IDs (UIDs)
Secret key stubs: presence of secret key material, key grip, and associated subkeys
Subkey relationships: subkey fingerprints, algorithms, usage flags (sign, encrypt, authenticate), and validity periods

What this guide covers:

Locating the GnuPG home directory on the target host
Verifying keyring file format (modern keybox vs. legacy GPG format)
Listing public and secret keys to confirm sensor read access
Configuring the Discover_PGP sensor with the correct GPG home path
Validating successful sensor operation

Important: The Discover_PGP sensor extracts metadata only. Private key material, passphrases, and raw key bytes are never read, transmitted, or stored.

2. Prerequisites

Before configuring the CBOM PGP sensor, ensure the following requirements are met:

GnuPG installed on the target host. Minimum supported version is GnuPG 2.1 (modern branch). Legacy GnuPG 1.x is supported in read-only mode for .gpg format keyrings.
CBOM agent installed on the host where GnuPG keyrings reside, or a network-accessible path to the GPG home directory is mounted on the agent host.
Read access to the GPG home directory: The OS user account running the CBOM agent must have read permission on ~/.gnupg/ or the path specified in $GNUPGHOME.
No passphrase prompt required: The sensor calls gpg --list-keys and gpg --list-secret-keys with --batch and --no-tty flags. Secret key stubs that require PIN or passphrase entry on list will cause partial discovery only.
Python 3.8+ required by the CBOM agent runtime.
CBOM platform access: Valid API endpoint and token for the CBOM server are available.

3. Identify the GnuPG Home Directory

The sensor must be pointed at the correct GnuPG home directory. Follow these steps to identify and confirm the path.

3.1 Check GnuPG Version and Default Home

Run the following commands on the target host to confirm GnuPG is installed and identify the default home path:

gpg --version
echo "GNUPGHOME=${GNUPGHOME:-~/.gnupg}"

Expected output (example):

gpg (GnuPG) 2.4.3
libgcrypt 1.10.2
...
GNUPGHOME=/home/appuser/.gnupg

If $GNUPGHOME is not set, GnuPG defaults to ~/.gnupg for the current user. For system-level or service account keyrings, substitute the appropriate home path.

3.2 Confirm Keyring Files Exist

Verify that keyring files are present in the GPG home directory:

ls -lh "${GNUPGHOME:-$HOME/.gnupg}/"

Expected files for modern GnuPG 2.1+ (keybox format):

pubring.kbx        # Primary keyring — public and secret key metadata
trustdb.gpg        # Web of trust database
private-keys-v1.d/ # Directory containing private key files (not read by sensor)

Expected files for legacy GnuPG < 2.1:

pubring.gpg   # Public keyring
secring.gpg   # Secret keyring (deprecated in GnuPG 2.1+)
trustdb.gpg

If pubring.kbx or pubring.gpg is absent, the keyring may be empty or located in a non-default path. Confirm with the system administrator.

4. Verify Read Access and List Keys

Before configuring the sensor, confirm that the CBOM agent OS user can read keyring metadata without errors.

4.1 List Public Keys

Run the following as the CBOM agent OS user:

gpg --homedir "${GNUPGHOME:-$HOME/.gnupg}" \
    --list-keys \
    --with-fingerprint \
    --with-keygrip \
    --batch \
    --no-tty

Expected output (example):

/home/appuser/.gnupg/pubring.kbx
--------------------------------
pub   rsa4096 2022-03-15 [SC] [expires: 2026-03-14]
      A1B2 C3D4 E5F6 7890 ABCD  EF01 2345 6789 ABCD EF01
      Keygrip = 1234567890ABCDEF1234567890ABCDEF12345678
uid           [ultimate] Jane Doe <[email protected]>
sub   rsa4096 2022-03-15 [E] [expires: 2026-03-14]
      Keygrip = ABCDEF1234567890ABCDEF1234567890ABCDEF12

If this command returns output without error, public key discovery will succeed.

4.2 List Secret Key Stubs

gpg --homedir "${GNUPGHOME:-$HOME/.gnupg}" \
    --list-secret-keys \
    --with-fingerprint \
    --with-keygrip \
    --batch \
    --no-tty

Expected output (example):

/home/appuser/.gnupg/pubring.kbx
--------------------------------
sec   rsa4096 2022-03-15 [SC] [expires: 2026-03-14]
      A1B2 C3D4 E5F6 7890 ABCD  EF01 2345 6789 ABCD EF01
      Keygrip = 1234567890ABCDEF1234567890ABCDEF12345678
uid           [ultimate] Jane Doe <[email protected]>
ssb   rsa4096 2022-03-15 [E] [expires: 2026-03-14]
      Keygrip = ABCDEF1234567890ABCDEF1234567890ABCDEF12

A # after sec or ssb (e.g., sec#) indicates the private key is not locally present (stub only). The sensor handles this correctly and records only metadata.

4.3 Grant Read Permission (if required)

If the CBOM agent user does not own the GPG home directory, grant read access:

# Add the CBOM agent user to the keyring owner group (adjust group name as needed)
sudo usermod -aG <keyring_owner_group> cbom-agent

# Set group-readable permissions on the GPG home (do NOT set world-readable)
chmod 750 /home/appuser/.gnupg
chmod 640 /home/appuser/.gnupg/pubring.kbx

Do not set world-readable permissions on the .gnupg directory, as this exposes trust data to all local users.

5. Configure CBOM Sensor

Add the Discover_PGP sensor block to the CBOM agent configuration file (typically cbom-agent.yaml or included as a sensor fragment).

sensors:
  - name: Discover_PGP
    enabled: true
    schedule: "0 2 * * *"          # Daily at 02:00 local time
    config:
      # Absolute path to the GnuPG home directory.
      # Override with $GNUPGHOME value if set on the target host.
      gpg_home: "/home/appuser/.gnupg"

      # GPG binary path. Leave as "gpg" to use system PATH resolution,
      # or specify an absolute path for non-standard installations.
      gpg_binary: "gpg"

      # Include secret key stub metadata in discovery output.
      # Private key material is never extracted regardless of this setting.
      discover_secret_key_stubs: true

      # Collect subkey metadata in addition to primary key metadata.
      discover_subkeys: true

      # Maximum age (in days) of a key before it is flagged as stale in CBOM.
      # Set to 0 to disable staleness flagging.
      stale_key_threshold_days: 365

      # Tags applied to all assets discovered by this sensor instance.
      tags:
        - "gnupg"
        - "pgp"
        - "host:appserver-01.example.com"
        - "env:production"

      # CBOM platform reporting settings (inherited from agent global config
      # if not overridden here).
      cbom_api_endpoint: "https://cbom.example.com/api/v1"
      cbom_api_token: "${CBOM_API_TOKEN}"   # Injected via environment variable

Save the configuration and restart the CBOM agent service:

sudo systemctl restart cbom-agent

6. Validation

After configuring and restarting the agent, confirm that the Discover_PGP sensor is operating correctly.

6.1 Check Agent Logs

sudo journalctl -u cbom-agent -n 100 --no-pager | grep -i "Discover_PGP"

Expected log lines on successful execution:

INFO  [Discover_PGP] Starting PGP keyring scan: gpg_home=/home/appuser/.gnupg
INFO  [Discover_PGP] Listed 4 public key(s) from pubring.kbx
INFO  [Discover_PGP] Listed 2 secret key stub(s)
INFO  [Discover_PGP] Discovered 6 cryptographic asset(s); reporting to CBOM platform
INFO  [Discover_PGP] Report accepted by CBOM platform (HTTP 200)

6.2 Trigger a Manual Sensor Run

cbom-agent run-sensor --name Discover_PGP --once

6.3 Verify Assets in CBOM Platform

Log in to the CBOM platform UI and navigate to Assets > PGP Keys. Confirm that:

Keys discovered match the output of gpg --list-keys run manually on the host.
Key fingerprints, algorithms, key sizes, creation dates, and expiry dates are correctly populated.
Expired keys are flagged with the appropriate status in the platform.
No private key material appears in any asset field.

7. Common Errors and Resolution

Error 1: Permission denied opening keyring file

ERROR [Discover_PGP] Failed to list public keys: gpg exited with code 2
gpg: can't open '/home/appuser/.gnupg/pubring.kbx': Permission denied

Cause: The CBOM agent OS user does not have read permission on the keyring file.

Fix:

chmod 640 /home/appuser/.gnupg/pubring.kbx
chown appuser:cbom-agent-group /home/appuser/.gnupg/pubring.kbx
sudo usermod -aG cbom-agent-group cbom-agent

Error 2: Unsafe permissions warning causes gpg to abort

WARN  [Discover_PGP] gpg emitted warning: unsafe permissions on homedir
ERROR [Discover_PGP] gpg exited with non-zero status; keyring data may be incomplete
gpg: WARNING: unsafe permissions on homedir '/home/appuser/.gnupg'

Cause: GnuPG refuses to operate on a home directory that is group- or world-writable. This occurs when permissions on .gnupg are set too broadly (e.g., 777 or 775).

Fix:

chmod 700 /home/appuser/.gnupg
chmod 600 /home/appuser/.gnupg/pubring.kbx
chmod 600 /home/appuser/.gnupg/trustdb.gpg

Error 3: CBOM platform rejects report with HTTP 401

ERROR [Discover_PGP] Failed to submit report to CBOM platform
Response: HTTP 401 Unauthorized {"error": "invalid or expired API token"}

Cause: The cbom_api_token value is missing, expired, or the environment variable CBOM_API_TOKEN was not injected into the agent process.

Fix:

Verify the token is set in the environment:

sudo systemctl show cbom-agent -p Environment

If missing, add the variable to the systemd service override:

sudo systemctl edit cbom-agent

Add the following under [Service]:

[Service]
Environment="CBOM_API_TOKEN=your-token-here"

Reload and restart:

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

Rotate the token in the CBOM platform if it has expired under Settings > API Tokens.

8. Security Recommendations

Principle of least privilege: The CBOM agent OS user should be granted read-only access to the GPG home directory exclusively. Do not run the agent as the keyring owner or as root.
Never expose .gnupg world-readable: Setting permissions broader than 750 on the GPG home directory exposes trust database information to all local users and may allow tampering with key trust levels.
Use environment variables for secrets: Store the cbom_api_token in an environment variable (e.g., via systemd EnvironmentFile) rather than hardcoding it in cbom-agent.yaml. Ensure the environment file is readable only by the agent user (chmod 600).
Monitor for expired and expiring keys: Configure CBOM alerting rules to notify on keys approaching expiry (stale_key_threshold_days) so that key renewals can be planned before cryptographic operations fail.
Audit keyring access: Enable OS-level audit logging (auditd) on the .gnupg directory to detect unexpected read or write access outside of normal agent scan windows.

9. Conclusion

The CBOM Discover_PGP sensor provides automated, read-only discovery of OpenPGP key metadata from GnuPG keyrings, giving security teams continuous visibility into PGP key lifecycle, algorithm usage, and expiry posture across their infrastructure. By following this guide, the sensor is configured with the minimum required permissions and integrated safely with the CBOM platform. Regular scheduled scans ensure that newly created, rotated, or expired keys are reflected in the cryptographic bill of materials without any manual inventory effort.

CBOM Secure

GnuPG Setup Guide for CBOM PGP Sensor

1. Purpose

2. Prerequisites

3. Identify the GnuPG Home Directory

3.1 Check GnuPG Version and Default Home

3.2 Confirm Keyring Files Exist

4. Verify Read Access and List Keys

4.1 List Public Keys

4.2 List Secret Key Stubs

4.3 Grant Read Permission (if required)

5. Configure CBOM Sensor

6. Validation

6.1 Check Agent Logs

6.2 Trigger a Manual Sensor Run

6.3 Verify Assets in CBOM Platform

7. Common Errors and Resolution

8. Security Recommendations

9. Conclusion

On this Page: