ic-builder
e3c8e43ffb
The first architecture set did not render (backslash-n escapes, semicolons in sequence messages, braces in text). All diagrams rewritten to conservative syntax and QA-verified with mermaid-cli (3/3 PARSE-OK). qa-diagrams.sh added; CI enforces it on docs changes. Ticket: https://projects.knownelement.com/issues/832
94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# KNELSecretsManager — Architecture
|
|
|
|
Status: production. Ruling chain: ADR-002 (containerized CLI) -> ADR-003
|
|
(pure-Go `smcli`, Rust `bw` retired). Founder directives: #829/#832.
|
|
|
|
## Components
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
V["Vaultwarden vault - pwvault.turnsys.com"]
|
|
C["smcli container - ukrrs-secretsmgr-cli"]
|
|
S1["TSGCOO entry - data2 TSGCOO bin sm"]
|
|
S2["lane crossover - tools sm"]
|
|
W1["mred-vp - Redmine identity"]
|
|
W2["ci-green.sh - Gitea admin"]
|
|
W3["redmine-sweep.sh"]
|
|
B["KNELBMS on-box secrets.yaml"]
|
|
K["pfv-k8s secrets - glpi-creds, flux PAT"]
|
|
R["nightly timers - pve backup, glpi reconcile"]
|
|
S1 --> C
|
|
S2 --> C
|
|
W1 --> C
|
|
W2 --> C
|
|
W3 --> C
|
|
C -->|HTTPS login sync CRUD| V
|
|
C -.-> B
|
|
C -.-> K
|
|
C -.-> R
|
|
```
|
|
|
|
## Auth + unlock sequence
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as Consumer
|
|
participant S as smcli
|
|
participant V as Vault
|
|
U->>S: login with email password TOTP seed
|
|
S->>V: POST prelogin - get KDF params
|
|
V-->>S: PBKDF2 iterations or Argon2id
|
|
S->>S: derive master key and auth hash
|
|
S->>V: POST identity connect token
|
|
V-->>S: 400 - two factor required
|
|
S->>S: compute TOTP code - RFC 6238
|
|
S->>V: token request plus twoFactorToken
|
|
V-->>S: access token and encrypted keys
|
|
S->>V: GET sync
|
|
V-->>S: profile key - encrypted
|
|
S->>S: stretch master key - decrypt user key
|
|
S->>S: write state file 0600
|
|
```
|
|
|
|
Item payloads are type-2 encStrings (AES-256-CBC + HMAC-SHA256, 32B enc +
|
|
32B mac keys) encrypted/decrypted locally; the vault never sees plaintext.
|
|
|
|
## Consumer pattern
|
|
|
|
```bash
|
|
# env-style consumers (export lines; URI/USERNAME/PASSWORD + original keys)
|
|
eval "$(docker exec -i ukrrs-secretsmgr-cli smcli env creds/<name>)"
|
|
# surgical single-field rotation update
|
|
docker exec -i ukrrs-secretsmgr-cli smcli setfield creds/<name> <KEY> <newvalue>
|
|
```
|
|
|
|
Items are LOGIN type: username + password/API-key as first-class fields,
|
|
service URLs as URIs, remaining keys as named custom fields (hidden where
|
|
secret). Original env key names are preserved as the custom-field names.
|
|
|
|
## Rotation program (#829)
|
|
|
|
All pre-migration material is presumed BURNED (plaintext on disk + LLM
|
|
exposure). Waves, each item = rotate at source -> `setfield` in vault ->
|
|
rewire consumers to `sm env` -> validate (guard rule: never write the vault
|
|
from a failed rotation):
|
|
|
|
1. Tooling tokens (librenms*, wazuh DONE, grafana*, gvm, technitium, phpipam,
|
|
rancher-sectest, beszel, pihole, PMG pair, PBS tokens)
|
|
2. Agent identities (gitea agent-stack, vptechops gitea/redmine)
|
|
3. Platform (cloudron API token, kuma, discourse)
|
|
4. Deep-wired (flux PAT + gitea runner + HA on-box secrets.yaml + k8s
|
|
secrets + PVE upsagent tokens)
|
|
|
|
\* item-specific notes: librenms — token-mint API route absent on this
|
|
install (UI/DB path); grafana — SSO-managed, local admin parked (instance
|
|
password policy blocks CLI reset).
|
|
|
|
## KNELBMS integration
|
|
|
|
See [integration-knelbms.md](integration-knelbms.md). Short form: the BMS
|
|
deploy pipeline (KNELBMS repo, packages/deploy_pipeline.yaml) consumes
|
|
`gitea_auth_header` + `kuma_push_url` + `pve_*_api_token` from on-box
|
|
`/config/secrets.yaml`; the vault is the source of record and rotations
|
|
push to the box through the CR-gated provisioning path.
|