8.7 KiB

Raw Blame History

Credential Rotation Enforcer (`cre`)

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. Tamper-evident audit log. Bidirectional Telegram bot. Signed compliance evidence export.

What this is

A senior+ portfolio implementation of an enterprise credential rotation enforcer, built end-to-end in Crystal. The code is the lesson - every architectural choice (event bus, plugin macros, AEAD envelope, hash-chained audit log, three demo tiers) is intentional and explained in learn/.

This is not a wrapper around HashiCorp Vault or AWS Secrets Manager. It is its own coherent enforcer that talks to those systems via their HTTP APIs (real SigV4, real bearer auth, real lease tokens).

What it does

Tracks credentials in an inventory (PostgreSQL or SQLite).
Evaluates Crystal-DSL policies that compile-time-check for typos, missing fields, and bad enum values.
Rotates credentials using AWS Secrets Manager's four-step contract (generate -> apply -> verify -> commit) with dual-version safety so concurrent consumers never crash mid-rotation.
Records every event in a tamper-evident audit log: SHA-256 hash chain + ratcheting HMAC-SHA256 + Ed25519-signed Merkle batches.
Encrypts stored credentials at rest with AES-256-GCM AEAD, per-row DEKs wrapped by a KEK, AAD-bound to credential identity.
Notifies via structured logs and a bidirectional Telegram bot supporting /status, /rotate <id>, /snooze, /history, /queue.
Exports signed compliance evidence bundles mapping audit events to SOC 2 / PCI-DSS / ISO 27001 / HIPAA controls.
Renders a hand-rolled live TUI (no crysterm dependency) showing active rotations, recent events, and KEK version, repainted at most every 200ms.

Quick start

Tier 1 - Zero-deps demo (under 30 seconds)

git clone <repo> && cd PROJECTS/intermediate/credential-rotation-enforcer
shards install && shards build cre
./bin/cre demo

You'll see live narration of an in-memory SQLite + tempfile rotation, with audit-chain verification at the end.

Tier 2 - Full mocked stack (under 2 minutes)

just demo-full

Brings up Docker Compose with PostgreSQL 16, LocalStack (AWS Secrets Manager), HashiCorp Vault dev mode, and a fake-GitHub Flask service. CRE talks to all four with real network calls.

Tier 3 - Real cloud

Edit config/demo-full.cr.example and set env vars to point at your real AWS account / Vault server / GitHub Apps token. Then cre run --db=postgres://....

Subcommands

Command	Purpose
`cre run`	Headless daemon (production / systemd)
`cre watch`	Engine + live TUI in same process
`cre check`	One-shot policy evaluation; exit code reflects violations
`cre rotate <id>`	Manually rotate a single credential
`cre policy list / show <name>`	Inspect compiled-in policies
`cre export --framework=soc2`	Generate signed compliance evidence ZIP
`cre audit verify`	Verify hash chain + HMAC ratchet + Merkle batch signatures
`cre demo`	Tier 1 zero-deps demo
`cre version`	Print version

The flagship rotators

Rotator	What it talks to	Auth
AWS Secrets Manager	`secretsmanager.us-east-1.amazonaws.com`	SigV4 (rolled from scratch in `src/cre/aws/signer.cr`)
HashiCorp Vault	`vault read database/creds/<role>` + 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.

Architecture at a glance

                       ┌──────────────────────────────────────┐
                       │       cre  (single Crystal binary)   │
                       │                                      │
   ┌────────────┐      │  ┌──────────────────────────────┐    │
   │ Scheduler  │─────►│  │       Typed Event Bus        │    │
   │ (fiber)    │      │  └──┬─────┬─────┬─────┬─────┬───┘    │
   └────────────┘      │     │     │     │     │     │        │
                       │  ┌──▼──┐ ┌▼────┐ ┌▼──┐ ┌▼──┐ ┌▼───┐  │
                       │  │Rot. │ │Audit│ │TUI│ │Tg │ │Pol.│  │
                       │  │Reg. │ │Log  │ │   │ │Bot│ │Eval│  │
                       │  └──┬──┘ └──┬──┘ └───┘ └───┘ └────┘  │
                       │     └──────┴──────────────┐          │
                       │                           │          │
                       │              ┌────────────▼────────┐ │
                       │              │  Persistence        │ │
                       │              │  (PG / SQLite)      │ │
                       │              └─────────────────────┘ │
                       └──────────────────────────────────────┘

All components are fibers in one OS process. The bus is in-process - Crystal channels are nanosecond-scale.

Project layout

credential-rotation-enforcer/
├── shard.yml          Crystal manifest (1.20+)
├── justfile           build / test / demo / lint recipes
├── policies/          USER policy files (compiled in)
├── src/cre/
│   ├── cli/           subcommand dispatch + 9 commands
│   ├── tui/           ANSI primitives + 4-panel live monitor
│   ├── engine/        scheduler, event bus, lifecycle, orchestrator
│   ├── events/        typed event hierarchy
│   ├── rotators/      registry + 4 flagship rotators
│   ├── policy/        macro DSL + evaluation engine
│   ├── audit/         hash chain + HMAC ratchet + Merkle + Ed25519
│   ├── crypto/        AES-256-GCM envelope, KEK/DEK
│   ├── persistence/   PG + SQLite adapters (same interface)
│   ├── notifiers/     structured log + Telegram bidirectional bot
│   ├── compliance/    SOC2/PCI/ISO/HIPAA control mapping + bundle export
│   ├── aws/           SigV4 signer + Secrets Manager client
│   ├── vault/         dynamic-secrets HTTP client
│   ├── github/        fine-grained PAT API client
│   └── demo/          Tier 1 demo
├── docker/            Tier 2 docker-compose stack (PG + LocalStack + Vault + fake-GH)
├── spec/              200+ unit + integration tests
└── learn/             walkthrough docs (this is the teaching folder)

Read the walkthrough

learn/00-OVERVIEW.md - quick start, prerequisites, three-tier demo path
learn/01-CONCEPTS.md - rotation theory, real breaches that motivated the design, framework controls
learn/02-ARCHITECTURE.md - bus + plugin design, persistence layers, crypto stack
learn/03-IMPLEMENTATION.md - code-level walkthrough; where to look in the source for each concept
learn/04-CHALLENGES.md - 10 extension challenges (beginner -> advanced)

Running the test suite

crystal spec                     # all 200+ tests
crystal spec spec/unit            # unit only (no DB required)
DATABASE_URL=postgres://cre_test:cre_test@localhost:5432/cre_test \
  crystal spec spec/integration   # integration with real PG
just ci                        # format + lint + unit

License

MIT - see LICENSE.

Credits

Built as part of the Cybersecurity Projects portfolio - 60+ enterprise-grade cybersecurity projects designed as senior-level learning resources.

8.7 KiB Raw Blame History

Credential Rotation Enforcer (cre)