SecretSpec: Declarative Secret-Management for Developers

This post gives you a short introduction to the open source tool SecretSpec and explains why it could be a good choice for your next project. It is aimed at developers who want to manage secrets on their development machines in a cleaner and more secure way.

Why secret management matters

Secret management is always a hot topic, especially in the age of AI agents, where secrets can be leaked even easier and faster. Environment variable files are a bad idea. They are cumbersome to maintain, and you can easily leak them even if you have them excluded in your .gitignore. SecretSpec addresses this by separating the committed declaration of secrets from value storage and delivery. The article Where env went wrong explains the reasons for this approach in detail.

The guiding principle is scoping. Secrets should only be available where they are required and only be accessible by the applications that need them. Storing passwords in your home directory or in .env files violates this principle and is always a bad idea.

What SecretSpec does

SecretSpec provides an interface and schema for your development environment to define which secrets must be available in a project and how to retrieve them. It works mainly by wrapping the target command, for example secretspec run -- myCommand. The secrets are provided as environment variables to that command only, not to your entire shell.

This keeps the secrets out of your repository. But of course there is also a provider for sops and age if you want to keep them inside the repository. This could be especially interesting for GitOps tooling like Flux.

The tool also provides local audit logging to detect which secrets were consumed by whom. For even better integration and security there is an SDK for the most common programming languages.

Key facts:

• Multiple providers are supported, for example 1Password, Unix Pass, and age and sops files. This gives you a unified interface for all your secret providers and a single file for all your secret declarations.
• An auto generation feature can generate local-only secrets and place them into the secret store.
• SecretSpec allows the usage of multiple profiles, for example a dev and a prod profile.

Example usage

SecretSpec is a simple CLI tool. Just follow the installation instructions from the Quick Start.

Define a secretspec.toml in your project root:

The example defines two profiles. In the dev profile the secret is regenerated on every run on every machine and never leaves the local machine, because it uses the null provider. In the prod profile one secret is read from a 1Password vault — and generated if it does not exist yet — while another one references an existing 1Password item. The myApp scope restricts access to only the secrets it lists.

Now you can use the secrets for the dev profile with:

If you want to just share scoped secrets with your application, for example with the prod profile:

Of course your 1Password tooling must be set up correctly for this example to work, see also Get started with 1Password CLI.

You can always check your current setup with the following command:

Auditing

You can check all operations on secrets with the audit log. This can simply be done with the command line:

The reason is provided with:

You can also check the audit logs manually:

That gives you a structured audit log like this:

If traceable, the audit log can even check if a coding agent has accessed your secrets. See also Audit Logging to override, for example, the path.

Summary

SecretSpec provides a unified interface for all your project's secrets and brings you one step closer to better secret management. The project is still evolving, and more features and integrations will come.