```regex ██████╗██████╗ ███████╗ ██╔════╝██╔══██╗██╔════╝ ██║ ██████╔╝█████╗ ██║ ██╔══██╗██╔══╝ ╚██████╗██║ ██║███████╗ ╚═════╝╚═╝ ╚═╝╚══════╝ ``` [](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/intermediate/credential-rotation-enforcer) [](https://crystal-lang.org) [](https://www.gnu.org/licenses/agpl-3.0) [](https://www.postgresql.org) > Credential rotation enforcer written in Crystal. Tracks credentials, evaluates compile-time-checked policies, 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. *This is a quick overview — security theory, architecture, and full walkthroughs are in the [learn modules](#learn). Operator setup lives in [CONFIGURATION.md](CONFIGURATION.md).* ## What It Does - Compile-time-checked policy DSL (typo'd action symbols, missing fields, bad credential property references all fail `crystal build`) - 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 - Four-step rotation contract (`generate → apply → verify → commit`) borrowed from AWS Secrets Manager's rotation Lambda template, dual-version safe under concurrent reads - Three-layer tamper-evident audit log: SHA-256 hash chain + ratcheting HMAC-SHA256 + Ed25519-signed Merkle batches - AEAD envelope encryption (AES-256-GCM, per-row DEKs wrapped by KEK, AAD-bound to credential identity, reserved `algorithm_id` byte for crypto agility) - Hand-rolled live TUI (no external TUI framework — stdlib ANSI escapes only) with event-driven repaints coalesced to a tick interval - Bidirectional Telegram bot — viewer tier (`/status`, `/queue`, `/history`, `/alerts`) + operator tier (`/rotate`) - Compliance evidence export bundle (signed ZIP with audit log, Merkle batches, control mapping for SOC 2 / PCI-DSS / ISO 27001 / HIPAA) ## Quick Start ```bash git clone https://github.com/CarterPerez-dev/Cybersecurity-Projects.git cd Cybersecurity-Projects/PROJECTS/intermediate/credential-rotation-enforcer shards install && shards build cre --release ./bin/cre demo ``` Or use the install script: ```bash curl -fsSL https://raw.githubusercontent.com/CarterPerez-dev/Cybersecurity-Projects/main/PROJECTS/intermediate/credential-rotation-enforcer/scripts/install.sh | bash ``` > [!TIP] > This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see all available recipes. > > Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin` ### Demo tiers ```bash just demo # Tier 1 — zero-deps SQLite + .env rotator (under 30s) just tui-demo # Live TUI preview with synthetic events (8s, no setup) just demo-full # Tier 2 — Docker Compose: PG + LocalStack + Vault + fake-GH just demo-full-down # tear down the stack ``` ### Daemon usage `cre run` and `cre watch` require two 32-byte secrets — the seed key for the audit-log HMAC ratchet and the KEK that wraps per-row data keys. Generate fresh values once and store them somewhere durable (KMS, password manager, sealed env file): ```bash export CRE_HMAC_KEY_HEX=$(openssl rand -hex 32) export CRE_KEK_HEX=$(openssl rand -hex 32) export CRE_SIGNING_KEY_HEX=$(openssl rand -hex 32) # optional: enables Merkle-batch sealing ``` Then: ```bash cre run --db=sqlite:cre.db # headless daemon cre watch --db=sqlite:cre.db # daemon + live TUI cre check --db=sqlite:cre.db --output=json # one-shot CI gate (no key required) cre rotate # manual rotation (uses same env-driven rotators as run) cre policy list # inspect compiled policies cre audit verify # hash chain + HMAC ratchet (+ Merkle if --public-key given) cre export --framework=soc2 --out=evidence.zip # signed compliance bundle cre verify-bundle evidence.zip # offline re-verify a bundle ``` `cre check` exits 1 when any credential violates its policy — drop into any CI pipeline. ## Flagship Rotators | Rotator | What it talks to | Auth | |---|---|---| | AWS Secrets Manager | `secretsmanager..amazonaws.com` | SigV4 (rolled from scratch in `src/cre/aws/signer.cr`) | | HashiCorp Vault | `vault read database/creds/` + lease revoke | `X-Vault-Token` | | GitHub fine-grained PATs | `POST/DELETE /user/personal-access-tokens` | `Bearer ghp_...` | | Local `.env` file | atomic temp+rename | n/a | Adding a fifth rotator means dropping a single file in `src/cre/rotators/` — the `register_as :kind` macro hooks it into the registry at compile time. Zero changes to the orchestrator, scheduler, or any subscriber. ## Architecture ``` ┌──────────────────────────────────────┐ │ cre (single Crystal binary) │ │ │ ┌────────────┐ │ ┌──────────────────────────────┐ │ │ Scheduler │─────►│ │ Typed Event Bus │ │ │ (fiber) │ │ └──┬─────┬─────┬─────┬─────┬───┘ │ └────────────┘ │ │ │ │ │ │ │ │ ┌──▼──┐ ┌▼────┐ ┌▼──┐ ┌▼──┐ ┌▼───┐ │ │ │Rot. │ │Audit│ │TUI│ │Tg │ │Pol.│ │ │ │Wrkr │ │Sub │ │Sub│ │Bot│ │Eval│ │ │ └──┬──┘ └──┬──┘ └───┘ └───┘ └────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────────┐ │ │ │ Persistence (PG / SQLite) │ │ │ │ + 3-layer audit integrity │ │ │ └──────────────────────────────┘ │ └──────────────────────────────────────┘ ``` All long-lived components are fibers in one OS process. The bus is in-process (Crystal channels are nanosecond-scale) so the architectural overhead is essentially free. Per-subscriber overflow policy: `Block` for audit (compliance — never drop), `Drop` for TUI / metrics / Telegram (best-effort). ## The Three-Layer Audit Log ``` Layer 3 ─ Ed25519-signed Merkle batches → auditor verifies with public key only Layer 2 ─ HMAC ratchet (key zeroized per rotation) → past entries unforgeable Layer 1 ─ SHA-256 hash chain → any single-row tampering breaks forward chain ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Postgres ─ append-only via TRIGGER + role grants (INSERT-only) ``` `cre audit verify` walks all three layers and reports which (if any) is broken. ## Stack **Language:** Crystal 1.20+ **Dependencies:** crystal-db (DB abstraction), crystal-pg (PostgreSQL), crystal-sqlite3 (SQLite), tourmaline (Telegram framework, used minimally), webmock.cr (test HTTP mocks) **Direct LibCrypto FFI** for AES-256-GCM AEAD (Crystal stdlib `OpenSSL::Cipher` lacks GCM auth_data/auth_tag) and Ed25519 signing (stdlib lacks high-level wrapper). Bindings live in `src/cre/crypto/aead.cr` and `src/cre/audit/signing.cr`. **Testing:** stdlib `Spec` runner, 179+ unit tests + integration tests against real PostgreSQL via Docker. ## Configuration Setup is fully env-var driven — no config file required. See **[CONFIGURATION.md](CONFIGURATION.md)** for the operator guide: - Required env vars (`CRE_KEK_HEX`, `CRE_HMAC_KEY_HEX`, `DATABASE_URL`) - Per-rotator setup (AWS IAM policy, Vault token policy, GitHub admin PAT) - Telegram bot creation + chat-ID discovery - systemd service unit with hardening directives - Production security checklist ## Learn This project includes step-by-step learning materials covering security theory, architecture, and implementation. | Module | Topic | |--------|-------| | [00 - Overview](learn/00-OVERVIEW.md) | Prerequisites, quick start, three-tier demo path | | [01 - Concepts](learn/01-CONCEPTS.md) | Rotation theory, real breaches, NIST/SOC2/PCI/ISO/HIPAA framework controls | | [02 - Architecture](learn/02-ARCHITECTURE.md) | Bus + plugin design, persistence layers, three-layer audit integrity, AEAD envelope | | [03 - Implementation](learn/03-IMPLEMENTATION.md) | Code-level walkthrough; where to look in source for each concept | | [04 - Challenges](learn/04-CHALLENGES.md) | 10 ranked extension challenges (PG ALTER USER, Slack, ML-KEM, OpenTimestamps, SPIFFE, JIT broker, etc.) | ## License AGPL 3.0