Core Concepts¶

This guide explains the fundamental concepts and architecture of SecretZero. Understanding these concepts will help you design effective secret management strategies.

Overview¶

SecretZero follows a declarative, infrastructure-as-code approach to secret management. You define what secrets you need, how they should be generated, and where they should be stored—SecretZero handles the rest.

graph LR
    A[Secretfile.yml] --> B[SecretZero]
    B --> C[Generators]
    B --> D[Providers]
    B --> E[Targets]
    C --> F[Secret Values]
    D --> E
    F --> E
    E --> G[Storage]
    E --> H[Lockfile]

Secretfile Structure¶

The Secretfile.yml is the single source of truth for all your secrets. It's a YAML configuration file that describes:

What secrets you need
How they should be generated
Where they should be stored
When they should be rotated

Basic Structure¶

version: "1.0"

metadata:
  name: my-project
  description: Project secrets
  owner: platform-team

variables:
  environment: development
  region: us-east-1

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

secrets:
  api_key:
    template:
      type: api_key
      fields:
        - name: value
          generator:
            type: random-string
            length: 32
    targets:
      - type: local-file
        path: .env
        format: dotenv

policies:
  rotation_required:
    type: rotation
    config:
      require_rotation_period: true

Component Breakdown¶

Version¶

version: "1.0"

Specifies the Secretfile schema version. Used for backward compatibility.

Metadata¶

metadata:
  name: my-project
  description: Project description
  owner: team-name
  environments:
    - development
    - staging
    - production
  compliance:
    - soc2
    - iso27001

Project metadata for documentation and compliance tracking:

name: Project identifier
description: Human-readable description
owner: Team or person responsible
environments: Deployment targets
compliance: Standards to enforce (SOC2, ISO27001)

Variables¶

variables:
  environment: development
  aws_region: us-east-1
  db_host: localhost

Reusable values for interpolation throughout the configuration:

Can be overridden by environment variables
Support default values with Jinja2 syntax
Enable environment-specific configurations

Interpolation:

targets:
  - type: aws-secretsmanager
    name: "/{{var.environment}}/db/password"
    region: "{{var.aws_region}}"

Providers¶

Providers manage authentication and connectivity to secret storage backends.

Provider Types¶

graph TB
    A[Providers] --> B[Local]
    A --> C[Cloud]
    A --> D[CI/CD]
    A --> E[Container]
    C --> F[AWS]
    C --> G[Azure]
    C --> H[Vault]
    D --> I[GitHub]
    D --> J[GitLab]
    D --> K[Jenkins]
    E --> L[Kubernetes]

Provider Configuration¶

providers:
  # AWS provider
  aws:
    kind: aws
    auth:
      kind: ambient  # or token, assume_role
      config:
        region: us-east-1
        role_arn: arn:aws:iam::123456789012:role/SecretAdmin  # for assume_role

  # Azure provider
  azure:
    kind: azure
    auth:
      kind: default  # or managed_identity, cli
      config:
        subscription_id: your-subscription-id

  # HashiCorp Vault
  vault:
    kind: vault
    auth:
      kind: token  # or approle
      config:
        url: https://vault.example.com
        token: ${VAULT_TOKEN}

  # GitHub Actions
  github:
    kind: github
    auth:
      kind: token
      config:
        token: ${GITHUB_TOKEN}

  # Kubernetes
  kubernetes:
    kind: kubernetes
    auth:
      kind: ambient
      config:
        kubeconfig: ~/.kube/config
        context: production

Authentication Methods¶

Different providers support different auth methods:

Provider	Auth Methods
AWS	`ambient`, `profile`, `assume_role`
Azure	`default`, `managed_identity`, `cli`
Vault	`token`, `approle`
GitHub	`token`
GitLab	`token`
Jenkins	`token`
Kubernetes	`ambient`, `in_cluster`, `token`

Secrets¶

Secrets are the core data structures that SecretZero manages.

Secret Definition¶

secrets:
  database_password:
    # Optional: Secret template type
    template:
      type: password
      fields:
        - name: value
          generator:
            type: random-password
            length: 32

    # Optional: One-time generation
    one_time: false

    # Optional: Rotation policy
    rotation:
      period: 90d

    # Required: Where to store the secret
    targets:
      - type: local-file
        path: .env
        format: dotenv

Secret Types¶

Secrets can be simple (single value) or complex (multiple fields):

Simple Secret¶

api_key:
  template:
    type: api_key
    fields:
      - name: value
        generator:
          type: random-string
          length: 32

Complex Secret (Template)¶

database_credentials:
  template:
    type: database
    fields:
      - name: username
        generator:
          type: static
          value: myapp_user
      - name: password
        generator:
          type: random-password
          length: 32
      - name: host
        generator:
          type: static
          value: db.example.com
      - name: port
        generator:
          type: static
          value: "5432"

