SecretSpec: Deklaratives Secret-Management für deine Entwicklungsumgebung

Dieser Beitrag gibt dir eine kurze Einführung in das Open-Source-Tool SecretSpec und erklärt, warum es eine gute Wahl für dein nächstes Projekt sein könnte. Er richtet sich an Entwickler, die Secrets auf ihren Entwicklungsmaschinen sauberer und sicherer verwalten wollen.

Warum Secret-Management wichtig ist

Secret-Management ist immer ein heißes Thema, besonders im Zeitalter von KI-Agenten, in dem Secrets noch einfacher und schneller geleakt werden können. Umgebungsvariablen-Dateien sind eine schlechte Idee. Sie sind mühsam zu pflegen, und man kann sie leicht leaken, selbst wenn man sie in der .gitignore ausgeschlossen hat. SecretSpec adressiert dies, indem es die committete Deklaration der Secrets von der Wertespeicherung und -bereitstellung trennt. Der Artikel Where env went wrong erklärt die Gründe für diesen Ansatz im Detail.

Das Leitprinzip ist Scoping. Secrets sollten nur dort verfügbar sein, wo sie benötigt werden, und nur für die Anwendungen zugänglich sein, die sie brauchen. Passwörter im Home-Verzeichnis oder in .env-Dateien zu speichern, verletzt dieses Prinzip und ist immer eine schlechte Idee.

Was SecretSpec macht

SecretSpec stellt eine Schnittstelle und ein Schema für deine Entwicklungsumgebung bereit, um zu definieren, welche Secrets in einem Projekt verfügbar sein müssen und wie sie abgerufen werden. Es funktioniert hauptsächlich, indem es den Zielbefehl wrappt, zum Beispiel secretspec run -- myCommand. Die Secrets werden nur diesem Befehl als Umgebungsvariablen bereitgestellt, nicht deiner gesamten Shell.

So bleiben die Secrets außerhalb deines Repositorys. Aber natürlich gibt es auch einen Provider für sops und age, falls du sie im Repository behalten möchtest. Das könnte besonders für GitOps-Tooling wie Flux interessant sein.

Das Tool bietet außerdem lokales Audit-Logging, sodass du erkennen kannst, welche Secrets von wem verwendet wurden. Für noch bessere Integration und Sicherheit gibt es ein SDK für die gängigsten Programmiersprachen.

Wichtige Fakten:

• Es werden mehrere Provider unterstützt, zum Beispiel 1Password, Unix Pass sowie age- und sops-Dateien.
• Damit bekommst du eine einheitliche Schnittstelle für alle deine Secret-Provider.
• Alle Secret-Deklarationen liegen in einer einzigen Datei.
• Eine Auto-Generierungs-Funktion kann lokale Secrets erzeugen und im Secret-Store ablegen.
• SecretSpec erlaubt die Verwendung mehrerer Profile.

Beispiel-Nutzung

Definiere eine secretspec.toml im Projekt-Root:

1[project]
2name = "secretspec-playground"
3revision = "1.0"
4
5[providers]
6op_me = { uri = "onepassword://me" }
7
8[profiles.default]
9TEST_SECRET_OP_EXISTING = { description = "My existing test secret", ref = { item = "myTestSecret", field= "password" }, type = "password", providers = ["op_me"] }
10
11# Liest das Secret aus 1Password aus einem Vault namens "me". Falls das Secret nicht existiert, wird es unter secretspec/{projectName}/{profile}/TEST_SECRET_OP generiert
12TEST_SECRET_OP_GENERATED = { description = "My generated test secret", type = "password", generate = { command = "openssl rand -base64 765" }, providers = ["op_me"] }
13
14# Dieses Secret wird bei jedem Lauf auf jeder Maschine neu generiert
15TEST_SECRET_LOCAL_ONLY = { description = "generate for every developer", type = "base64", generate = { bytes = 32 }, providers = ["null"] }

Jetzt kannst du die Secrets so nutzen:

1secretspec run -- myCommand

Natürlich muss dein 1Password-Tooling korrekt eingerichtet sein, siehe auch Get started with 1Password CLI.

Du kannst dein aktuelles Setup jederzeit mit folgendem Befehl prüfen:

1secretspec check

Auditing

Du kannst alle Operationen auf Secrets mit dem Audit-Log prüfen. Das geht einfach über die Kommandozeile:

1secretspec audit -n 20

Die Ausgabe zeigt, welche Secrets von welchem Prozess und warum abgerufen wurden:

1...
22026-08-20T13:26:51.52277863Z  run    started  bash  TEST_SECRET_LOCAL_ONLY,TEST_SECRET_OP_EXISTING,TEST_SECRET_OP_GENERATED  (secretspec-playground/default)  reason: reason for audit logging
3...

Der Grund wird beim Ausführen des Befehls angegeben:

1secretspec run --reason "Run a simple manual test" -- myCommand

Du kannst die Audit-Logs auch manuell prüfen:

1bat ~/.local/state/secretspec/audit.log | jq

Das ergibt ein strukturiertes Audit-Log wie dieses:

1{
2  "v": 1,
3  "id": "450a4a92-72eb-4597-b296-4288b3d9ca93",
4  "ts": "2026-08-20T12:44:48.899516822Z",
5  "session_id": "b2c6c234-5d07-43af-a192-43ed39c79adf",
6  "seq": 0,
7  "action": "set",
8  "project": "secretspec-playground",
9  "profile": "default",
10  "key": "TEST_SECRET_OP",
11  "provider": "onepassword://me",
12  "outcome": "written",
13  "actor": {
14    "user": "SystemUserName",
15    "is_agent": false
16  },
17  "version": "0.19.1"
18}

Falls nachverfolgbar, kann das Audit-Log sogar prüfen, ob ein Coding-Agent auf deine Secrets zugegriffen hat. Siehe auch Audit Logging, um zum Beispiel den Pfad zu überschreiben.

Zusammenfassung

SecretSpec bietet eine einheitliche Schnittstelle für alle Secrets deines Projekts und bringt dich einen Schritt näher zu besserem Secret-Management. Das Projekt entwickelt sich weiter, und weitere Features und Integrationen werden folgen.