Secret Managers¶

The scanner can retrieve connection credentials from a secret manager instead of storing them in plain text in connection files.

This page describes the supported secret managers, how to configure them, and the permissions required on the secret manager side.

How It Works¶

A secret manager configuration has two parts:

1. Scanner-level configuration: One secret manager for the whole scanner, declared in the scanner's application.conf.
2. Connection-level configuration: A reference in each connection file that specifies the secret to read (secret_manager.key) and the fields to substitute (${secret_manager.<field>}).

Scanner-Level Configuration¶

Configure a single secret manager for the scanner in application.conf:

secret-manager {
  provider = "<PROVIDER>"      
  configuration {              # provider settings; flat keys, string values
    ...
  }
  proxy {                      # optional
    ...
  }
  key = "scanner"              # optional: the secret used for substitutions in application.conf itself (default "scanner")
}

• If no secret-manager block is configured, no secret manager is used. The log shows secret_manager_not_in_use.
• Keep the values in configuration as quoted strings, including numbers. For example, timeout-seconds = "30".
• The scanner creates the provider at startup. A configuration error (such as a missing key, an unreadable keystore, or an http:// URL) stops the scanner with a message that identifies the setting.

Connection-Level Configuration¶

Configure each connection to use a secret from the secret manager:

name = "postgres-prod"
code = "postgres-prod"
connector_id = "postgresql"

secret_manager {
  enabled = true
  key = "zeenea/postgres-prod"        # the secret to read; its format depends on the provider
}

connection {
  url      = "jdbc:postgresql://db.example:5432/app"
  username = ${secret_manager.username}   # a field of the secret
  password = ${secret_manager.password}

  # Optional field with a default value: kept when the secret has no "schema" field
  schema = "public"
  schema = ${?secret_manager.schema}
}

• secret_manager.enabled defaults to false.
• When key is missing, the scanner uses the connection code as the key and logs the warning secret_manager_no_identifier_key_found.
• A secret is a set of named fields. Each provider section describes the fields available in a secret (for example, username and password for a JSON secret).
• Use ${secret_manager.<field>} for a required value, and ${?secret_manager.<field>} for an optional one (standard HOCON syntax).
• When the secret or field cannot be found, the scanner logs secret_manager_missing_secret or secret_manager_missing_key_value. A required substitution cannot be resolved (Could not resolve substitution to a value), so the connection does not load.
• The scanner calls the secret manager for each substitution and caches nothing. As a result, a rotated password is picked up the next time the connection configuration is loaded.

Providers¶

The scanner supports multiple secret manager providers.

Choosing a Provider¶

Use the following table to compare the supported providers:

Common Settings for HTTP Providers¶

The following settings apply to hashicorp-vault and gcp-secret-manager.

Timeouts and Retries¶

The scanner does not retry 4xx responses or TLS errors because they indicate a configuration or permission problem.

TLS¶

• Only https:// URLs are accepted. The exception is hashicorp-vault, which also accepts http:// URLs on localhost, 127.x.x.x, or [::1] for local development and logs the warning secret_manager_insecure_url.
• The server certificate and host name are always verified.
• By default, the JVM's trusted certificates (cacerts) are used. For a private CA or a TLS-inspecting proxy, provide a truststore:

Where a client certificate is used (for example, Vault cert authentication), it is read from keystore-path, keystore-password, and keystore-type (default PKCS12). The keystore must contain both the certificate and its private key.

Create a keystore from PEM files as follows:

openssl pkcs12 -export -in client.crt -inkey client.key -certfile ca.crt \
  -name client -out client.p12          # prompts for the keystore password
chmod 600 client.p12                    # readable by the scanner's service user only

Proxy¶

secret-manager {
  ...
  proxy {
    hostname = "proxy.example"
    port     = "3128"
    scheme   = "http"                     # default "http"
    username = "<PROXY_USER>"             # optional
    password = ${?SCANNER_PROXY_PASSWORD} # optional
  }
}

• hostname and port are required. If either is missing, the warning <provider>_proxy_error is logged and no proxy is used.
• Basic proxy authentication is supported, including for HTTPS tunnels.
• aws-secrets-manager uses the same block but requires all five settings. For more information, see AWS Secrets Manager.
• Providers that do not make network calls, such as file, ignore the proxy configuration.

Local File¶

provider = "file"

Reads secrets from a local HOCON file.

Configuration¶

secret-manager {
  provider = "file"
  configuration {
    file-path = "/etc/zeenea/secrets.conf"
  }
}

Key and Fields¶

In the secret file, the first path segment is the secret key, and the remaining path segments are the field name. Values must be strings. Substitutions are resolved, so ${?ENV_VAR} works.

postgres-prod {
  username = "USER_NAME"
  password = ${?POSTGRES_PASSWORD}
}

• Key: postgres-prod.
• Fields: username, password.

Setup on the Host Side¶

Protect the file with chmod 600 and ensure it is owned by the scanner's service user.

AWS Secrets Manager¶

provider = "aws-secrets-manager"

Reads secrets from AWS Secrets Manager through the AWS SDK.

Configuration¶

secret-manager {
  provider = "aws-secrets-manager"
  configuration {
    region            = "eu-west-3"             # optional: default AWS region chain
    profile           = "zeenea"                # optional: named profile from ~/.aws
    access_key_id     = ${?AWS_ACCESS_KEY_ID}   # optional, together with secret_access_key
    secret_access_key = ${?AWS_SECRET_ACCESS_KEY}
  }
}

• Unlike the other providers, this provider uses underscores in setting names, such as access_key_id.
• The proxy requires hostname, port, scheme, username, and password. If any setting is missing, the scanner does not use the proxy.

Authentication¶

The scanner selects credentials in this order: access_key_id and secret_access_key, then profile, then the default AWS credentials chain (environment variables, instance role, ECS or EKS role, and other sources).

On AWS, we recommend using an instance role or a pod role.

Key and Fields¶

• Key: The secret name or ARN.
• Secret value: A JSON object whose values are all strings, for example, {"username": "USER_NAME", "password": "..."}. Other value types cause parsing to fail with aws_secret_manager_parse_error.
• Fields: The keys of the JSON object.

Setup on the AWS Side¶

Grant the IAM permission secretsmanager:GetSecretValue on the secrets. If the secrets are encrypted with a customer-managed KMS key, also grant kms:Decrypt.

HashiCorp Vault and OpenBao¶

provider = "hashicorp-vault"

Reads secrets from a KV v1 or KV v2 secrets engine.

The same provider works with OpenBao. Use the OpenBao URL and the same settings. Compatibility has been verified with OpenBao 2.7.0 using token and AppRole authentication with KV v2. However, OpenBao does not guarantee API compatibility with Vault.

Configuration¶

secret-manager {
  provider = "hashicorp-vault"
  configuration {
    url         = "https://<VAULT_HOST>:8200"   # required; http only on localhost
    namespace   = "<NAMESPACE>"                 # optional (Vault Enterprise / HCP / OpenBao namespaces)
    mount       = "secret"                      # default: KV mount path
    kv-version  = "2"                           # default; "1" for KV v1
    auth-method = "approle"                     # required: token | approle | kubernetes | cert
    auth-mount  = "approle"                     # optional: defaults to the method name
    # ...authentication settings, see below
    truststore-path = "/etc/zeenea/vault-ca.p12"   # optional
    timeout-seconds = "30"
    max-retries     = "2"
  }
  proxy { ... }   # optional
}

Authentication¶

• Login token: With approle, kubernetes and cert authentication, the scanner reuses the token until 90% of its lease has elapsed and then performs a new login to obtain a new token. After a 403 response, the scanner logs in again and retries the request once.

Key and Fields¶

• Key: The secret path within the mount, for example, zeenea/postgres-prod. The scanner refuses a key that is empty, starts with /, or has an empty or .. segment.
• Fields: The top-level keys of the secret. Numbers and booleans are converted to text. Nested objects and lists are ignored with vault_ignored_values warning.

Behavior¶

• Reading: KV v2 reads GET /v1/<mount>/data/<key> (latest version). KV v1 reads GET /v1/<mount>/<key>.
• Missing secret: A 404 response indicates that the secret does not exist.

Setup on the Vault or OpenBao Side¶

The following example uses KV v2 mounted at secret/.

# Policy "zeenea-read": read-only access to the scanner's secrets
path "secret/data/zeenea/*" {
  capabilities = ["read"]
}

vault policy write zeenea-read zeenea-read.hcl                    # OpenBao: bao policy write ...
vault write auth/approle/role/zeenea token_policies=zeenea-read token_ttl=1h
vault read  auth/approle/role/zeenea/role-id                      # -> role-id
vault write -f auth/approle/role/zeenea/secret-id                 # -> secret-id
vault kv put secret/zeenea/postgres-prod username=USER_NAME password=...

For KV v1, the policy path does not include the data/ segment (for example, path "secret/zeenea/*").

Google Cloud Secret Manager¶

provider = "gcp-secret-manager"

Reads a secret version from Google Cloud Secret Manager through its REST API.

Configuration¶

secret-manager {
  provider = "gcp-secret-manager"
  configuration {
    project          = "<PROJECT_ID>"               # required unless keys are full resource names
    auth-method      = "application-default"        # default | service-account-key | metadata
    credentials-path = "/etc/zeenea/gcp-sa.json"    # service-account-key (required); application-default (optional)
    truststore-path  = "..."                        # optional, e.g. for a TLS-inspecting proxy
    timeout-seconds  = "30"
    max-retries      = "2"
  }
  proxy { ... }   # optional
}

Authentication¶

Only service_account key files are supported. authorized_user (gcloud user credentials), external_account (Workload Identity Federation), and impersonation files are rejected at startup with a clear error message.

Key and Fields¶

Secret IDs and versions can contain only letters, digits, hyphens (-), and underscores (_).

• If a secret value is a JSON object, its top-level keys are returned as fields. Numbers and booleans are converted to text, and nested values are ignored.
• Any other value (for example, a plain password) is returned as a single field named value.
• The payload checksum (CRC32C) is verified.

Setup on the GCP Side¶

gcloud secrets create zeenea-postgres --data-file=secret.json      # {"username": "...", "password": "..."}
gcloud secrets add-iam-policy-binding zeenea-postgres \
  --member="serviceAccount:<SCANNER_SA>@<PROJECT>.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

To follow the principle of least privilege, grant the role on each secret rather than on the entire project.

Security Recommendations¶

• Least privilege: Give the scanner's identity read-only access to the secrets it needs, and nothing else. For example, use a Vault policy on a single path prefix or per-secret IAM permissions on GCP.

• Avoid long-lived secrets on disk when possible:

  • AWS: Use an instance role or pod role.
  • GCP: Use the metadata server.
  • Vault: Use Kubernetes authentication.

• When a bootstrap secret is unavoidable (for example, an AppRole secret-id or a keystore password):

  • Pass it through an environment variable (${?VAR}) rather than storing it as plain text in application.conf.
  • Restrict the key and keystore files to the scanner's service user using chmod 600.
  • Rotate secrets regularly.

• Dedicated service account: Run the scanner under its own OS user, which the file permissions rely on.

• TLS: Keep the default certificate verification enabled. Add your CA to a truststore rather than disabling verification. The scanner does not provide an option to disable these checks.

• Audit: Monitor the secret manager's access logs for the scanner's identity (for example, Vault audit logs, AWS CloudTrail, or Google Cloud Audit Logs).

• Logs: The scanner never logs secret values, tokens, or private keys. It logs keys (secret names or queries), status codes, and the error messages of the provider.

Troubleshooting¶

Log Prefixes¶

Log events start with a provider-specific prefix:

Common Issues¶