Generators¶

Generators create secret values using various algorithms and sources.

Generator Types¶

graph TB
    A[Generators] --> B[Random]
    A --> C[Static]
    A --> D[Script]
    A --> E[API]
    B --> F[random-password]
    B --> G[random-string]
    C --> H[static value]
    D --> I[External command]
    E --> J[HTTP API call]

Random Password¶

Generates cryptographically secure passwords:

generator:
  type: random-password
  length: 32
  include_upper: true
  include_lower: true
  include_numbers: true
  include_symbols: true
  exclude_characters: '"@/\`'

Features:

Uses Python's secrets module (cryptographically secure)
Customizable character sets
Character exclusion for compatibility
Minimum length enforcement

Random String¶

Generates random alphanumeric strings:

generator:
  type: random-string
  length: 40
  charset: hex  # alphanumeric, alpha, numeric, hex

Use cases:

API tokens
Session IDs
Webhook secrets

Static¶

Provides static values with optional validation:

generator:
  type: static
  value: my-value
  validation: ^[a-zA-Z0-9\-\.]+$  # Optional regex

Use cases:

Usernames
API endpoints
Configuration values

Script¶

Executes external commands:

generator:
  type: script
  command: ssh-keygen
  args:
    - -t
    - rsa
    - -b
    - "4096"
    - -f
    - /dev/stdout
    - -N
    - ""
  timeout: 30

Use cases:

SSH key generation
Certificate creation
Custom secret generation logic

Targets¶

Targets define where secrets are stored.

Target Types¶

graph TB
    A[Targets] --> B[Local]
    A --> C[Cloud]
    A --> D[CI/CD]
    A --> E[Container]

    B --> B1[local-file]

    C --> C1[aws-secretsmanager]
    C --> C2[aws-ssm-parameter]
    C --> C3[azure-keyvault]
    C --> C4[vault-kv]

    D --> D1[github-secret]
    D --> D2[gitlab-variable]
    D --> D3[jenkins-credential]

    E --> E1[kubernetes-secret]
    E --> E2[external-secret]

Local File Target¶

Store secrets in local files:

targets:
  - type: local-file
    path: .env
    format: dotenv  # dotenv, json, yaml, toml
    merge: true
    key: API_KEY  # Optional: custom key name

Formats:

Dotenv (.env):

API_KEY=value123
DATABASE_PASSWORD=secure456

JSON:

{
  "api_key": "value123",
  "database_password": "secure456"
}

YAML:

api_key: value123
database_password: secure456

Cloud Targets¶

AWS Secrets Manager¶

targets:
  - type: aws-secretsmanager
    provider: aws
    name: /myapp/database/password
    description: Database password
    kms_key_id: alias/myapp  # Optional

AWS SSM Parameter Store¶

targets:
  - type: aws-ssm-parameter
    provider: aws
    name: /myapp/api_key
    type: SecureString  # String, SecureString, StringList
    tier: Standard  # Standard, Advanced
    overwrite: true

Azure Key Vault¶

targets:
  - type: azure-keyvault
    provider: azure
    vault_url: https://myvault.vault.azure.net
    secret_name: database-password

HashiCorp Vault¶

targets:
  - type: vault-kv
    provider: vault
    path: myapp/database/password
    mount_point: secret
    version: 2  # KV version

CI/CD Targets¶

GitHub Actions¶

targets:
  - type: github-secret
    provider: github
    owner: myorg
    repo: myrepo
    environment: production  # Optional

GitLab CI/CD¶

targets:
  - type: gitlab-variable
    provider: gitlab
    project: mygroup/myproject
    environment_scope: production
    protected: true
    masked: true

Jenkins¶

targets:
  - type: jenkins-credential
    provider: jenkins
    credential_id: api-key-prod
    credential_type: string  # string, username_password
    description: Production API Key

Kubernetes Targets¶

targets:
  - type: kubernetes-secret
    provider: kubernetes
    namespace: production
    secret_name: app-secrets
    secret_type: Opaque  # Opaque, kubernetes.io/tls, etc.
    data_key: password

Templates¶

Templates define reusable secret structures with multiple fields.

Template Definition¶

templates:
  database_config:
    description: Complete database configuration
    fields:
      username:
        description: Database username
        generator:
          type: static
          value: app_user
      password:
        description: Database password
        generator:
          type: random-password
          length: 32
      host:
        generator:
          type: static
          value: "{{var.db_host}}"
      port:
        generator:
          type: static
          value: "5432"
    targets:
      - type: local-file
        path: config/database.json
        format: json

