On This Page

Home / Edge/ Secure Your Deployment/ Manage Secrets and Keys/Create and Manage Secrets in Cribl Edge

Create and Manage Secrets in Cribl Edge
​

The Cribl Edge secrets store enables you to centrally manage secrets that Cribl Edge instances use to authenticate on integrated services. Use the Manage Secrets page to create and update authorization tokens, username/password combinations, and API-key/secret-key combinations for reuse across the application. These defined secrets can then be programmatically accessed and used within your Cribl Edge configurations using the C.Secret Function.

To ensure they can be decoded correctly, all secrets in Cribl Edge must use latin1 encoding.

How Secrets Are Protected
​

cribl.secret is the master encryption key used by Cribl Edge to protect sensitive values such as credentials, tokens, and other secrets stored in configuration files. It is the root of trust for securing encrypted values across the platform and is created when Cribl Edge first starts.

File Location
​

By default, cribl.secret is stored at:

$CRIBL_HOME/local/cribl/auth/cribl.secret

When you configure an external KMS provider, cribl.secret is removed from disk and managed by that provider instead. Supported providers include AWS KMS and HashiCorp Vault.

Back up cribl.secret securely before major changes such as enabling an external KMS or rotating keys.

When using an external KMS, ensure that IAM permissions are correctly scoped (for example, kms:Decrypt for AWS KMS). Misconfigured permissions can prevent the Leader from starting. For details, see Configure KMS Providers.

Other Security Files
​

When you install Cribl Edge, a keys.json file is also created. This file contains cryptographic keys used for internal operations within Cribl Edge.

  • Single-instance deployment - this file is located in $CRIBL_HOME/local/cribl/auth/.

  • Distributed deployment - this file resides on the Leader Node, in $CRIBL_HOME/groups/<group-name>/local/cribl/auth/.

Access Secrets
​

  • In a Single-instance deployment, select Settings > Security > Secrets.
  • In a Distributed deployment with one Fleet, select Configure > Settings > Security > Secrets.
  • In a Distributed deployment with multiple Fleets, secrets are managed on each Fleet. Select Fleet > <Name> > Fleet Settings > Security > Secrets.

On the Manage Secrets page, you can configure existing secrets, and/or click New Secret to define new secrets.

View Secret References
​

To view where a secret is used in your deployment:

  1. Select a secret from the secrets list.

  2. View the Referenced table at the end of the secret details. This table lists all Sources, Destinations, Pipelines, or Database Connections that currently reference that secret. If a secret is not referenced in one of those resources, the Referenced By column displays No.

    View where secrets are referenced in your deployment
    View where secrets are referenced in your deployment

Add New Secret
​

The New Secret modal provides the following controls:

  • Secret name: Enter an arbitrary, unique name for this secret.

  • Secret type: Some options for this field expose additional controls, as described below.

  • Description: Optionally, enter a description summarizing the purpose of the secret.

  • Tags: Optionally, enter one or multiple tags related to this secret.

Secret Type
​

This drop-down offers the following types:

  • Text: This default type exposes a Value field where you directly enter the secret.

  • API key and secret key: Exposes API key and Secret key fields, used to retrieve the secret from a secure endpoint. This is the only secret type that Cribl Edge supports for its AWS-based Sources, Collectors, and Destinations, and its Google Cloud Storage Destination.

  • Username with password: Exposes Username and Password fields, which you fill to retrieve the secret using Basic Authentication.

Encrypt Secrets Using the Command Line
​

You also have the option to create and encrypt sensitive values using the same mechanism Cribl Edge employs internally for all sensitive fields. This ensures consistency and leverages the built-in encryption capabilities within Cribl Edge.

This approach allows you to store all your secrets securely in a password store, keeping them out of your Git repository, and adheres to strict organizational security standards that prohibit storing secrets in version control.

Modifying credentials directly through the Cribl Edge UI won’t be possible, even in development environments. This approach prioritizes security by keeping secrets out of the UI altogether.

For details, see encrypt in the CLI Reference doc.

Recover cribl.secret
​

If cribl.secret is lost or inaccessible, the Leader will fail to start because it cannot decrypt protected values. Recovery depends on whether you have an unencrypted backup or only an encrypted version.

Recover from an Unencrypted Backup
​

If you have an unencrypted backup, restore it to the following path and restart the Leader:

$CRIBL_HOME/local/cribl/auth/cribl.secret

Recover from an Encrypted Backup (AWS KMS)
​

If you only have an encrypted version under AWS KMS, use the AWS CLI with kms:Decrypt permissions to recover the plaintext key:

aws kms decrypt \
  --ciphertext-blob fileb://cribl.secret.encrypted.decoded \
  --region <region> \
  --key-id <KMS key ARN> \
  --output text \
  --query Plaintext | base64 --decode > cribl.secret

Place the recovered file at $CRIBL_HOME/local/cribl/auth/cribl.secret and restart the Leader.

Recover After KMS Failure
​

If your AWS KMS integration is misconfigured and the Leader won’t start, switch back to the local KMS provider by editing:

$CRIBL_HOME/local/cribl/kms.yml

If you only have the encrypted version cribl.secret.encrypted, use the AWS CLI decrypt command above to recover the plaintext key, then restart the Leader.

Rotate cribl.secret
​

To rotate the master encryption key for the Leader, follow these steps. Note that all credentials encrypted with the current key will need to be re-entered.

Take a full backup of the $CRIBL_HOME directory before proceeding. Use tar to create an archive and store it in a secure location.

  1. Copy the current auth token from the Leader and store it securely. Navigate to Global Settings > System > Distributed Settings > Leader Settings > Auth Token.

  2. Stop the Cribl systemd service.

  3. Delete the $CRIBL_HOME/local/cribl/auth/cribl.secret file.

  4. Edit the $CRIBL_HOME/local/cribl/auth/users.json file and reset the password for at least the admin user. For details, see Manual Password Reset.

  5. Start the Leader and log in with the new credentials.

  6. Restore the auth token you saved earlier. Navigate to Global Settings > System > Distributed Settings > Leader Settings > Auth Token. Once restored, Edge Nodes should reconnect to the Leader.

  7. Reset passwords for other users through the UI, if applicable.

  8. Reconfigure TLS and SSO settings if needed.

  9. Replace each secret in Sources, Destinations, and Fleets. Secrets are stored in $CRIBL_HOME/local/cribl/secrets.yml. To find all references to secrets, search for strings starting with #42::

    grep -Rn '#42:' $CRIBL_HOME/local/cribl/

  10. For each secret, generate a new encrypted value:

    cribl encrypt -v PLAINTEXT_SECRET

    Update the secret and all references with the new encrypted value.