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 30 MCP tools any agent can call.

Related MCP server: keyvault

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.

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 (30)

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

Architecture

┌──────────────────────────────────────────────┐
│  MCP Server (30 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. Five tables: secrets, audit_log, policies, secret_versions, rotation_policies.

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

Test coverage

220 tests covering storage, engine, server, versioning, expiry, rotation, auto-rotation, strength auditing, backup/restore, and the generator.

License

MIT