Configuration Overview

SecretZero uses a declarative configuration approach where all your secrets, providers, and policies are defined in a Secretfile.yml. This page provides an overview of configuration concepts and structure.

Configuration Files

Secretfile.yml

The primary configuration file that defines:

• Secret definitions and generation rules
• Provider configurations and authentication
• Target storage locations
• Templates for complex secrets
• Rotation policies and compliance rules
• Variables for dynamic configuration

Location: Project root (default: ./Secretfile.yml)

version: '1.0'

variables:
  environment: production

providers:
  aws:
    kind: aws
    auth:
      kind: ambient

secrets:
  - name: database_password
    kind: random_password
    config:
      length: 32
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /app/db-password

Complete Secretfile Reference →

Lockfile

The lockfile (.gitsecrets.lock) is automatically generated and tracks:

• Generated secret hashes (SHA-256)
• Creation and update timestamps
• Rotation history and counts
• Secret metadata

Location: Project root (default: ./.gitsecrets.lock)

Version Control

The lockfile contains hashes, not actual secret values. While it can be committed to version control, consider your security requirements carefully.

Example lockfile structure:

version: '1.0'
secrets:
  database_password:
    hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    created_at: '2024-01-15T10:30:00Z'
    updated_at: '2024-01-15T10:30:00Z'
    last_rotated: '2024-01-15T10:30:00Z'
    rotation_count: 0
    metadata:
      kind: random_password
      length: 32

Configuration Hierarchy

SecretZero resolves configuration in the following order (highest to lowest priority):

1. Environment Variables - Runtime environment variables
2. Command-line Arguments - CLI flags and options
3. Secretfile Variables - Variables defined in variables section
4. Provider Defaults - Default provider configurations
5. Built-in Defaults - SecretZero's default values

Example

variables:
  # Can be overridden by environment variable: AWS_REGION
  aws_region: us-east-1

  # Use environment variable with fallback
  environment: ${ENVIRONMENT:-dev}

providers:
  aws:
    config:
      # Variable interpolation with fallback
      region: "{{var.aws_region or 'us-west-2'}}"

Core Concepts

Providers

Providers are the backends for storing and retrieving secrets. They handle:

• Authentication and authorization
• Secret storage and retrieval
• Provider-specific operations

Supported provider types:

• Cloud: aws, azure, vault
• CI/CD: github, gitlab, jenkins
• Container: kubernetes
• Local: local (file-based)

Each provider can have multiple named configurations:

providers:
  aws-prod:
    kind: aws
    auth:
      kind: assume_role
      config:
        role_arn: arn:aws:iam::123456789012:role/Prod

  aws-dev:
    kind: aws
    auth:
      kind: ambient
      config:
        profile: dev

Secrets

Secrets are the core entities managed by SecretZero. Each secret definition includes:

• Name: Unique identifier for the secret
• Kind: Generator type or template reference
• Config: Generator-specific configuration
• Targets: Where to store the generated value
• Rotation Policy: When to regenerate the secret

secrets:
  - name: api_key
    kind: random_password
    rotation_period: 90d
    one_time: false
    config:
      length: 64
      special: false
    targets:
      - provider: aws
        kind: secrets_manager
        config:
          name: /prod/api-key

Templates

Templates define reusable secret structures with multiple fields:

templates:
  database_credentials:
    description: Complete database connection credentials
    fields:
      host:
        generator:
          kind: static
          config:
            default: db.example.com
      port:
        generator:
          kind: static
          config:
            default: "5432"
      username:
        generator:
          kind: static
          config:
            default: appuser
      password:
        generator:
          kind: random_password
          config:
            length: 32
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: json

# Use the template
secrets:
  - name: prod_database
    kind: templates.database_credentials

Targets

Targets specify where generated secrets should be stored. A single secret can have multiple targets:

secrets:
  - name: shared_secret
    kind: random_password
    config:
      length: 32
    targets:
      # Store in AWS
      - provider: aws
        kind: ssm_parameter
        config:
          name: /app/secret

      # Also store locally
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv

      # And in Kubernetes
      - provider: kubernetes
        kind: kubernetes_secret
        config:
          namespace: production
          secret_name: app-secret

Variables

Variables enable dynamic configuration and reusability:

