Security, Cryptography & GitOps
Starry provides a zero-trust security model: cluster configuration files can be stored safely even in public Git repositories, because all sensitive values are authenticated and encrypted using AES-256-GCM with contextual AAD (Additional Authenticated Data) binding.
1. Contextual AAD Binding: Protection Against Cut-and-Paste Attacks
A known vulnerability with encrypted secrets stored in Git is cut-and-paste manipulation: an attacker or careless operator moving an encrypted ciphertext from one property to another (e.g. copying a root SSH key into an unprivileged environment variable).
In Starry, every value is cryptographically tied to its canonical JSON path:
- The secret for
nodes.bocchi.ssh_keyusesAAD = "nodes.bocchi.ssh_key" - If this ciphertext is pasted into
services.api.db_password, decryption fails immediately withCryptographicExceptionbecause the authentication tag does not match!
2. Secret Formats in Configuration
Open Secrets (PLAIN[...])
When drafting changes, developers can write raw secrets using the PLAIN[...] marker:
nodes:
bocchi:
host: "192.168.1.10"
ssh_key: "PLAIN[-----BEGIN OPENSSH PRIVATE KEY-----...]"Running starry encrypt automatically finds all plain secrets, encrypts them in place, and updates the files:
starry encrypt --key $STARRY_MASTER_KEY ./clusterEncrypted Secrets (ENC[...])
The resulting encrypted secret is formatted as an authenticated envelope:
ENC[AES256_GCM:v1:<base64_nonce>:<base64_cipher>:<base64_tag>]3. Automated Monthly Master Key Rotation via GitHub Actions
To adhere to best security hygiene, master keys should be rotated periodically (e.g. monthly).
Starry accomplishes full fleet re-encryption with a single command:
starry encrypt global --reencrypt \
--old-key-env STARRY_MASTER_KEY_OLD \
--new-key-env STARRY_MASTER_KEY_NEW \
--allow-config-edit \
--git-commit \
--git-push \
--update-github-secret STARRY_MASTER_KEYThis command:
- Discovers all configuration files (
.yaml,.json,.toml). - Decrypts with the old key, checking AAD on every field.
- Encrypts with the new key using a fresh cryptographic nonce per field.
- Atomically rewrites all config files using safe temporary file renames.
- Commits changes to Git and pushes to the remote branch.
- Updates the
STARRY_MASTER_KEYsecret in GitHub Actions usinggh secret set.