Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow lokibreadcrumb arrow loki.secretfilter
Experimental

loki.secretfilter

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. The stability.level flag must be set to experimental to use the component.

loki.secretfilter receives log entries and redacts sensitive information from them, such as secrets. The detection is based on regular expression patterns, defined in the Gitleaks configuration file embedded within the component. loki.secretfilter can also use a custom configuration file based on the Gitleaks configuration file structure.

Caution

Personally Identifiable Information (PII) isn’t currently in scope and some secrets could remain undetected. This component may generate false positives. Don’t rely solely on this component to redact sensitive information.

Note

This component operates on log lines and doesn’t scan labels or other metadata.

Usage

Alloy 
loki.secretfilter "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

loki.secretfilter supports the following arguments:

NameTypeDescriptionDefaultRequired
forward_tolist(LogsReceiver)List of receivers to send log entries to.yes
allowlistmap(string)List of regular expressions to allowlist matching secrets.{}no
gitleaks_configstringPath to the custom gitleaks.toml file.Embedded Gitleaks fileno
include_genericboolInclude the generic API key rule.falseno
partial_masknumberShow the first N characters of the secret.0no
redact_withstringString to use to redact secrets.<REDACTED-SECRET:$SECRET_NAME>no
typesmap(string)Types of secret to look for.All typesno

The gitleaks_config argument is the path to the custom gitleaks.toml file. The Gitleaks configuration file embedded in the component is used if you don’t provide the path to a custom configuration file.

The types argument is a map of secret types to look for. The values are used as prefixes for the secret types in the Gitleaks configuration. If you don’t provide this argument, all types are used.

Note

Configuring this argument with the secret types you want to look for is strongly recommended. If you don’t, the component looks for all known types, which is resource-intensive.

Caution

Some secret types in the Gitleaks configuration file rely on regular expression patterns that don’t detect the secret itself but rather the context around it. For example, the aws-access-token type detects AWS key IDs, not the keys themselves. This is because the keys don’t have a unique pattern that can easily be detected with a regular expression. As a result, with this secret type enabled, the component redacts key IDs but not actual secret keys. This behavior is consistent with the Gitleaks redaction feature but may not be what you expect. Currently, the secret types known to have this behavior are: aws-access-token.

The redact_with argument is a string that can use variables such as $SECRET_NAME, replaced with the matching secret type, and $SECRET_HASH, replaced with the SHA1 hash of the secret.

The include_generic argument is a boolean that includes the generic API key rule in the Gitleaks configuration file if set to true. It’s disabled by default because it can generate false positives.

The allowlist argument is a map of regular expressions to allow matching secrets. A secret won’t be redacted if it matches any of the regular expressions. The allowlist in the Gitleaks configuration file is also applied.

The partial_mask argument is the number of characters to show from the beginning of the secret before the redact string is added. If set to 0, the entire secret is redacted.

Blocks

The loki.secretfilter component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
receiverLogsReceiverA value that other components can use to send log entries to.

Component health

loki.secretfilter is only reported as unhealthy if given an invalid configuration.

Debug metrics

loki.secretfilter doesn’t expose any component-specific debug information.

Example

This example shows how to use loki.secretfilter to redact secrets from log lines before forwarding them to a Loki receiver. It uses a custom redaction string that includes the secret type and its hash.

Alloy 
local.file_match "local_logs" {
    path_targets = "<PATH_TARGETS>"
}

loki.source.file "local_logs" {
    targets    = local.file_match.local_logs.targets
    forward_to = [loki.secretfilter.secret_filter.receiver]
}

loki.secretfilter "secret_filter" {
    forward_to  = [loki.write.local_loki.receiver]
    redact_with = "<ALLOY-REDACTED-SECRET:$SECRET_NAME:$SECRET_HASH>"
}

loki.write "local_loki" {
    endpoint {
        url = "<LOKI_ENDPOINT>"
    }
}

Replace the following:

  • <PATH_TARGETS>: The paths to the log files to monitor.
  • <LOKI_ENDPOINT>: The URL of the Loki instance to send logs to.

Compatible components

loki.secretfilter can accept arguments from the following components:

loki.secretfilter has exports that can be consumed by the following components:

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.