MySQL Setup Guide for CBOM Database TDE Sensor
1. Purpose
This guide covers the configuration required to connect the CBOM Database TDE sensor to a MySQL 8.0+ instance using InnoDB data-at-rest encryption. The CBOM sensor discovers cryptographic material managed by MySQL keyring plugins, including:
Encryption keys registered in the keyring (keyring_file, keyring_okv, keyring_hashicorp)
InnoDB tablespace encryption status and associated key identifiers
Active keyring plugin metadata and configuration state
The sensor operates in read-only mode using a dedicated least-privilege MySQL user. No data is modified, and no encryption keys are extracted — only metadata is collected for inventory and compliance purposes.
2. Prerequisites
Before beginning this setup, ensure the following conditions are met:
MySQL 8.0 or later is installed and running.
InnoDB data-at-rest encryption is enabled with a supported keyring plugin (
keyring_file,keyring_okv, orkeyring_hashicorp).The
performance_schemais enabled (default in MySQL 8.0+).You have access to a MySQL account with
GRANTprivileges (typicallyrootor a DBA account).Network connectivity exists between the CBOM sensor host and the MySQL server on the configured port (default: 3306).
The CBOM agent is installed on the sensor host and the
Discover_DBsensor module is available.SSL/TLS is configured on the MySQL server if the connection traverses an untrusted network.
3. Create the CBOM Reader Account
Create a dedicated MySQL user for the CBOM sensor. This user requires read-only access to specific system schemas and no access to application data.
3.1 Create the User
Connect to MySQL as an administrative user and run the following statement. Replace 'StrongPassword123!' with a secure password that meets your organization's password policy.
CREATE USER 'cbom_reader'@'%' IDENTIFIED BY 'StrongPassword123!';If the CBOM sensor will connect from a specific host, replace '%' with the sensor's IP address or hostname to restrict the login origin:
CREATE USER 'cbom_reader'@'cbom-agent.example.com' IDENTIFIED BY 'StrongPassword123!';3.2 Grant Required Privileges
Grant the minimum privileges needed for the CBOM sensor to query keyring and tablespace metadata.
-- Allow the sensor to read registered keyring key metadata
GRANT SELECT ON performance_schema.keyring_keys TO 'cbom_reader'@'%';
-- Allow the sensor to query running process and session state
GRANT PROCESS ON *.* TO 'cbom_reader'@'%';
-- Allow the sensor to read tablespace encryption status
GRANT SELECT ON information_schema.INNODB_TABLESPACES TO 'cbom_reader'@'%';
-- Apply the privilege changes immediately
FLUSH PRIVILEGES;3.3 Verify the User and Privileges
Confirm the account was created and the grants were applied correctly:
SELECT user, host, account_locked, password_expired
FROM mysql.user
WHERE user = 'cbom_reader';
SHOW GRANTS FOR 'cbom_reader'@'%';Expected output for SHOW GRANTS:
+-----------------------------------------------------------------------------------+
| Grants for cbom_reader@% |
+-----------------------------------------------------------------------------------+
| GRANT PROCESS ON *.* TO `cbom_reader`@`%` |
| GRANT SELECT ON `performance_schema`.`keyring_keys` TO `cbom_reader`@`%` |
| GRANT SELECT ON `information_schema`.`INNODB_TABLESPACES` TO `cbom_reader`@`%` |
+-----------------------------------------------------------------------------------+4. Verify the Keyring Plugin Is Active
The CBOM sensor requires a keyring plugin to be loaded and active. Without an active keyring plugin, no key metadata will be available.
4.1 Check Loaded Plugins
Run the following query to confirm a keyring plugin is present and active:
SHOW PLUGINS;Look for a row where Name contains keyring and Status is ACTIVE. Example output:
+-------------------+--------+--------------------+----------------------+---------+
| Name | Status | Type | Library | License |
+-------------------+--------+--------------------+----------------------+---------+
| keyring_file | ACTIVE | KEYRING | keyring_file.so | GPL |
+-------------------+--------+--------------------+----------------------+---------+4.2 Verify Keyring Keys Are Accessible
Confirm that key entries are visible in performance_schema:
SELECT * FROM performance_schema.keyring_keys;If the table returns rows, the keyring is populated and the CBOM sensor will be able to collect key identifiers. An empty result set indicates encryption is configured but no keys have been generated yet, which may occur on a freshly initialized instance.
4.3 Verify Tablespace Encryption Status
Confirm encrypted tablespace metadata is accessible:
SELECT SPACE, NAME, ENCRYPTION
FROM information_schema.INNODB_TABLESPACES
WHERE ENCRYPTION = 'Y'
LIMIT 10;5. Configure SSL/TLS for the Sensor Connection (Recommended)
If MySQL is configured to require SSL, or if the connection traverses a network boundary, configure the CBOM sensor to use TLS when connecting.
5.1 Confirm SSL Is Available on the MySQL Server
SHOW VARIABLES LIKE '%ssl%';Confirm that have_ssl is YES and have_openssl is YES.
5.2 Require SSL for the CBOM Reader Account (Optional Hardening)
To enforce encrypted connections for the sensor account:
ALTER USER 'cbom_reader'@'%' REQUIRE SSL;5.3 Obtain the CA Certificate
Copy the MySQL CA certificate from the server to the CBOM sensor host. The default location on the MySQL server is:
/var/lib/mysql/ca.pemPlace the certificate on the sensor host at a path accessible to the CBOM agent, for example:
/etc/cbom/certs/mysql-ca.pem6. Configure CBOM Sensor
Create or update the sensor configuration file for the Discover_DB sensor. The configuration file is typically located at /etc/cbom/sensors/mysql-tde.yaml or within the CBOM agent's sensors/ directory.
sensor:
name: Discover_DB
enabled: true
schedule: "0 */6 * * *" # Run every 6 hours
target:
type: mysql
host: "mysql.internal.example.com"
port: 3306
database: "performance_schema"
credentials:
username: "cbom_reader"
password: "${CBOM_MYSQL_PASSWORD}" # Injected from environment or secrets manager
tls:
enabled: true
ca_cert: "/etc/cbom/certs/mysql-ca.pem"
verify_server_cert: true
discovery:
keyring:
enabled: true
source_table: "performance_schema.keyring_keys"
tablespaces:
enabled: true
source_table: "information_schema.INNODB_TABLESPACES"
filter_encrypted_only: true
plugins:
enabled: true
query: "SHOW PLUGINS"
filter_type: "KEYRING"
output:
format: "cbom-json"
destination: "/var/cbom/output/mysql-tde/"
include_metadata: true
logging:
level: "info"
path: "/var/log/cbom/mysql-tde-sensor.log"Set the password environment variable on the CBOM agent host before starting the sensor:
export CBOM_MYSQL_PASSWORD='StrongPassword123!'For production deployments, inject the password via a secrets manager (HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault) rather than a plain environment variable.
7. Validation
After saving the configuration file, run the CBOM sensor in dry-run mode to verify connectivity and permissions before enabling the scheduled collection.
7.1 Test Connectivity
cbom sensor run --name Discover_DB --config /etc/cbom/sensors/mysql-tde.yaml --dry-runExpected output:
[INFO] Connecting to mysql.internal.example.com:3306...
[INFO] Authentication successful for user 'cbom_reader'
[INFO] Keyring plugin detected: keyring_file (ACTIVE)
[INFO] Discovered 12 keyring key entries
[INFO] Discovered 34 encrypted tablespaces
[INFO] Dry-run complete. No output written.7.2 Run a Full Collection
cbom sensor run --name Discover_DB --config /etc/cbom/sensors/mysql-tde.yaml7.3 Verify Output
Confirm output files were written to the configured destination:
ls -lh /var/cbom/output/mysql-tde/Review the CBOM JSON output to confirm key identifiers and tablespace records are present:
cat /var/cbom/output/mysql-tde/cbom-latest.json | python3 -m json.tool | head -607.4 Confirm in the CBOM Dashboard
Log in to the CBOM console and navigate to Sensors > Discover_DB > MySQL. Confirm the sensor shows a recent successful run timestamp and that discovered assets are listed under the MySQL data source.
8. Common Errors and Resolution
Error 1: Access denied for user 'cbom_reader'@'...' (using password: YES)
Cause: The user account does not exist for the connecting host, the password is incorrect, or the host restriction on the account does not match the sensor's IP address.
Resolution:
Verify the account exists:
SELECT user, host FROM mysql.user WHERE user = 'cbom_reader';Confirm the sensor host IP matches the account's
hostcolumn. If the account was created with a specific IP, ensure the sensor connects from that address.Re-create the account with
'%'if host restriction is not required, or update the account host:RENAME USER 'cbom_reader'@'old_host' TO 'cbom_reader'@'new_host';Reset the password if needed:
ALTER USER 'cbom_reader'@'%' IDENTIFIED BY 'NewPassword!';
Error 2: Table 'performance_schema.keyring_keys' doesn't exist
Cause: The keyring_keys table is only present in MySQL 8.0.16 and later, and only when a keyring plugin is loaded. If no keyring plugin is active, the table does not exist.
Resolution:
Verify the MySQL version:
SELECT VERSION();— must be 8.0.16 or later.Confirm a keyring plugin is active:
SHOW PLUGINS;— look for a row withType = KEYRINGandStatus = ACTIVE.If no keyring plugin is loaded, configure one in
my.cnf. Example forkeyring_file:
[mysqld]
early-plugin-load = keyring_file.so
keyring_file_data = /var/lib/mysql-keyring/keyringRestart MySQL and re-run the sensor.
Error 3: SSL connection error: SSL is required but the server doesn't support it
Cause: The CBOM sensor configuration has tls.enabled: true but the MySQL server was not compiled with SSL support or SSL is disabled in the server configuration.
Resolution:
Check SSL support on the server:
SHOW VARIABLES LIKE 'have_ssl';— must returnYES.If SSL is disabled, enable it in
my.cnf:
[mysqld]
ssl-ca = /var/lib/mysql/ca.pem
ssl-cert = /var/lib/mysql/server-cert.pem
ssl-key = /var/lib/mysql/server-key.pemRestart MySQL and confirm:
SHOW VARIABLES LIKE '%ssl%';If the MySQL instance does not support SSL and operates on a trusted internal network, set
tls.enabled: falsein the sensor configuration as a temporary workaround. Document this exception and schedule remediation.
9. Security Recommendations
Use a dedicated read-only account. Never configure the CBOM sensor with a DBA or root account. The
cbom_readeraccount should hold only the three grants described in Section 3.2 and nothing more.Restrict the account login origin. Replace
'%'with the specific IP address of the CBOM sensor host to prevent the credential from being usable from other systems in the event of exposure.Store credentials in a secrets manager. Do not hard-code passwords in the sensor YAML file. Use environment variable injection from HashiCorp Vault, AWS Secrets Manager, or a comparable system, and rotate the password on a defined schedule.
Enforce SSL for the sensor connection. Apply
ALTER USER 'cbom_reader'@'%' REQUIRE SSL;and configure the sensor with a valid CA certificate to prevent credential interception in transit.Audit sensor account usage. Enable the MySQL audit log plugin and create a filter that captures all queries by
cbom_reader. Review these logs periodically to detect unexpected access patterns or privilege escalation attempts.
10. Conclusion
This guide establishes a secure, least-privilege connection between the CBOM Discover_DB sensor and a MySQL 8.0+ instance using InnoDB data-at-rest encryption. By querying performance_schema.keyring_keys and information_schema.INNODB_TABLESPACES, the sensor builds a complete inventory of active encryption keys and encrypted tablespaces without accessing application data or extracting key material. Regular sensor runs ensure the CBOM cryptographic inventory remains current and supports ongoing compliance, audit, and cryptographic risk assessment workflows.