variables:
  environment: production
  region: us-east-1
  app_name: myapp

secrets:
  - name: config_secret
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          # Variable interpolation using Jinja2 syntax
          name: /{{var.environment}}/{{var.app_name}}/secret
          tags:
            Environment: "{{var.environment}}"
            Region: "{{var.region}}"

Learn more about variables →

Policies

Policies enforce compliance and security requirements:

policies:
  rotation_required:
    kind: rotation
    require_rotation_period: true
    severity: warning
    enabled: true

  max_rotation_age:
    kind: rotation
    max_age: 90d
    severity: error
    enabled: true

  production_security:
    kind: access
    allowed_targets:
      - ssm_parameter
      - secrets_manager
      - vault_kv
    severity: error
    enabled: true

Configuration Validation

SecretZero validates your configuration before execution:

Schema Validation

Validates structure and required fields:

secretzero validate

Output:

Validating: Secretfile.yml
✓ Configuration is valid

Configuration Summary:
  Version: 1.0
  Variables: 3
  Providers: 2
  Secrets: 5
  Templates: 1

Provider Testing

Tests provider connectivity and authentication:

secretzero test

Output:

Testing Provider Connectivity:

  • aws: ✓ Connected to AWS (us-east-1)
  • vault: ✓ Connected to Vault (http://localhost:8200)
  • local: ✓ Local provider (always available)

All provider tests passed!

Policy Checking

Validates compliance with defined policies:

secretzero policy

Output:

Checking policy compliance...

Warnings:
  ⚠ api_token: No rotation_period defined
    → Add rotation_period to enable automatic rotation

Summary:
  Errors: 0
  Warnings: 1
  Info: 0

Learn more about validation →

Environment-Specific Configuration

Using Variables

Define environment-specific values:

variables:
  environment: ${ENVIRONMENT:-dev}
  aws_account: ${AWS_ACCOUNT_ID}

secrets:
  - name: app_secret
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /{{var.environment}}/app/secret

Multiple Secretfiles

Manage different environments with separate files:

# Development
secretzero sync -f Secretfile.dev.yml

# Production
secretzero sync -f Secretfile.prod.yml

Variable Files

Load variables from external sources:

# Secretfile.yml
version: '1.0'

variables:
  # Load from environment
  environment: ${ENVIRONMENT}
  region: ${AWS_REGION}

  # Or provide defaults
  app_name: ${APP_NAME:-myapp}

Configuration Best Practices

1. Use Version Control

Commit Secretfile.yml to track changes:

git add Secretfile.yml
git commit -m "Add database credentials configuration"

2. Separate Environments

Use variables or separate files for different environments:

variables:
  environment: ${ENVIRONMENT:-dev}

secrets:
  - name: database_url
    kind: static
    config:
      default: ${DATABASE_URL}
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /{{var.environment}}/database-url

3. Document Your Secrets

Use metadata and descriptions:

metadata:
  project: myapp
  owner: platform-team
  description: Production secrets for MyApp

templates:
  api_credentials:
    description: External API authentication credentials
    fields:
      api_key:
        description: API key from provider dashboard
        generator:
          kind: static

4. Implement Rotation Policies

Define rotation periods for all secrets:

secrets:
  - name: database_password
    kind: random_password
    rotation_period: 90d  # SOC2 compliance
    config:
      length: 32

5. Use Templates for Complex Secrets

Group related secret fields:

templates:
  oauth_credentials:
    description: OAuth client credentials
    fields:
      client_id:
        generator:
          kind: static
      client_secret:
        generator:
          kind: random_password
          config:
            length: 64
      redirect_uri:
        generator:
          kind: static

6. Validate Before Syncing

Always validate configuration first:

# Validate
secretzero validate

# Test providers
secretzero test

# Check policies
secretzero policy

# Dry run
secretzero sync --dry-run

# Execute
secretzero sync

Next Steps

• Secretfile Reference

  ---

  Complete specification of all Secretfile.yml fields and options

  Read Reference →

• Variables

  ---

  Learn about variable interpolation and environment variables

  Learn About Variables →

• Validation

  ---

  Understand schema validation and error handling

  Validation Guide →

• CLI Commands

  ---

  Learn how to use SecretZero commands

  CLI Reference →