{"id":45520644,"url":"https://github.com/zloeber/secretzero","last_synced_at":"2026-06-17T14:00:35.958Z","repository":{"id":340013575,"uuid":"1157411861","full_name":"zloeber/SecretZero","owner":"zloeber","description":"Git native secrets-as-code","archived":false,"fork":false,"pushed_at":"2026-06-16T18:09:53.000Z","size":6781,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T18:26:47.677Z","etag":null,"topics":["automation","secrets","secrets-as-code","secrets-management"],"latest_commit_sha":null,"homepage":"https://secret0.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zloeber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/cli-docs-integration.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["zloeber"]}},"created_at":"2026-02-13T19:39:04.000Z","updated_at":"2026-06-16T18:10:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zloeber/SecretZero","commit_stats":null,"previous_names":["zloeber/secretzero"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/zloeber/SecretZero","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2FSecretZero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2FSecretZero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2FSecretZero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2FSecretZero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zloeber","download_url":"https://codeload.github.com/zloeber/SecretZero/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloeber%2FSecretZero/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34451342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","secrets","secrets-as-code","secrets-management"],"created_at":"2026-02-22T22:26:45.977Z","updated_at":"2026-06-17T14:00:35.952Z","avatar_url":"https://github.com/zloeber.png","language":"Python","funding_links":["https://github.com/sponsors/zloeber"],"categories":[],"sub_categories":[],"readme":"# SecretZero™\n\u003c!-- agent-entrypoint:\nintent: executable-tool\nprimary_workflow: usage-first\ninstall: uv tool install -U \"secretzero[all]\"\n\nbootstrap:\n  - export SZ_AGENT_MODE=true\n  - secretzero agent list --format json\n  - secretzero agent adopt --dry-run --format json\n\nauthoritative:\n  - ./AGENTS.md\n\nusage:\n  - ./README.md#agent-quick-start\n  - ./skills/secretzero-agent-adopt/SKILL.md\n\nagent_targets:\n  discover: secretzero agent list --format json\n  adopt: secretzero agent adopt --format json\n  adopt_gitops: secretzero agent adopt --output-dir ./agents/hermes --template --format json\n  sync: secretzero agent sync --json\n  skills:\n    - skills/secretzero-agent-adopt/SKILL.md\n    - skills/secretzero-agent/SKILL.md\n    - skills/secretzero-handle/SKILL.md\n--\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://secret0.com/\"\u003e\n\u003cimg src=\"docs/inc/secret0_angel_small.png\" width=\"520\" alt=\"Secret0 logo\"\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/zloeber/SecretZero/releases/latest\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/v/release/zloeber/SecretZero?color=blue\u0026label=Latest%20Release\" alt=\"Latest Release\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/zloeber/SecretZero/blob/main/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-Apache--2.0-ffffff?labelColor=d4eaf7\u0026color=2e6cc4\" alt=\"License: Apache 2.0\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://deepwiki.com/zloeber/SecretZero\"\u003e\n        \u003cimg alt=\"Ask DeepWiki\" src=\"https://deepwiki.com/badge.svg\"\u003e\n    \u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/status-stable-green.svg\" alt=\"Status: Stable\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.12+-blue.svg\" alt=\"Python 3.12+\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Entra-Agent%20ID%20Preview-5B2C87.svg\" alt=\"Entra Agent ID Preview\"\u003e\n    \u003cimg src=\"https://github.com/zloeber/SecretZero/actions/workflows/test.yaml/badge.svg\" alt=\"Tests\"\u003e\n    \u003cimg src=\"https://github.com/zloeber/SecretZero/actions/workflows/docker.yaml/badge.svg\" alt=\"Build\"\u003e\n\u003c/p\u003e\n\nSecretZero 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.\n\n## Agent Quick Start\n\nIf you are an agent reading this repository remotely through `gh`, `curl`, or a GitHub/MCP client,\nstart here.\n\n**Agent runtime integration (Hermes / OpenClaw):**\n\n```bash\nexport SZ_AGENT_MODE=true\nsecretzero agent list --format json\nsecretzero agent adopt --dry-run --format json\nsecretzero agent adopt --preseed-lockfile --format json\nsecretzero agent sync --json -f ~/.hermes/Secretfile.yml\n```\n\nSee `skills/secretzero-agent-adopt/SKILL.md` for the full adopt/restore loop. `secretzero agent backup`\nis an alias of `agent adopt` (not `secretzero backup create`).\n\nSkill files:\n\n- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md`\n- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md`\n- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md`\n- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md`\n\nDownload all skill folders into a target directory:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zloeber/SecretZero/main/scripts/download-secretzero-skills.zsh \\\n  | bash -s -- ./skills\n```\n\nUse that downloader like this:\n\n- **OpenClaw:** download to `./skills` for the current workspace or `~/.agents/skills` for a\n  shared install.\n- **Hermes:** either install the raw `SKILL.md` URLs with `hermes skills install ...`, or\n  download to `~/.agents/skills` (or another shared directory) and add that directory to\n  `~/.hermes/config.yaml` under `skills.external_dirs`.\n\nDirect Hermes install:\n\n```bash\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md\n```\n\n## The Problem\n\nIf you have ever asked any of these questions about a new or existing codebase then SecretZero is for you!\n\n- Where are all the secrets in my project?\n- How do I generate new secrets, api keys, or certificates to deploy a whole new environment or application deployment?\n- When were my critical project secrets last rotated?\n- If I needed to bootstrap this entire project from scratch would I be able to do so without manually handling any secrets?\n- How do I document my project's secrets surface area and requirements?\n\n## Features\n\n### Core Capabilities\n- **Idempotent bootstrap** of initial secrets for one or more environments\n- **Lockfile tracking** for secrets with rotation history and timestamps\n- **Dual-purpose providers** that can both request/rotate new secrets and store them across a variety of environments\n- **Type safety and validation** at every layer with strongly-typed Pydantic models\n- **Variable interpolation and stacking** for targeting multiple environments independently\n- **Manual secret fallbacks** via environment variables when automatic generation isn't possible\n- **Self-documenting** secrets-as-code showing when secrets were created, from where, and where they are now\n\n### Advanced Features\n- **Secret Rotation Policies** - Automated rotation based on configurable time periods (90d, 2w, etc.)\n- **Policy Enforcement** - Validate secrets against rotation, compliance, and access control policies\n- **Compliance Support** - Built-in SOC2 and ISO27001 compliance policies\n- **Drift Detection** - Detect when secrets have been modified outside of SecretZero's control\n- **Rotation Tracking** - Track rotation history, count, and last rotation timestamp in lockfile\n- **One-time Secrets** - Support for secrets that should only be generated once\n- **Entra Agent ID Blueprint Orchestration** - Declaratively manage Entra agent identity blueprints and credential posture via Microsoft Graph\n- **API** - Run as an API server if you need to for some reason I cannot fathom\n\n`secretzero get` safety controls:\n- `SZ_SANDBOX=true` blocks retrieval by default\n- `SZ_ALLOW_GET_IN_SANDBOX=true` explicitly overrides the block\n- `--reveal` is required to print plaintext values\n- `SZ_AGENT_MODE=true` (or `SZ_AGENT=true`) blocks `--reveal` and other commands that would dump secret-bearing config to stdout; use `secretzero ingest preseed` for `.env` lockfile hashing\n\n## How It Works\n\nAt 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.\n\nFor end-to-end workflow diagrams and graph screenshots, see:\n\n- [Workflow visuals](docs/getting-started/workflows.md)\n- [Agent-guided secret sync](docs/user-guide/agent-sync.md)\n- [Sync command reference](docs/user-guide/cli/sync.md)\n\n\n## Use Cases\n\n- GitOps-first infrastructure with git-friendly lockfiles for multi-environment secret provisioning.\n- Multi-cloud secret synchronization across AWS Secrets Manager, Azure Key Vault, and HashiCorp Vault from a single source of truth.\n- Database credential bootstrapping and rotation for PostgreSQL, MySQL, MongoDB, and similar systems.\n- Certificate management for TLS certificates, SSH keypairs, and signing certificates across environments.\n- CI/CD secret provisioning for GitHub Actions, GitLab CI, Jenkins, and related pipelines.\n- Kubernetes secret seeding, including External Secrets Operator manifest generation for target secrets.\n- Development environment setup so new team members can bootstrap local `.env` files without manual credential sharing.\n- Compliance and audit workflows with lockfile history for SOC2 and ISO-style evidence.\n- Secret-zero bootstrap for greenfield deployments and disaster recovery scenarios.\n- API key lifecycle management for third-party services like Stripe, SendGrid, and Twilio.\n- Microservices secret coordination for shared signing keys, encryption keys, and other distributed credentials.\n- Environment parity testing with ephemeral environments that use production-like secrets without exposing real credentials.\n\n\n# Components\n\nThese are the core components of this application.\n\n## Secrets\n\nSecrets 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.\n\n\u003e **NOTE** All secrets have a source and at least 1 or more targets.\n\n## Providers\n\nProviders are similar to terraform providers and are often an authentication point granting API access to secret sources or targets.\n\nSecret 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.\n\n## Installation\n\n### Basic Installation\n\n```bash\nuv tool install -U \"secretzero[all]\"\n```\n\n### With Provider Support\n\n```bash\n# AWS support\nuv tool install \"secretzero[aws]\"\n\n# Azure support\nuv tool install \"secretzero[azure]\"\n\n# Entra Agent ID support\nuv tool install \"secretzero[entra_agent_id]\"\n\n# Vault support\nuv tool install \"secretzero[vault]\"\n\n# Kubernetes support\nuv tool install \"secretzero[kubernetes]\"\n\n# CI/CD support (GitHub, GitLab, Jenkins)\nuv tool install \"secretzero[cicd]\"\n\n# API server support\nuv tool install \"secretzero[api]\"\n\n# Everything (easiest)\nuv tool install \"secretzero[all]\"\n```\n\n### Agent Skills\n\nSecretZero ships four focused skills for agentic workflows:\n\n- [`secretzero-agent-adopt`](./skills/secretzero-agent-adopt/SKILL.md) for Hermes/OpenClaw adopt/list, restore, and GitOps capture\n- [`secretzero-agent`](./skills/secretzero-agent/SKILL.md) for runtime bootstrap, `agent sync`, and secure human-in-the-loop operations\n- [`secretzero-author`](./skills/secretzero-author/SKILL.md) for `Secretfile.yml` authoring, review, and safe discovery workflows\n- [`secretzero-handle`](./skills/secretzero-handle/SKILL.md) for `.env` / file-target workflows, `SZ_AGENT_MODE`, and spill-safe CLI usage\n\nFor the fastest remote install path, see `Agent Quick Start` near the top of this README.\n\nIf you are a human operator, install SecretZero itself and use the skills as operating guides:\n\n```bash\nuv tool install -U \"secretzero[all]\"\nsecretzero --help\nsecretzero agent sync --help\n```\n\nIf you are running Hermes Agent, install the skills directly from this repository:\n\n```bash\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md\nhermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md\nhermes skills list\n```\n\nIf you already have a local checkout, you can also point Hermes at the repo skill directory in `~/.hermes/config.yaml`:\n\n```yaml\nskills:\n  external_dirs:\n    - /absolute/path/to/SecretZero/skills\n```\n\nIf you are running OpenClaw, opening this repository as the agent workspace is enough because OpenClaw auto-loads workspace `/skills`. To make the skills available across all workspaces, copy them into `~/.agents/skills`:\n\n```bash\nmkdir -p ~/.agents/skills\ncp -R skills/secretzero-agent-adopt ~/.agents/skills/\ncp -R skills/secretzero-agent ~/.agents/skills/\ncp -R skills/secretzero-author ~/.agents/skills/\ncp -R skills/secretzero-handle ~/.agents/skills/\n```\n\nOr use the bundled downloader script from a remote agent session:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zloeber/SecretZero/main/scripts/download-secretzero-skills.zsh \\\n  | bash -s -- ~/.agents/skills\n```\n\n## Installation (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/zloeber/SecretZero.git\ncd SecretZero\n\n# Create virtual environment (include pip and other tools)\nuv sync --all-extras\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install in development mode\nuv uv tool install -e \".[dev]\"\n```\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Start a one-time web interface\nsecretzero web\n\n# Start a one-time web interface that targets the dev environment\nsecretzero web -e dev\n\n# List supported secret types\nsecretzero secret-types\n\n# Show detailed configuration for a specific type\nsecretzero secret-types --type password --verbose\n\n# Create a new manifest from template\nsecretzero create --template-type basic\n\n# Validate your manifest\nsecretzero validate\n\n# Test provider connectivity\nsecretzero test\n\n# Generate and sync secrets (dry-run)\nsecretzero sync --dry-run\n```\n\n### API Server\n\n```bash\n# Install API dependencies\nuv tool install secretzero[api]\n\n# Set API key (optional, enables authentication)\nexport SECRETZERO_API_KEY=$(python -c \"import secrets; print(secrets.token_urlsafe(32))\")\n\n# Start server\nsecretzero-api\n\n# Server runs on http://localhost:8000\n# Visit http://localhost:8000/docs for interactive API documentation\n```\n\n### API Usage Examples\n\n```bash\n# Health check\ncurl http://localhost:8000/health\n\n# List secrets (with authentication)\ncurl -H \"X-API-Key: $SECRETZERO_API_KEY\" http://localhost:8000/secrets\n\n# Sync secrets\ncurl -X POST -H \"X-API-Key: $SECRETZERO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  http://localhost:8000/sync \\\n  -d '{\"dry_run\": true, \"force\": false}'\n\n# Check rotation status\ncurl -X POST -H \"X-API-Key: $SECRETZERO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  http://localhost:8000/rotation/check \\\n  -d '{}'\n```\n\nFor more API examples, see [docs/api-getting-started.md](docs/api-getting-started.md).\n\n## Demo\n\nSee local `Secretfile.*.yml` files or other [local examples](./examples/). Here we run some of the commands against the local `Secretfile.yml` manifest:\n\n![Demo of secretzero cli](./docs/inc/demos/demo-all.gif)\n\n\n## Pretty Graphs\n\n### Secret Graph Overview\n\n![Secret graph overview](./docs/inc/sz-graph-1.png)\n\nThis view shows the top-level relationship between generated/resolved secrets and their targets.\n\n### Sync State Across Targets\n\n![Sync state graph](./docs/inc/sz-graph-2.png)\n\nEdges reflect target sync state so you can quickly identify what is already synced versus pending/drifted.\n\n### Destination-Centric View\n\n![Destination-centric graph](./docs/inc/sz-graph-3.png)\n\n## Documentation\n\n- **[Docs](https://docs.secret0.com)**\n- **[Extending SecretZero](./docs/extending.md)** - Guide for adding new secret types and providers\n\n## Security\n\nSecretZero is designed with security as a priority:\n\n- ✅ No plaintext secrets in lock files (only metadata hashes)\n- ✅ Schema-driven validation at every layer\n- ✅ Type-safe implementations with Pydantic\n- ✅ Idempotent operations to prevent accidental overwrites\n- ✅ Audit trail through lock file tracking\n\n# License\n\n[Apache](./LICENSE)\n\n# FAQs\n\n## Relationship to External Secrets Operator\n\nSecretZero is designed to complement, not replace, the External Secrets Operator. \n\nSecretZero manages secret creation, bootstrap, lifecycle, and auditability upstream, while External Secrets handles runtime projection into Kubernetes.\n\n## Relationship to \u003cVault|Infiscal|Others\u003e\n\nA 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloeber%2Fsecretzero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzloeber%2Fsecretzero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloeber%2Fsecretzero/lists"}