Automated Credential Rotation
Overview
End-to-end, safe rotation of application secrets across the fleet, with
OpenBao as the single source of truth. Every rotation follows the same atomic
flow and never prints a secret value — outputs carry names, versions, and
status only. Default mode is dry-run: produce a plan, review it, then execute.
This skill orchestrates existing tools — it doesn't reinvent them:
- OpenBao (
openbao_read_secret / openbao_write_secret) — store of record.
- Portainer (
port__stack update_stack) — inject rotated env into stacks + restart.
- Keycloak (
keycloak-agent) — OIDC client-secret regeneration.
- GitLab (
gitlab-api) / GitHub (gith__*) — provider PAT/token rotation + CI vars.
- rotate-credentials skill — OS/SSH + BMC passwords (this skill delegates those).
scripts/rotation_lib.py — the deterministic safety layer (generate / redact /
plan / audit), stdlib-only and value-free by construction.
Safety rules (non-negotiable)
- Never echo a value. Route any text that might contain a secret through
rotation_lib.redact (or safe_dumps). Tool results that return values
(e.g. Portainer get_stack_by_name returns env values) must be summarized,
not pasted. Generate secrets with rotation_lib.generate_secret.
- Dry-run first. Build and present the plan; only execute after approval.
- Validate before propagate. Confirm the new value works at the provider
and the OpenBao version incremented before touching any consumer.
- Keep the old until verified. OpenBao KV2 retains the prior version; only
revoke the old credential at the provider after consumers verify.
- Per-consumer atomicity. One consumer failing must not abort the rest;
record partial status.
Inputs
- catalog: a list of secrets to manage (see
references/catalog.example.json).
Each entry: {name, type, provider, bao_path, consumers[], cadence_days, verify}.
- scope: a secret name, a type, or
all. mode: dry-run (default) | execute.
Workflow (per secret — same flow every time)
- Plan —
python scripts/rotation_lib.py plan --catalog catalog.json renders a
value-free, ordered plan (rotate → write → validate → propagate → verify → revoke).
Present it. Stop here in dry-run.
- Rotate at provider (execute mode):
- GitHub PAT: create a new fine-scoped token (
gith__* / GitHub settings), keep the id of the old.
- GitLab PAT:
gitlab-api create personal/project access token; note the old id.
- Keycloak client: regenerate the client secret (
keycloak-agent).
- DB password: generate with
rotation_lib.generate_secret --kind password; ALTER USER.
- Generic API/LLM/OTEL key: rotate in the provider console/API.
- Write to OpenBao —
openbao_write_secret mount_path=secret secret_path=<bao_path> params_json={"data":{"value":"<new>","rotated_at":"<ts>"}}.
Then kv2_get and assert the returned version is greater than before.
- Propagate to consumers (from the catalog):
- Portainer stack env:
port__stack action=update_stack with the new env.
⚠️ This requires re-sending the stack env (which includes other secrets) — do it
via the tool, never paste the values into the conversation; pull current env from
OpenBao, not from chat. (If the stack reads the secret from OpenBao at boot, just
restart the service instead — no value passes through.)
- agent-utilities config: rewrite
vault:// refs via setup-config; restart arbora.
- CI variables:
gitlab-api update CI/CD variable; GitHub Actions secret via API.
- Verify — hit the consumer's auth path (provider whoami, DB connect, MCP
/health).
- Revoke old — delete/expire the previous token at the provider once verified.
- Audit — append a
rotation_lib.audit_record(...) (names/versions/status only) to
the run report. Summarize: rotated N, partial M, failed K.
Policy & scheduling (6-month baseline)
Per-type cadence lives in the catalog (cadence_days, default 182). Drive periodic
runs with the schedule skill / a cron routine, e.g. monthly at an off-peak minute,
filtered to secrets whose age exceeds cadence_days. Always run mode=dry-run on a
schedule and require approval (or a signed window) before execute for high-stakes
secrets (Keycloak, DB, registry).
Integration
- agent-utilities-deployment: after secrets are provisioned (its Step 3
vault://
resolution), this skill is the rotation counterpart — same catalog, same OpenBao paths.
- agent-os-genesis: register this skill as the recurring rotation step after SSO
wiring; genesis provisions the initial secrets, this rotates them on policy.
Verification (of this skill)
python scripts/rotation_lib.py gen --kind password → a strong value (used once).
echo 'GITHUB_TOKEN=your_github_token_here' | python scripts/rotation_lib.py redact
→ the value is ***REDACTED***.
python scripts/rotation_lib.py plan --catalog references/catalog.example.json → a
value-free plan. Confirm no secret material appears anywhere in output.
Related
rotate-credentials — OS/SSH + BMC passwords (delegate those here).
secret-vault-manager — OpenBao unseal/init + one-off KV writes.
keycloak-client-onboarder — initial OIDC client provisioning.
1---2name: automated-credential-rotation-23domain: infrastructure4skill_type: skill5description: >-6 Holistically and safely rotate fleet secrets (GitHub/GitLab PATs, Keycloak7 OIDC client secrets, database passwords, LLM/API keys, OTEL/Langfuse keys,8 registry creds) with OpenBao as the source of truth. Rotates at the provider,9 writes the new value to OpenBao, propagates to consumers (Portainer stack env,10 Keycloak, agent-utilities config), verifies, and revokes the old — never11 echoing a secret value. Dry-run first; supports a 6-month rotation policy. Use12 when asked to rotate credentials/secrets/tokens/keys, set up periodic rotation,13 respond to a leaked credential, or audit secret age. Ties into14 agent-utilities-deployment and agent-os-genesis. Do NOT use for OS/SSH login or15 BMC passwords (use rotate-credentials) or one-off vault writes (use16 secret-vault-manager).17license: MIT18tags: [infra, security, credentials, secrets, rotation, openbao, keycloak, portainer, policy]19metadata:20 source: https://skillmd.com/skills/knuckles-team/automated-credential-rotation-221 version: '1.6.0'22 author: Genius23---2425# Automated Credential Rotation2627## Overview2829End-to-end, **safe** rotation of application secrets across the fleet, with30**OpenBao as the single source of truth**. Every rotation follows the same atomic31flow and **never prints a secret value** — outputs carry names, versions, and32status only. Default mode is **dry-run**: produce a plan, review it, then execute.3334This skill *orchestrates existing tools* — it doesn't reinvent them:35- **OpenBao** (`openbao_read_secret` / `openbao_write_secret`) — store of record.36- **Portainer** (`port__stack` `update_stack`) — inject rotated env into stacks + restart.37- **Keycloak** (`keycloak-agent`) — OIDC client-secret regeneration.38- **GitLab** (`gitlab-api`) / **GitHub** (`gith__*`) — provider PAT/token rotation + CI vars.39- **rotate-credentials** skill — OS/SSH + BMC passwords (this skill delegates those).40- `scripts/rotation_lib.py` — the deterministic safety layer (generate / redact /41 plan / audit), stdlib-only and value-free by construction.4243## Safety rules (non-negotiable)44451. **Never echo a value.** Route any text that might contain a secret through46 `rotation_lib.redact` (or `safe_dumps`). Tool results that return values47 (e.g. Portainer `get_stack_by_name` returns env values) must be summarized,48 not pasted. Generate secrets with `rotation_lib.generate_secret`.492. **Dry-run first.** Build and present the plan; only execute after approval.503. **Validate before propagate.** Confirm the new value works at the provider51 and the OpenBao version incremented before touching any consumer.524. **Keep the old until verified.** OpenBao KV2 retains the prior version; only53 revoke the old credential at the provider after consumers verify.545. **Per-consumer atomicity.** One consumer failing must not abort the rest;55 record partial status.5657## Inputs5859- **catalog**: a list of secrets to manage (see `references/catalog.example.json`).60 Each entry: `{name, type, provider, bao_path, consumers[], cadence_days, verify}`.61- **scope**: a secret name, a type, or `all`. **mode**: `dry-run` (default) | `execute`.6263## Workflow (per secret — same flow every time)64651. **Plan** — `python scripts/rotation_lib.py plan --catalog catalog.json` renders a66 value-free, ordered plan (rotate → write → validate → propagate → verify → revoke).67 Present it. Stop here in dry-run.682. **Rotate at provider** (execute mode):69 - GitHub PAT: create a new fine-scoped token (`gith__*` / GitHub settings), keep the id of the old.70 - GitLab PAT: `gitlab-api` create personal/project access token; note the old id.71 - Keycloak client: regenerate the client secret (`keycloak-agent`).72 - DB password: generate with `rotation_lib.generate_secret --kind password`; `ALTER USER`.73 - Generic API/LLM/OTEL key: rotate in the provider console/API.743. **Write to OpenBao** — `openbao_write_secret mount_path=secret75 secret_path=<bao_path> params_json={"data":{"value":"<new>","rotated_at":"<ts>"}}`.76 Then `kv2_get` and assert the returned version is greater than before.774. **Propagate to consumers** (from the catalog):78 - **Portainer stack env**: `port__stack action=update_stack` with the new env.79 ⚠️ This requires re-sending the stack env (which includes other secrets) — do it80 via the tool, never paste the values into the conversation; pull current env from81 OpenBao, not from chat. (If the stack reads the secret from OpenBao at boot, just82 restart the service instead — no value passes through.)83 - **agent-utilities config**: rewrite `vault://` refs via `setup-config`; restart arbora.84 - **CI variables**: `gitlab-api` update CI/CD variable; GitHub Actions secret via API.855. **Verify** — hit the consumer's auth path (provider whoami, DB connect, MCP `/health`).866. **Revoke old** — delete/expire the previous token at the provider once verified.877. **Audit** — append a `rotation_lib.audit_record(...)` (names/versions/status only) to88 the run report. Summarize: rotated N, partial M, failed K.8990## Policy & scheduling (6-month baseline)9192Per-type cadence lives in the catalog (`cadence_days`, default 182). Drive periodic93runs with the `schedule` skill / a cron routine, e.g. monthly at an off-peak minute,94filtered to secrets whose age exceeds `cadence_days`. Always run `mode=dry-run` on a95schedule and require approval (or a signed window) before `execute` for high-stakes96secrets (Keycloak, DB, registry).9798## Integration99100- **agent-utilities-deployment**: after secrets are provisioned (its Step 3 `vault://`101 resolution), this skill is the rotation counterpart — same catalog, same OpenBao paths.102- **agent-os-genesis**: register this skill as the recurring rotation step after SSO103 wiring; genesis provisions the initial secrets, this rotates them on policy.104105## Verification (of this skill)106107- `python scripts/rotation_lib.py gen --kind password` → a strong value (used once).108- `echo 'GITHUB_TOKEN=your_github_token_here' | python scripts/rotation_lib.py redact` <!-- sanitizer:ignore — placeholder value ("your_..."), not a real PAT; rotation_lib's KV redactor matches on the TOKEN= key, not the ghp_ shape, so this still demonstrates real redaction behavior -->109 → the value is `***REDACTED***`.110- `python scripts/rotation_lib.py plan --catalog references/catalog.example.json` → a111 value-free plan. Confirm no secret material appears anywhere in output.112113## Related114- `rotate-credentials` — OS/SSH + BMC passwords (delegate those here).115- `secret-vault-manager` — OpenBao unseal/init + one-off KV writes.116- `keycloak-client-onboarder` — initial OIDC client provisioning.