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

Sensitive Terraform/OpenTofu outputs may be written to disk

Disabling masking with --mask=false, ATMOS_MASK=false, or settings.terminal.mask.enabled: false also disables secret-safe TF_VAR_ delivery for automatically registered sensitive Terraform/OpenTofu outputs. Those values may be written to generated .tfvars.json files.

Use this compatibility and debugging opt-out only when writing those values to disk is acceptable. Declared secrets continue to use the existing no-secrets-on-disk handling.

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.

Setting this to false has the same security implications as --mask=false: automatically registered sensitive Terraform/OpenTofu outputs may be written to generated .tfvars.json files. See Disable Masking for Debugging.

• 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

atmos secrets masking

00:00.0 / 00:00.0

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

• secrets-masking/components/terraform/secrets-demo/.demo-dev-test-secrets-demo.terraform.lock.hcl
• secrets-masking/components/terraform/secrets-demo/.terraform.lock.hcl
• secrets-masking/components/terraform/secrets-demo/main.tf
• secrets-masking/components/terraform/secrets-demo/variables.tf
• secrets-masking/components/terraform/secrets-demo/versions.tf
• secrets-masking/stacks/deploy/dev.yaml
• secrets-masking/.gitignore
• secrets-masking/atmos.yaml
• secrets-masking/README.md

Browse all files

See Also

• Terminal Configuration - Terminal settings and options