# Credential Rotation Enforcer - Overview A Crystal daemon that **tracks** credentials, **enforces** rotation policies as code, and **executes** the four-step rotation contract against AWS Secrets Manager, HashiCorp Vault, GitHub fine-grained PATs, and local `.env` files. Single binary. Live TUI. Bidirectional Telegram bot. Tamper-evident audit log. Signed compliance evidence export. ## What This Project Demonstrates | Concept | What you'll see in the code | |---|---| | Statically-validated policy DSL | `policies/*.cr` evaluated by the Crystal compiler; single-symbol enum args (`enforce :rotate_immediately`) and `match {}` block typos fail `crystal build`. Splat-symbol args (`notify_via :telegram, :slack`) and missing required fields raise `BuilderError` at policy registration time. Either way, a misformed policy never reaches a running daemon. | | Bus + plugin architecture | Typed events fan out across Crystal channels; subscribers (audit, TUI, Telegram, log) react independently; rotators register at compile time via `register_as :kind` macro | | 4-step rotation contract | `generate -> apply -> verify -> commit`, dual-version safe (AWSCURRENT / AWSPENDING analog), with rollback on failure between apply and commit | | Tamper-evident audit log | SHA-256 hash chain + ratcheting HMAC-SHA256 + Ed25519-signed Merkle batches (3 independent layers of integrity) | | AEAD envelope encryption | AES-256-GCM with per-row DEKs wrapped by a KEK; AAD-bound to `tenant_id || credential_id || version_id`; reserved `algorithm_id` byte for crypto agility | | Hand-rolled live TUI | ANSI escapes only (no `crysterm` dependency); event-driven repaints coalesced to a tick interval; works against any IO so it's testable | ## Prerequisites - Crystal **1.20.0+** (see `https://crystal-lang.org/install/`) - For Tier 1 demo: nothing else - For Tier 2 demo: Docker + Docker Compose - For Tier 3 (real cloud): AWS account, Vault server, GitHub Apps token ## Three-Tier Demo Path Each tier teaches a different lesson. Run them in order to see the system evolve. ### Tier 1 - Zero Deps ``` $ git clone && cd credential-rotation-enforcer $ shards install && shards build cre $ ./bin/cre demo ``` What you'll see: - A temp `.env` file with `API_KEY=oldvalue-aaa` - A simulated 60-day-old credential triggering policy violation - Live narration of all 4 rotation steps - The same `.env` file with a fresh random `API_KEY=...` value - Audit chain verification confirming integrity Runtime: under 1 second. ### Tier 2 - Docker Compose ``` $ just demo-full ``` Brings up: PostgreSQL 16, LocalStack (AWS Secrets Manager), HashiCorp Vault dev mode, a fake-GitHub Flask service. CRE connects to all four and rotates one credential through each rotator. Demonstrates real network calls, real auth (SigV4 to LocalStack, token to Vault, bearer to fake-GitHub), real persistence to Postgres, real append-only audit triggers. Setup time: ~2 minutes (mostly image pulls). ### Tier 3 - Real Cloud `cre run` and `cre watch` refuse to start without two 32-byte secrets: ``` export CRE_HMAC_KEY_HEX=$(openssl rand -hex 32) # audit log seed key export CRE_KEK_HEX=$(openssl rand -hex 32) # envelope KEK export CRE_SIGNING_KEY_HEX=$(openssl rand -hex 32) # optional: enables Merkle-batch sealing ``` Then copy `config/demo-full.cr.example`, set the AWS / Vault / GitHub env vars it documents, and run `cre run` headless or `cre watch` for the live TUI. Without `CRE_SIGNING_KEY_HEX`, the daemon still runs but skips Layer 3 of the audit log — `cre audit verify` will skip the Merkle layer too. ## Subcommand Cheat Sheet | Command | Purpose | |---|---| | `cre run` | Headless daemon (production / systemd) — requires `CRE_HMAC_KEY_HEX` + `CRE_KEK_HEX` | | `cre watch` | Engine + live TUI in one process — same env requirements | | `cre check` | One-shot policy eval, exit code by violations (CI-friendly) | | `cre rotate ` | Manual rotation of a single credential — uses the same env-driven rotators as `cre run` | | `cre policy list` | List compiled-in policies | | `cre policy show ` | Inspect one policy in detail | | `cre export --framework=soc2` | Generate signed compliance evidence ZIP | | `cre audit verify` | Hash chain + HMAC ratchet (Merkle layer adds when `--public-key=PATH` or `CRE_AUDIT_PUBLIC_KEY_HEX`) | | `cre verify-bundle ` | Offline re-verify of an evidence bundle (sha256 + manifest sig + chain + Merkle) | | `cre demo` | Tier 1 zero-deps demo | | `cre tui-demo` | 8-second TUI preview using synthetic events (no daemon, no DB) | | `cre version` | Print version | ## Where to Read Next - **Architecture** -> `02-ARCHITECTURE.md` (event bus, persistence, crypto layers) - **Concepts** -> `01-CONCEPTS.md` (rotation theory, NIST/SOC2 framework controls, real breaches) - **Code walkthrough** -> `03-IMPLEMENTATION.md` (key functions, where to make changes) - **Extension ideas** -> `04-CHALLENGES.md` (add a 5th rotator, ML-KEM hybrid wrap, web UI)