Using Templates¶

secrets:
  production_database:
    kind: templates.database_config
    variables:
      db_host: prod-db.example.com

  staging_database:
    kind: templates.database_config
    variables:
      db_host: staging-db.example.com

Lockfile¶

The lockfile (.gitsecrets.lock) tracks the state of all secrets.

Purpose¶

Change Detection: Determine if secrets have changed
Rotation Tracking: Record when secrets were last rotated
One-Time Secrets: Prevent regeneration of one-time secrets
Audit Trail: Historical record of secret operations

Structure¶

{
  "version": "1.0",
  "secrets": {
    "api_key": {
      "hash": "sha256:a1b2c3d4e5f6g7h8...",
      "created_at": "2026-02-16T12:00:00.000000+00:00",
      "updated_at": "2026-02-16T12:00:00.000000+00:00",
      "last_rotated": "2026-02-16T12:00:00.000000+00:00",
      "rotation_count": 0,
      "targets": {
        ".env": {
          "hash": "sha256:...",
          "updated_at": "2026-02-16T12:00:00.000000+00:00"
        }
      }
    }
  },
  "metadata": {
    "last_sync": "2026-02-16T12:00:00.000000+00:00"
  }
}

Security¶

The lockfile stores one-way SHA-256 hashes, not actual secret values:

Safe to commit to version control
Enables change detection without exposing secrets
Supports compliance audits

Lockfile Safety

The lockfile contains only hashes and timestamps. It's safe to commit to Git for tracking purposes.

Rotation¶

Secret rotation is the process of generating new values for existing secrets.

Rotation Policies¶

secrets:
  api_key:
    rotation:
      period: 90d  # Rotate every 90 days

Supported Periods:

7d - Weekly
30d - Monthly
90d - Quarterly (SOC2 compliant)
180d - Semi-annually
365d or 1y - Annually

Rotation Workflow¶

graph TB
    A[Check Rotation Status] --> B{Due for Rotation?}
    B -->|Yes| C[Generate New Value]
    B -->|No| D[Skip]
    C --> E[Update Targets]
    E --> F[Update Lockfile]
    F --> G[Increment Rotation Count]

Commands¶

# Check rotation status
secretzero rotate --dry-run

# Rotate due secrets
secretzero rotate

# Force rotate specific secret
secretzero rotate --force api_key

One-Time Secrets¶

Secrets with one_time: true are never automatically rotated:

secrets:
  master_key:
    one_time: true
    rotation:
      period: 90d  # Warns but doesn't rotate

Policies¶

Policies enforce security and compliance requirements.

Policy Types¶

graph LR
    A[Policies] --> B[Rotation]
    A --> C[Compliance]
    A --> D[Access Control]

Rotation Policy¶

Enforce rotation requirements:

policies:
  require_rotation:
    type: rotation
    config:
      require_rotation_period: true
      max_age: 90d
      severity: error

Compliance Policy¶

Built-in compliance frameworks:

policies:
  soc2_compliance:
    type: compliance
    config:
      standard: soc2  # soc2, iso27001
      severity: error

Requirements:

SOC2: All secrets must have rotation periods ≤ 90 days
ISO27001: All secrets must have documented rotation periods

Access Control Policy¶

Restrict allowed/denied targets:

policies:
  cloud_only:
    type: access
    config:
      allowed_targets:
        - aws-secretsmanager
        - aws-ssm-parameter
      denied_targets:
        - local-file
      severity: warning

Drift Detection¶

Drift detection identifies when secrets have been modified outside SecretZero.

Drift Types¶

graph TB
    A[Drift Detection] --> B[Missing Secrets]
    A --> C[Modified Values]
    A --> D[Missing Targets]
    A --> E[Corrupted Lockfile]

Detection Process¶

Compare lockfile hashes with current values
Check if target files exist
Verify secret configuration matches
Report discrepancies

Commands¶

# Check for drift
secretzero drift

# Check specific secret
secretzero drift api_key

Remediation¶

# Resync all secrets
secretzero sync --force

# Resync specific secret
secretzero sync --force api_key

Architecture¶

Data Flow¶

graph TB
    A[Secretfile.yml] --> B[ConfigLoader]
    B --> C[Validation]
    C --> D[Variable Interpolation]
    D --> E[Provider Initialization]
    E --> F[Secret Generation]
    F --> G{Environment Override?}
    G -->|Yes| H[Use ENV Value]
    G -->|No| I[Use Generator]
    H --> J[Target Storage]
    I --> J
    J --> K[Lockfile Update]
    K --> L[Success]

Component Layers¶

graph TB
    A[CLI Layer] --> B[Engine Layer]
    B --> C[Provider Layer]
    B --> D[Generator Layer]
    C --> E[Target Layer]
    D --> E
    E --> F[Storage Layer]

    G[API Layer] --> B

