agent-secrets

Encrypted secrets management MCP server for AI agents. Store, retrieve, rotate, audit, auto-rotate, backup, and restore API keys, tokens, and credentials — all encrypted at rest with AES-128 (Fernet).

Why

AI agents need access to API keys, tokens, and credentials. Hardcoding them or passing via env vars is insecure and unmanageable at scale. agent-secrets provides a single encrypted vault with audit trails, access policies, versioning, expiration, rotation scheduling, auto-rotation, strength auditing, and backup/restore — exposed as 43 MCP tools any agent can call.

Features

Core (v0.1.0)

• AES-128 encryption at rest (Fernet: AES-128-CBC + HMAC-SHA256)

• Full audit log: every access tracked

• Access policies: allow/deny patterns, type restrictions

• Secret rotation: rotate with history

• CLI + MCP server: use from terminal or any MCP-compatible agent

v0.2.0 — Lifecycle Management

• Secret versioning: every update/rotation creates a version record. Roll back to any previous version, view history, retrieve old values.

• Auto-expiration (TTL): set expires_at on secrets. Sweep expired secrets in batch, or check expiry status with configurable "expiring soon" thresholds.

• Rotation scheduling: set interval-based rotation policies per secret. Check which secrets are overdue for rotation.

• Auto-rotation execution: run_auto_rotation generates new values and rotates all due secrets with auto_rotate=True in one call — designed for cron/scheduled execution.

• Secret strength auditing: decrypt and analyze entropy of all stored secrets. Flag weak secrets below a configurable entropy threshold.

• Vault backup/restore: export the entire vault (encrypted values stay encrypted) as JSON. Restore in merge or replace mode. Same key required for decryption.

• CSPRNG secret generator: generate strong passwords, API keys, tokens, passphrases, and UUIDs with entropy estimation and strength classification.

v0.3.0 — Zero-Exposure Access

• Read-once secrets: values cryptographically destroyed after first read (ciphertext + all versions overwritten). get_secret refuses read-once secrets; consume_secret is the explicit, intentional path.

• Secret leases: time-boxed, use-limited, revocable access tokens (asl_...) — hand a token to a subprocess instead of the raw secret.

• Vault-side templates: render {{secret.NAME}} placeholders inside the vault; plaintext never enters agent context until render time.

• Secret redaction: scan any outgoing text for known secret values and replace with [REDACTED:name] before sharing.

Quick start

pip install agent-secrets

# CLI — basic operations
agent-secrets store OPENAI_API_KEY sk-... --type api_key --tag prod
agent-secrets get OPENAI_API_KEY --show
agent-secrets list
agent-secrets rotate OPENAI_API_KEY
agent-secrets audit

# v0.2.0 CLI — lifecycle management
agent-secrets generate password --length 32 --store new-db-password
agent-secrets generate api-key --prefix sk --store client-key
agent-secrets generate passphrase --words 5

agent-secrets versioning list OPENAI_API_KEY
agent-secrets versioning rollback OPENAI_API_KEY 2

agent-secrets expiry check --within 48
agent-secrets expiry sweep

agent-secrets rotation set OPENAI_API_KEY 30 --auto
agent-secrets rotation list
agent-secrets rotation due
agent-secrets rotation auto-rotate --kind password

agent-secrets security strength --min-entropy 80
agent-secrets security strength --weak-only

agent-secrets backup export --output vault-backup.json
agent-secrets backup import vault-backup.json --mode merge

# MCP server
agent-secrets serve --db ~/.agent-secrets/vault.db

MCP tools (43)

Core Operations (14)

Secret Versioning (4)

Auto-Expiration / TTL (2)

Rotation Scheduling (4)

Secret Generator (2)

Auto-Rotation, Audit & Backup (4) — NEW in v0.2.0

Zero-Exposure Access (13) — NEW in v0.3.0

v0.3.0 — Zero-Exposure Access

The theme of v0.3.0: secret values should only exist where they are actually needed.

1. Read-once secrets — store enrollment tokens, OTPs, recovery codes that are cryptographically destroyed (ciphertext + all versions overwritten) on first read. The MCP get_secret tool refuses read-once secrets and points the caller at consume_secret, so an agent can never accidentally burn a one-time token by just "checking" it. engine.get_meta() inspects status without consuming.

2. Secret leases — time-boxed (ttl_seconds), use-limited (max_uses), revocable access tokens (asl_...). Hand a lease to a subprocess or another agent instead of the raw value; revoke it any time, or renew it with extend_lease when a task runs long (new expiry = later of now/current expiry + added seconds — renewal never shortens a lease; only active leases are renewable). Every grant/redeem/revoke/renew is audited.

3. Templates — store config skeletons like postgres://admin:{{secret.db-password}}@{{secret.db-host}}:5432/prod and render them vault-side. The plaintext never touches agent context until render time, and render is audited without recording rendered values.

4. Redaction — the safety net. Scan any text for known secret values and replace them with [REDACTED:name] before the text leaves your control (logs, tickets, model prompts). Revoked and consumed secrets are excluded from scanning.

Architecture

┌──────────────────────────────────────────────┐
│  MCP Server (43 tools) / CLI                 │
├──────────────────────────────────────────────┤
│  SecretsEngine (business logic)              │
├──────────────────────────────────────────────┤
│  Vault (encrypted storage — SQLite + Fernet) │
│  Generator (CSPRNG secret generation)        │
└──────────────────────────────────────────────┘

• Encryption: Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256). Master key derived via PBKDF2HMAC (480,000 iterations).

• Storage: SQLite with WAL mode for concurrent reads. Eight tables: secrets, audit_log, policies, secret_versions, rotation_policies, leases, templates (+ lease audit in audit_log).

• Generator: Uses Python's secrets module (CSPRNG) for all generation. Includes curated EFF-style word list for passphrases.

Test coverage

300 tests covering storage, engine, server, versioning, expiry, rotation, auto-rotation, strength auditing, backup/restore, the generator, read-once destruction (including direct-DB recovery attempts), leases, templates, and redaction.

License

MIT