Copy page

Secret Masking Policy

This policy is deprecated. Use the Data Loss
Prevention
policy instead. It detects the same Zuplo API keys, GitHub tokens, and private
key blocks via its secret-zuplo, secret-github, and secret-private-key
recognizers, plus 60+ more built-in entities, and can block or log a response
rather than only masking it. This policy will continue to work but will be
removed in a future version of Zuplo.

Deprecated: Use the Data Loss Prevention policy instead. It detects everything this policy does plus 60+ more entity types, and can block or log a response rather than only masking it. This policy will continue to work but will be removed in a future version of Zuplo. See Migrating to Data Loss Prevention below.

The Secret Masking policy searches for and masks common secrets and replaces them with a placeholder. Secrets that are automatically masked include:

• Zuplo API keys
• GitHub Tokens and Personal Access Tokens
• Private key blocks
• And more!

See the policy documentation for a full description of secrets that are masked via this policy.

This is especially useful as an outbound policy for MCP servers, APIs that interface with user generated content, or AI consumers.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

Code
{
  "name": "my-secret-masking-outbound-policy",
  "policyType": "secret-masking-outbound",
  "handler": {
    "export": "SecretMaskingOutboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "additionalPatterns": [],
      "mask": "[REDACTED]"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be secret-masking-outbound.
• handler.export <string> - The name of the exported type. Value should be SecretMaskingOutboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• mask <string> - The string to replace detected secrets with. Equivalent to the Data Loss Prevention policy's mask option. Defaults to "[REDACTED]".
• additionalPatterns <string[]> - Extra regex patterns for secrets to mask. Replaced by the Data Loss Prevention policy's customPatterns option, which also accepts a name, confidence, and context words per pattern.

Using the Policy

This policy masks sensitive secrets in outgoing requests to prevent exposure to downstream consumers. This is especially useful for AI agents and MCP clients (where LLMs should not consume potentially sensitive user generated information or poisoned agents are attempting to leak information they have access to).

Configuration

• mask: The mask to use when redacting information. Default: [REDACTED]
• additionalPatterns: Additional Regex patterns to mask secrets with (make sure to correctly escape "meta escape" characters: i.e., \b should be escaped \\b to avoid a JSON parsing error. Otherwise, you may see build errors).

Usage

Apply this policy to outbound requests in your route configuration:

Code
{
  "policies": [
    {
      "name": "secret-masking-policy",
      "policyType": "secret-masking-outbound",
      "handler": {
        "export": "SecretMaskingOutboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "mask": "<SECRET MASKED>",
          "additionalPatterns": ["\\b(\\w+)=\\w+\\b"]
        }
      }
    }
  ]
}

Masked secrets

• Zuplo API keys (i.e. zpka_xxx)
• GitHub Tokens and Personal Access Tokens (i.e. ghp_xxx)
• Private key blocks (i.e. BEGIN PRIVATE KEY and END PRIVATE KEY)

Migrating to Data Loss Prevention

The Data Loss Prevention policy supersedes this one. Its secret-zuplo, secret-github, and secret-private-key recognizers use the same patterns this policy does, so selecting them reproduces the current behavior exactly:

Code
{
  "policies": [
    {
      "name": "dlp-outbound",
      "policyType": "data-loss-prevention-outbound",
      "handler": {
        "export": "DataLossPreventionOutboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "action": "mask",
          "entities": ["secret-zuplo", "secret-github", "secret-private-key"],
          "mask": "<SECRET MASKED>",
          "customPatterns": [
            { "name": "key-value-pair", "pattern": "\\b(\\w+)=\\w+\\b" }
          ]
        }
      }
    }
  ]
}

Option mapping:

• mask becomes mask, which only applies when action is mask.
• additionalPatterns becomes customPatterns, where each entry takes a name and a pattern plus optional confidence and context words.

Two behavior differences to be aware of when you migrate:

• Drop entities entirely to enable the whole built-in catalog — 60+ recognizers covering PII, payment and bank identifiers, national IDs, and API keys for dozens of vendors — rather than only the three secret types this policy handles.
• Data Loss Prevention only inspects text content types (JSON, XML, form-encoded, text/*) and passes binary bodies through untouched, whereas this policy reads every response body as text. Set contentTypes to override the allow-list.

Use action to do more than mask: block replaces the response with a 422 that lists only the detected entity names, and log records a warning and returns the response unchanged. Pair it with Data Loss Prevention - Inbound to scan incoming requests as well.

Read more about how policies work