Skip to main content

Secret Masking Configuration

Atmos provides provably safe secrets maskingβ€”all output channels route through the masking layer to ensure secrets never leak through any path. Sensitive data (secrets, API keys, tokens) is automatically masked in all terminal output to prevent accidental exposure in logs, screenshots, or CI/CD pipelines.

Overview​

Secret masking operates at the I/O layer, intercepting all output before it reaches stdout/stderr. This ensures secrets are masked regardless of:

  • Output format (plain text, JSON, YAML)
  • Output destination (terminal, file, pipe)
  • Command type (terraform, helmfile, custom commands)

Quick Start​

Enable Masking (Default)​

Masking is enabled by default with 8 built-in patterns for common secrets:

# atmos.yaml
settings:
  terminal:
    mask:
      enabled: true  # Default: true

Disable Masking for Debugging​

Use the CLI flag to disable masking temporarily:

atmos terraform plan --mask=false

Configuration​

Full Configuration Example​

# atmos.yaml
settings:
  terminal:
    mask:
      enabled: true                    # Enable/disable masking (default: true)
      replacement: "[REDACTED]"        # Custom replacement text (default: ***MASKED***)
      patterns:                        # Custom regex patterns
        - 'demo-key-[A-Za-z0-9]{16}'
        - 'internal-[a-f0-9]{32}'
        - 'tkn_(live|test)_[a-zA-Z0-9]{24}'
      literals:                        # Exact string matches
        - "super-secret-demo-value"
        - "my-api-key-12345"

Configuration Options​

enabled

Enable or disable secret masking globally.

  • Type: boolean
  • Default: true
  • Example: enabled: false
replacement

Text to replace masked secrets with.

  • Type: string
  • Default: "***MASKED***"
  • Example: replacement: "[REDACTED]"
patterns

Custom regex patterns to match organization-specific secrets. Patterns are added to the built-in patterns, not replacing them.

  • Type: array of strings
  • Default: []
  • Example: 
    patterns:
      - 'mycompany-key-[A-Za-z0-9]{16}'
      - 'internal-[a-f0-9]{32}'
literals

Exact string values to mask. Use for known sensitive values that don't follow a pattern.

  • Type: array of strings
  • Default: []
  • Example: 
    literals:
      - "my-hardcoded-secret"
      - "test-api-key-12345"

Custom Patterns​

Beyond the built-in patterns, you can define organization-specific patterns to mask internal tokens, API keys, or secrets that follow your naming conventions.

Regex Patterns​

Use the patterns option to define regex patterns:

settings:
  terminal:
    mask:
      patterns:
        # Internal API tokens
        - 'mycompany-api-[A-Za-z0-9]{32}'
        # Service account keys
        - 'svc_[a-z]+_[A-Za-z0-9]{24}'
        # Custom JWT-like tokens
        - 'tkn_(live|test)_[a-zA-Z0-9]{24}'

Literal Values​

Use the literals option for exact string matches:

settings:
  terminal:
    mask:
      literals:
        - "known-secret-value"
        - "hardcoded-test-key"

This is useful for:

  • Test secrets that don't follow patterns
  • Known sensitive values from configuration
  • Legacy credentials with unusual formats

Built-In Patterns​

Atmos includes 8 built-in patterns for common secret formats:

  1. GitHub Personal Access Tokens

    • Classic format: ghp_[A-Za-z0-9]{36}
    • OAuth format: gho_[A-Za-z0-9]{36}
    • New format: github_pat_[A-Za-z0-9]{22}_[A-Za-z0-9]{59}

  2. GitLab Personal Access Tokens

    • Format: glpat-[A-Za-z0-9\-_]{20}

  3. OpenAI API Keys

    • Format: sk-[A-Za-z0-9]{48}

  4. AWS Access Key ID

    • Format: AKIA[0-9A-Z]{16}

  5. AWS Secret Access Key

    • Format: 40-character base64 string

  6. Bearer Tokens

    • Format: Bearer [A-Za-z0-9\-._~+/]+=*

Auto-Masked Environment Variables​

The following environment variables are automatically detected and masked:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN
  • GITHUB_TOKEN
  • GH_TOKEN
  • GITLAB_TOKEN
  • CI_JOB_TOKEN
  • DATADOG_API_KEY
  • DD_API_KEY
  • ANTHROPIC_API_KEY

CLI Flags​

--mask​

Enable or disable masking for a single command:

# Disable masking for debugging
atmos terraform plan --mask=false

# Explicitly enable masking (default)
atmos terraform plan --mask=true

How It Works​

Masking Flow​

  1. Initialization - Atmos loads masking configuration on startup
  2. Pattern Registration - Built-in patterns and env var values are registered
  3. Output Interception - All output goes through the masking engine
  4. Secret Detection - Regex patterns and literal values are matched
  5. Replacement - Matched secrets are replaced with ***MASKED***

Format-Aware Masking​

