Provider Bundles¶

Provider bundles are SecretZero's plugin system. They let you add new providers, generators, and targets without modifying the core codebase — just pip install and go.

How It Works¶

A bundle is a standard Python package that exports a BundleManifest via a pyproject.toml entry point. SecretZero discovers and loads all installed bundles automatically at startup.

sequenceDiagram
    participant User
    participant CLI as SecretZero CLI
    participant BR as BundleRegistry
    participant EP as Python entry_points

    User->>CLI: secretzero sync
    CLI->>BR: get_bundle_registry()
    BR->>BR: Register built-in generators/targets
    BR->>BR: Register built-in bundle manifests
    BR->>EP: entry_points(group="secretzero.providers")
    EP-->>BR: [BundleManifest, ...]
    BR->>BR: Import & register each class
    BR-->>CLI: Registry ready
    CLI->>BR: get_generator_class("mycloud_token")
    BR-->>CLI: MyCloudTokenGenerator

Getting Started¶

Create a bundleInstall itUse it

secretzero scaffold-bundle mycloud --with-target mycloud_secret

cd secretzero_mycloud && pip install -e .

# Secretfile.yml
providers:
  mycloud:
    kind: mycloud
    auth:
      kind: token
      config:
        token: ${MYCLOUD_TOKEN}

secrets:
  api_key:
    generator: random_password
    targets:
      - provider: mycloud
        kind: mycloud_secret
        config:
          path: /secrets/api_key

What's in a Bundle?¶

Every bundle provides a BundleManifest that declares:

Component	What it does	Required?
Provider	Auth + connectivity to an external service	No
Generators	Create secret values (tokens, passwords, certs)	No
Targets	Store secrets in external systems	No

You can ship any combination. A generator-only bundle is perfectly valid.

Guides¶

Creating a Bundle — Full walkthrough from scaffold to publish
Bundle Cookbook — Advanced patterns: multi-target, capabilities, OAuth
Bundle Reference — API-level class documentation

Built-in Bundles¶

SecretZero ships with nine built-in bundles. They're implemented using the same BundleManifest architecture as third-party bundles and serve as reference implementations.

Bundle	Provider	Generators	Targets
AWS	`aws`	—	`ssm_parameter`, `secrets_manager`
Azure	`azure`	—	`key_vault`
Vault	`vault`	—	`vault_kv`
GitHub	`github`	`github_pat`	`github_secret`
GitLab	`gitlab`	—	`gitlab_variable`, `gitlab_group_variable`
Jenkins	`jenkins`	—	`jenkins_credential`
Kubernetes	`kubernetes`	—	`kubernetes_secret`, `external_secret`
Ansible Vault	`ansible_vault`	—	`ansible_vault`
Infisical	`infisical`	—	`infisical_secret`

CLI Commands¶

# Scaffold a new bundle package
secretzero scaffold-bundle mycloud --with-target mycloud_secret

# Validate a bundle before publishing
secretzero validate-bundle ./secretzero_mycloud

# List all registered providers (built-in + third-party)
secretzero providers list

# Inspect a specific provider's config and targets
secretzero providers --provider mycloud