Welcome to SecretZero¶
Secrets Orchestration, Lifecycle, and Bootstrap Engine¶
SecretZero is a secrets management tool that automates the creation, seeding, and lifecycle management of project secrets through a declarative, schema-driven workflow. Think of it as:
- Terraform for secrets lifecycle - Declarative configuration for all your secrets
- Renovate for credentials - Automated rotation and lifecycle management
- npm/yarn for secret dependencies - Dependency graph and lockfile tracking
- A compliance tool - Built-in policies for SOC2, ISO27001, and custom requirements
Production Ready
SecretZero has been battle-tested across multiple phases of development with comprehensive test coverage (200+ tests) and zero security vulnerabilities.
Why SecretZero?¶
The Problem¶
If you've ever asked any of these questions about a codebase, SecretZero is for you:
- Where are all the secrets in my project?
- How do I generate new secrets to deploy a whole new environment?
- How do I handle secret-zero bootstrap?
- When were my critical project secrets last rotated?
- Can I bootstrap this entire project from scratch without manually handling secrets?
- How do I document my project's secrets surface area and requirements?
The Solution¶
SecretZero provides a single source of truth for all secrets in your project through a declarative Secretfile.yml:
version: "1.0"
metadata:
name: my-project
description: Production secrets configuration
secrets:
database_password:
template:
type: password
fields:
- name: value
generator:
type: random-password
length: 32
targets:
- type: aws-secretsmanager
name: /prod/db/password
- type: local-file
path: .env
format: dotenv
Key Features¶
🚀 Core Capabilities¶
- Idempotent Bootstrap - Generate initial secrets for one or more environments
- Lockfile Tracking - SHA-256 hashing with rotation history and timestamps
- Dual-Purpose Providers - Request/rotate secrets and store them across platforms
- Type Safety - Strongly-typed Pydantic models at every layer
- Multiple Profiles - Target multiple environments independently
- Environment Fallbacks - Manual secret override via environment variables
- Self-Documenting - Secrets-as-code showing provenance and distribution
🔄 Secret Rotation¶
- Automated Rotation - Policy-based rotation (90d, 2w, custom periods)
- Rotation Tracking - History, count, and timestamps in lockfile
- One-Time Secrets - Support for secrets that should never rotate
- Compliance Policies - Built-in SOC2 and ISO27001 support
🌐 API Service¶
- REST API - FastAPI-based HTTP API for programmatic management
- OpenAPI Docs - Interactive Swagger UI and ReDoc
- Secure Authentication - API key-based with timing-safe comparison
- Audit Logging - Comprehensive audit trail for all operations
- Remote Management - Manage secrets from CI/CD, scripts, or applications
☁️ Platform Support¶
- AWS - Secrets Manager, SSM Parameter Store, IAM roles
- Azure - Key Vault, Managed Identity
- HashiCorp Vault - KV v2, Token/AppRole auth
- GitHub - Actions secrets (repo, environment, org)
- GitLab - CI/CD variables (project, group)
- Jenkins - Credentials (string, username/password)
- Kubernetes - Secrets (all types), External Secrets Operator
- Native support for TLS, Docker registry, SSH keys
- Files - .env, JSON, YAML, TOML formats
- Merge/append support for existing files
Quick Start¶
Installation¶
# Basic installation
pip install secretzero
# With cloud providers
pip install secretzero[aws,azure,vault]
# With CI/CD support
pip install secretzero[cicd]
# With API server
pip install secretzero[api]
# Everything
pip install secretzero[all]
Initialize a Project¶
# Create a new Secretfile
secretzero create
# Validate configuration
secretzero validate
# Test provider connectivity
secretzero test
Generate and Sync Secrets¶
# Preview what would be generated
secretzero sync --dry-run
# Generate and sync secrets to all targets
secretzero sync
# Show status of a specific secret
secretzero show database_password
Manage Secret Lifecycle¶
# Check which secrets need rotation
secretzero rotate --dry-run
# Rotate secrets based on policies
secretzero rotate
# Check policy compliance
secretzero policy
# Detect drift from expected state
secretzero drift
Start the API Server¶
# Start the REST API server
export SECRETZERO_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
secretzero-api
# Access interactive docs at http://localhost:8000/docs
Use Cases¶
-
Local Development
Generate development secrets locally with .env file support
-
GitHub Actions
Automated secret management for GitHub Actions workflows
-
Kubernetes
Native Kubernetes secret management and External Secrets Operator
-
Multi-Cloud
Synchronize secrets across AWS, Azure, and HashiCorp Vault
-
Compliance
SOC2 and ISO27001 compliance with policy enforcement
-
Migration
Migrate from existing secret management tools
Architecture¶
SecretZero follows a clean, modular architecture:
graph TB
A[Secretfile.yml] --> B[Config Loader]
B --> C[Validation]
C --> D{CLI / API}
D --> E[Providers]
D --> F[Generators]
D --> G[Targets]
E --> H[Secret Sources]
F --> I[Secret Values]
G --> J[Storage Locations]
H --> K[Lockfile]
I --> K
J --> K
K --> L[.gitsecrets.lock]What's Next?¶
-
Get Started
Follow our step-by-step guide to set up your first project
-
User Guide
Learn about configuration, providers, targets, and CLI commands
-
Examples
Explore complete examples for different use cases
-
API Reference
Integrate SecretZero into your applications and workflows
Community¶
- GitHub: zloeber/SecretZero
- Issues: Report bugs or request features
- Discussions: Ask questions and share ideas
License¶
SecretZero is licensed under the Apache License 2.0.