Secrets are detected in multiple formats:

  • Plain text: sk-abc123def456
  • JSON: {"api_key": "sk-abc123def456"}
  • YAML: api_key: sk-abc123def456
  • URL-encoded: key=sk%2Dabc123def456
  • Base64: c2stYWJjMTIzZGVmNDU2
  • Hex: 736b2d616263313233646566343536

Performance​

Masking has minimal performance impact:

  • Initialization: <50ms
  • Per-operation: <3ΞΌs (no secrets), <16ΞΌs (with secrets)
  • Memory: ~100KB for pattern storage

Use Cases​

Production Deployments​

Prevent secrets from appearing in CI/CD logs:

# atmos.yaml
settings:
  terminal:
    mask:
      enabled: true
# Run deployment - secrets automatically masked
atmos terraform apply

Local Development​

Disable masking for debugging:

# See full output for troubleshooting
atmos terraform plan --mask=false

Screenshot Generation​

Enable masking when generating documentation screenshots:

settings:
  terminal:
    mask:
      enabled: true
# Generate screenshots with masked secrets
atmos terraform plan | screenshot-tool

Security Considerations​

What Gets Masked​

  • AWS credentials (access keys, secret keys, session tokens)
  • GitHub/GitLab tokens and PATs
  • OpenAI API keys
  • Bearer tokens
  • Values from configured environment variables

What Does NOT Get Masked​

  • Non-secret configuration values
  • Resource names and identifiers
  • Public URLs and endpoints
  • Log messages and status text

False Positives​

If legitimate values are incorrectly masked:

  1. Disable masking temporarily:

    atmos terraform plan --mask=false

  2. Report pattern issue: Open an issue with the false positive pattern

False Negatives​

If secrets are NOT being masked:

  1. Check pattern coverage: Built-in patterns may not cover your secret format
  2. Add custom patterns: Define patterns in atmos.yaml for organization-specific secrets
  3. Use literals: Add exact values to the literals configuration
  4. Contribute patterns: Consider contributing common patterns to Atmos

Troubleshooting​

Secrets Not Being Masked​

Problem: Expected secrets appear in output.

Solutions:

  1. Verify masking is enabled:

    settings:
      terminal:
        mask:
          enabled: true

  2. Check if secret format matches built-in patterns

  3. Add custom patterns for organization-specific secrets:

    settings:
      terminal:
        mask:
          patterns:
            - 'your-secret-pattern-[A-Za-z0-9]+'
          literals:
            - "known-secret-value"

  4. Check environment variables are set correctly

Legitimate Values Masked​

Problem: Non-secret values are being masked.

Solutions:

  1. Temporarily disable masking for debugging:

    atmos terraform plan --mask=false

  2. Report false positive pattern

Performance Issues​

Problem: Masking slows down output.

Solutions:

  1. Check for extremely large output (>10MB)
  2. Disable masking if performance is critical: 
    atmos terraform plan --mask=false

Example​

secrets-maskingView full example

Secrets Masking Example

This example demonstrates Atmos's automatic secrets masking feature.

Overview

Atmos automatically masks sensitive values in terminal output to prevent accidental exposure of secrets. The masking system includes:

  • Built-in patterns: AWS keys, API tokens, GitHub tokens, and 120+ patterns from the Gitleaks library
  • Custom patterns: User-defined regex patterns in atmos.yaml
  • Custom literals: Exact string matches for known secret values

Configuration

See atmos.yaml for the masking configuration:

settings:
  terminal:
    mask:
      enabled: true
      replacement: "[REDACTED]"
      patterns:
        - 'demo-key-[A-Za-z0-9]{16}'
        - 'internal-[a-f0-9]{32}'
        - 'tkn_(live|test)_[a-zA-Z0-9]{24}'
      literals:
        - "super-secret-demo-value"
        - "my-api-key-12345"

Testing the Feature

  1. Run a terraform plan with secrets in output:

    cd examples/secrets-masking
    atmos terraform plan secrets-demo -s demo-dev-test

  2. Verify masking in terraform output: The component outputs secrets which will be masked as [REDACTED] in the output.

  3. Disable masking to compare:

    atmos terraform plan secrets-demo -s demo-dev-test --mask=false

What Gets Masked

  1. Built-in patterns (always active):

    • AWS Access Key IDs (AKIA...)
    • AWS Secret Access Keys
    • GitHub tokens (ghp_..., gho_..., ghu_...)
    • Generic API keys and passwords
    • JWT tokens
    • Private keys

  2. Custom patterns (from atmos.yaml):

    • demo-key-XXXX... format
    • internal-XXXX... format
    • tkn_live_... and tkn_test_... tokens

  3. Custom literals (from atmos.yaml):

    • super-secret-demo-value
    • my-api-key-12345

Masking Coverage

Secrets are masked across all output channels:

  • Terraform/Helmfile command output (stdout/stderr)
  • Custom command output
  • Atmos logs
  • Error messages
  • Documentation display

Disabling Masking

To disable masking for debugging (not recommended in CI/CD):

# Via command-line flag
atmos terraform plan component -s stack --mask=false

# Via environment variable
export ATMOS_TERMINAL_MASK_ENABLED=false
Browse all files

See Also​