Skip to content

User Guide

Welcome to the SecretZero User Guide! This comprehensive reference covers everything you need to know about using SecretZero for secret management.

What's in This Guide?

This guide is organized into three main sections covering configuration, CLI commands, and advanced topics.

Quick Navigation

Core Concepts

Before diving into the details, familiarize yourself with these core concepts:

Secretfile.yml

The central configuration file that defines all your secrets, providers, targets, and policies. Think of it as your secret infrastructure-as-code.

version: '1.0'

secrets:
  - name: my_password
    kind: random_password
    config:
      length: 32
    targets:
      - provider: aws
        kind: ssm_parameter

Learn more about Secretfile →

Providers

Providers are the backends where secrets are stored or retrieved. SecretZero supports:

  • Cloud: AWS, Azure, HashiCorp Vault
  • CI/CD: GitHub Actions, GitLab CI, Jenkins
  • Container: Kubernetes
  • Local: File storage in various formats

Learn about providers →

Generators

Generators create secret values using different methods:

  • random_password: Cryptographically secure passwords
  • random_string: Random alphanumeric strings
  • static: Static values with validation
  • script: Execute external scripts
  • api: Fetch from external APIs

Learn about generators →

Targets

Targets specify where generated secrets should be stored. A single secret can have multiple targets, allowing you to sync secrets across different platforms.

Learn about targets →

Lockfile

The .gitsecrets.lock file tracks generated secrets using SHA-256 hashes, enabling:

  • Idempotent secret generation
  • Rotation tracking
  • Drift detection
  • Audit history

Learn about lockfiles →

Common Workflows

Initial Setup

# Create a new Secretfile
secretzero create

# Validate configuration
secretzero validate

# Test provider connectivity
secretzero test

Secret Generation

# Preview what would be generated
secretzero sync --dry-run

# Generate and sync secrets
secretzero sync

# Show information about a secret
secretzero show my_password

Secret Rotation

# Check which secrets need rotation
secretzero rotate --dry-run

# Rotate secrets based on policies
secretzero rotate

# Force rotate a specific secret
secretzero rotate --force my_password

Policy and Compliance

# Check policy compliance
secretzero policy

# Fail on warnings
secretzero policy --fail-on-warning

# Detect drift
secretzero drift

Documentation Structure

Configuration

Learn how to configure SecretZero:

CLI Commands

Complete reference for all CLI commands:

  • CLI Overview - All available commands
  • init - Initialize new projects
  • validate - Validate configuration
  • sync - Generate and sync secrets
  • show - Display secret information
  • rotate - Rotate secrets
  • policy - Check policy compliance
  • drift - Detect configuration drift
  • test - Test provider connectivity

Components

Deep dives into SecretZero components:

Best Practices

Secret Organization

# Group related secrets using templates
templates:
  database_credentials:
    description: Database connection credentials
    fields:
      username:
        generator:
          kind: static
          config:
            default: dbuser
      password:
        generator:
          kind: random_password
          config:
            length: 32

Environment Management

# Use variables for environment-specific configuration
variables:
  environment: ${ENVIRONMENT:-dev}
  aws_region: ${AWS_REGION:-us-east-1}

secrets:
  - name: api_key
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /{{var.environment}}/api-key

Rotation Policies

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

One-Time Secrets

# Secrets that should only be generated once
secrets:
  - name: encryption_key
    kind: random_password
    one_time: true
    rotation_period: 180d  # Warning only
    config:
      length: 64

Getting Help

Documentation

Community

Next Steps