SecretZero is a secrets as code management tool that automates the creation, seeding, and lifecycle management of project secrets through self-documenting declarative manifests. The very first secrets you seed for a new project or environment (known in the industry as 'secret-zero') are often the most difficult to track, maintain, seed, audit, and rotate. SecretZero aims to be an answer to this madness.
If you have ever asked any of these questions about a new or existing codebase then SecretZero is for you!
- Where are all the secrets in my project?
- How do I generate new secrets, api keys, or certificates to deploy a whole new environment?
- How do I handle secret-zero?
- When were my critical project secrets last rotated?
- If I needed to bootstrap this entire project from scratch would I be able to do so without manually handling any secrets?
- How do I document my project's secrets surface area and requirements?
- Idempotent bootstrap of initial secrets for one or more environments
- Lockfile tracking for secrets with rotation history and timestamps
- Dual-purpose providers that can both request/rotate new secrets and store them across a variety of environments
- Type safety and validation at every layer with strongly-typed Pydantic models
- Variable interpolation and stacking for targeting multiple environments independently
- Manual secret fallbacks via environment variables when automatic generation isn't possible
- Self-documenting secrets-as-code showing when secrets were created, from where, and where they are now
- Secret Rotation Policies - Automated rotation based on configurable time periods (90d, 2w, etc.)
- Policy Enforcement - Validate secrets against rotation, compliance, and access control policies
- Compliance Support - Built-in SOC2 and ISO27001 compliance policies
- Drift Detection - Detect when secrets have been modified outside of SecretZero's control
- Rotation Tracking - Track rotation history, count, and last rotation timestamp in lockfile
- One-time Secrets - Support for secrets that should only be generated once
- Entra Agent ID Blueprint Orchestration - Declaratively manage Entra agent identity blueprints and credential posture via Microsoft Graph
- REST API - FastAPI-based HTTP API for programmatic secret management
- OpenAPI Documentation - Interactive API docs with Swagger UI and ReDoc
- API Authentication - Secure API key-based authentication
- Audit Logging - Comprehensive audit trail for all API operations
- Remote Management - Manage secrets from CI/CD pipelines, scripts, or applications
# Initialize and validate
secretzero create # Create new Secretfile from template
secretzero init # Check and install provider dependencies
secretzero validate # Validate Secretfile configuration
secretzero test # Test provider connectivity
# Secret management
secretzero sync # Generate and sync secrets to targets
secretzero sync --dry-run # Preview changes without applying
secretzero sync -s db_password # Sync only specific secret(s)
secretzero show '<secret>' # Show secret metadata
secretzero get --provider aws --secret-id '/prod/api/token' # Provider retrieval (metadata by default)
# Visualization
secretzero graph # Generate visual flow diagram
secretzero graph --type detailed # Show detailed configuration
secretzero graph --type architecture # Show system architecture
secretzero graph --format terminal # Text-based summary
secretzero graph --output diagram.md # Save to file
# Rotation and policies
secretzero rotate # Rotate secrets based on policies
secretzero rotate --dry-run # Preview rotation status
secretzero rotate --force # Force rotation even if not due
secretzero policy # Check policy compliance
secretzero drift # Detect drift in secrets
# Provider management
secretzero providers list # List available providers
secretzero providers capabilities # Show provider capabilities
secretzero providers token-info # Show token permissions (defaults to github)
secretzero providers token-info github --token ghp_xxx # Explicit provider + token
# API Server
secretzero-api # Start REST API serversecretzero get safety controls:
SZ_SANDBOX=trueblocks retrieval by defaultSZ_ALLOW_GET_IN_SANDBOX=trueexplicitly overrides the block--revealis required to print plaintext values
# Health and documentation
GET / # API info
GET /health # Health check
GET /docs # Interactive Swagger UI
GET /redoc # ReDoc documentation
# Secret management
GET /secrets # List all secrets
GET /secrets/{name}/status # Get secret status
POST /sync # Sync/generate secrets
POST /config/validate # Validate configuration
# Rotation and policies
POST /rotation/check # Check rotation status
POST /rotation/execute # Execute rotation
POST /policy/check # Check policy compliance
POST /drift/check # Check for drift
# Audit and monitoring
GET /audit/logs # Get audit logsAt its core SecretZero is a declarative manifest that defines your secret usage in a project and automates requesting + seeding across targets while tracking state in a lockfile.
For end-to-end workflow diagrams and graph screenshots, see:
SecretZero can introspect provider authentication tokens to verify they have the necessary permissions:
# Check GitHub token permissions and scopes
secretzero providers token-info
# Output shows:
# - User information
# - OAuth scopes (repo, workflow, admin:org, etc.)
# - Capabilities (can read repos, write secrets, etc.)
# - Links to documentation on permission requirementsThis is useful for:
- Troubleshooting - Verify token has required scopes before attempting operations
- Security auditing - Document what permissions are granted to tokens
- Compliance - Ensure tokens follow principle of least privilege
- Onboarding - Help new team members create tokens with correct permissions
Currently supported providers: GitHub (more providers coming soon).
Easy to read lockfiles are 100% git friendly. Perfect for teams deploying infrastructure via GitOps where secrets need automated provisioning across multiple environments without manual intervention.
Sync secrets across AWS Secrets Manager, Azure Key Vault, and HashiCorp Vault simultaneously from a single source of truth.
Generate and rotate database credentials (PostgreSQL, MySQL, MongoDB) during initial deployment or scheduled rotation cycles.
Automate creation and distribution of TLS certificates, SSH keypairs, and signing certificates across development, staging, and production environments.
Bootstrap CI/CD pipeline secrets (GitHub Actions, GitLab CI, Jenkins) from centralized configuration without storing credentials in version control.
Generate and deploy secrets to multiple Kubernetes clusters/namespaces during cluster initialization or application deployment.
- Generate externals secrets operator manifests for target secrets.
New team members can bootstrap their local .env files with production-like secrets in seconds without manual credential sharing.
Maintain an auditable lockfile showing when secrets were created, last rotated, and where they're deployed for SOC2/ISO compliance.
Solve the "where do the first secrets come from" challenge when deploying greenfield infrastructure or disaster recovery scenarios.
Track and rotate third-party API keys (Stripe, SendGrid, Twilio) across multiple services while maintaining synchronization.
Ensure all microservices receive consistent shared secrets (JWT signing keys, encryption keys) across distributed deployments.
Quickly spin up ephemeral test environments with production-like secrets for integration testing without exposing real credentials.
These are the core components of this application.
Secrets are usually just a text or dict type. In our case we use a schema of allowed values so that we can easily map out a secret type when requesting it from the provider (kinda need to know what you are asking for right?). This is really a contract used for expected data from a provider and then expressed in targets.
NOTE All secrets have a source and at least 1 or more targets.
Providers are similar to terraform providers and are often an authentication point granting API access to secret sources or targets.
Secret sources are provider bound. If authentication fails, the user is (optionally) prompted for secrets manually as a failover. This is often necessary if there is a manual request somewhere in your bootstrap process.
uv tool install -U "secretzero[all]"# AWS support
uv tool install "secretzero[aws]"
# Azure support
uv tool install "secretzero[azure]"
# Entra Agent ID support
uv tool install "secretzero[entra_agent_id]"
# Vault support
uv tool install "secretzero[vault]"
# Kubernetes support
uv tool install "secretzero[kubernetes]"
# CI/CD support (GitHub, GitLab, Jenkins)
uv tool install "secretzero[cicd]"
# API server support
uv tool install "secretzero[api]"
# Everything (easiest)
uv tool install "secretzero[all]"# Clone the repository
git clone https://github.com/zloeber/SecretZero.git
cd SecretZero
# Create virtual environment (include pip and other tools)
uv sync --all-extras
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in development mode
uv uv tool install -e ".[dev]"# Start a one-time web interface
secretzero web
# Start a one-time web interface that targets the dev environment
secretzero web -e dev
# List supported secret types
secretzero secret-types
# Show detailed configuration for a specific type
secretzero secret-types --type password --verbose
# Create a new manifest from template
secretzero create --template-type basic
# Validate your manifest
secretzero validate
# Test provider connectivity
secretzero test
# Generate and sync secrets (dry-run)
secretzero sync --dry-run# Install API dependencies
uv tool install secretzero[api]
# Set API key (optional, enables authentication)
export SECRETZERO_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
# Start server
secretzero-api
# Server runs on http://localhost:8000
# Visit http://localhost:8000/docs for interactive API documentation# Health check
curl http://localhost:8000/health
# List secrets (with authentication)
curl -H "X-API-Key: $SECRETZERO_API_KEY" http://localhost:8000/secrets
# Sync secrets
curl -X POST -H "X-API-Key: $SECRETZERO_API_KEY" \
-H "Content-Type: application/json" \
http://localhost:8000/sync \
-d '{"dry_run": true, "force": false}'
# Check rotation status
curl -X POST -H "X-API-Key: $SECRETZERO_API_KEY" \
-H "Content-Type: application/json" \
http://localhost:8000/rotation/check \
-d '{}'For more API examples, see docs/api-getting-started.md.
See local Secretfile.*.yml files or other local examples. Here we run some of the commands against the local Secretfile.yml manifest:
This view shows the top-level relationship between generated/resolved secrets and their targets.
Edges reflect target sync state so you can quickly identify what is already synced versus pending/drifted.
- Docs
- Extending SecretZero - Guide for adding new secret types and providers
SecretZero is designed with security as a priority:
- ✅ No plaintext secrets in lock files (only metadata hashes)
- ✅ Schema-driven validation at every layer
- ✅ Type-safe implementations with Pydantic
- ✅ Idempotent operations to prevent accidental overwrites
- ✅ Audit trail through lock file tracking
SecretZero is designed to complement, not replace, the External Secrets Operator.
SecretZero manages secret creation, bootstrap, lifecycle, and auditability upstream, while External Secrets handles runtime projection into Kubernetes.
A secrets management solution like Infisical is a strong control plane for secret storage and policy. SecretZero compliments this and other secrets solutions by adding deterministic orchestration and cross-provider lifecycle modeling. SecretZero maps out the secrets from inception to usage and beyond regardless of the backend secrets platforms in place.