Layers:

CLI/API Layer: User interface (commands, endpoints)
Engine Layer: Business logic (sync, rotation, policy)
Provider Layer: Authentication and connectivity
Generator Layer: Secret value generation
Target Layer: Secret storage abstraction
Storage Layer: Actual storage backends

Security Model¶

Principles¶

Defense in Depth: Multiple layers of security
Least Privilege: Minimal required permissions
Encryption at Rest: Cloud providers handle encryption
Encryption in Transit: HTTPS for all API calls
No Secret Storage: Lockfile contains only hashes
Audit Trail: All operations logged

Secret Lifecycle¶

graph LR
    A[Generation] --> B[Encryption]
    B --> C[Transmission]
    C --> D[Storage]
    D --> E[Retrieval]
    E --> F[Usage]
    F --> G[Rotation]
    G --> A

Access Control¶

Provider Authentication:

AWS: IAM roles/policies
Azure: Managed Identity/RBAC
Vault: Token/AppRole
Kubernetes: ServiceAccount/RBAC

API Authentication:

API key authentication
Timing-safe comparison
Audit logging

Extensibility Points¶

SecretZero is designed to be extensible:

Custom Generators¶

from secretzero.generators.base import BaseGenerator

class CustomGenerator(BaseGenerator):
    def generate(self, config: dict) -> str:
        # Your custom logic
        return "generated-value"

Custom Targets¶

from secretzero.targets.base import BaseTarget

class CustomTarget(BaseTarget):
    def store(self, secret_name: str, value: str) -> None:
        # Your custom storage logic
        pass

Custom Providers¶

from secretzero.providers.base import BaseProvider

class CustomProvider(BaseProvider):
    def test_connection(self) -> bool:
        # Your custom connectivity test
        return True

See the Extending SecretZero guide for details.

Best Practices¶

1. Use Variables for Flexibility¶

variables:
  environment: "{{env.ENVIRONMENT or 'development'}}"
  region: "{{env.AWS_REGION or 'us-east-1'}}"

2. Separate Lockfiles per Environment¶

secretzero sync --lockfile .gitsecrets-prod.lock
secretzero sync --lockfile .gitsecrets-staging.lock

3. Multiple Targets for Redundancy¶

targets:
  - type: aws-secretsmanager
  - type: local-file  # Backup

4. Use Templates for Reusability¶

Define common patterns once, use many times.

5. Enable Policies Early¶

Catch issues before they reach production:

policies:
  require_rotation:
    type: rotation
    severity: error

6. Always Dry-Run First¶

secretzero sync --dry-run
secretzero rotate --dry-run

Next Steps¶

Now that you understand the core concepts:

Build Your First Project → - Hands-on tutorial
Explore Examples → - Real-world configurations
User Guide → - Detailed documentation
Architecture Deep Dive → - Technical details

Core Concepts¶

Overview¶

Secretfile Structure¶

Basic Structure¶

Component Breakdown¶

Version¶

Metadata¶

Variables¶

Providers¶

Provider Types¶

Provider Configuration¶

Authentication Methods¶

Secrets¶

Secret Definition¶

Secret Types¶

Simple Secret¶

Complex Secret (Template)¶

Generators¶

Generator Types¶

Random Password¶

Random String¶

Static¶

Script¶

Targets¶

Target Types¶

Local File Target¶

Cloud Targets¶

AWS Secrets Manager¶

AWS SSM Parameter Store¶

Azure Key Vault¶

HashiCorp Vault¶

CI/CD Targets¶

GitHub Actions¶

GitLab CI/CD¶

Jenkins¶

Kubernetes Targets¶

Templates¶

Template Definition¶

Using Templates¶

Lockfile¶

Purpose¶

Structure¶

Security¶

Rotation¶

Rotation Policies¶

Rotation Workflow¶

Commands¶

One-Time Secrets¶

Policies¶

Policy Types¶

Rotation Policy¶

Compliance Policy¶

Access Control Policy¶

Drift Detection¶

Drift Types¶

Detection Process¶

Commands¶

Remediation¶

Architecture¶

Data Flow¶

Component Layers¶

Security Model¶

Principles¶

Secret Lifecycle¶

Access Control¶

Extensibility Points¶

Custom Generators¶

Custom Targets¶

Custom Providers¶

Best Practices¶

1. Use Variables for Flexibility¶

2. Separate Lockfiles per Environment¶

3. Multiple Targets for Redundancy¶

4. Use Templates for Reusability¶

5. Enable Policies Early¶

6. Always Dry-Run First¶

Next Steps¶

Additional Resources¶