Skip to main content

Encrypted Vault Secrets

For sensitive credentials (such as API keys, OAuth client secrets, and database passwords), Rumour provides a secure, local, file-based encrypted keystore called the Rumour Vault.

Secrets stored in the Vault are decrypted in-memory only during request execution and are never written to request files, logs, or reports.

Security Architecture​

The Rumour Vault is designed using modern cryptographic standards:

  • Storage Location: Secrets are saved by default in the user's home directory at ~/.rumour/vault.enc in a TOML format. You can override this location using:
    • RUMOUR_VAULT_PATH environment variable (e.g. export RUMOUR_VAULT_PATH=/path/to/custom.enc).
    • --vault-path <path> global CLI argument (e.g. rumour --vault-path ./custom.enc vault list).
  • Key Derivation: A 256-bit key is derived from your master password and a randomly generated salt using the memory-hard Argon2 algorithm.
  • Authenticated Encryption: Individual secrets are encrypted using AES-256-GCM with a random 12-byte initialization vector (nonce) for every write.
  • Resolution Priority: Vault secrets have the highest priority in the variable resolution chain. If a vault. prefixed key resolves successfully, it takes precedence over all environment files, CLI overrides, and extracted variables.

CLI Management Commands​

You can manage the Vault using the rumour vault command suite.

Password Resolution Order​

When a vault command requires authentication, the password is resolved in this order:

  1. --password <password> (or -p) — explicit inline flag.
  2. RUMOUR_VAULT_PASS — environment variable.
  3. Interactive prompt — the CLI prompts you securely in the terminal.

1. Storing a Secret (set)​

# Store an API key securely under the name 'stripe_key'
rumour vault set stripe_key "sk_live_51Nz..."

# With explicit password (skip interactive prompt)
rumour vault set stripe_key "sk_live_51Nz..." -p "my_vault_password"

If a secret already exists, the CLI will prompt you before overwriting it. Skip the prompt with --yes or -y.

tip

Automatic Initialization & Creation: If the vault file does not exist (at the default location or the path specified via RUMOUR_VAULT_PATH / --vault-path), the set command will automatically initialize and create it. You will be prompted to define a new master password, which will be used to encrypt the new vault file and all future secrets written to it.

caution

All vault secrets must use the same master password. When adding a new secret to a vault that already contains entries, Rumour validates the provided password against an existing secret before writing. If the password does not match, the operation is rejected with Wrong master password. This prevents accidental multi-password corruption that would make secrets inaccessible at runtime.

2. Retrieving a Secret (get)​

# Decrypt and print the value of a secret
rumour vault get stripe_key

3. Listing Keys (list)​

# List all secret identifiers stored in the vault
rumour vault list
note

The list command only reads key names from the vault file. It does not decrypt any secret values and does not require password authentication.

4. Rotating the Master Password (rekey)​

# Change the vault master password
rumour vault rekey --old "current_password" --new "new_password"

# Interactive rekey (prompts for the current password securely)
rumour vault rekey --new "new_password"

This decrypts all secrets with the old password, derives a new encryption key using a fresh salt, and re-encrypts all secrets with the new password.

5. Purging the Vault (reset)​

# Completely purge the vault
rumour vault reset

# Reset without interactive confirmation prompt
rumour vault reset --yes

This permanently deletes the encrypted vault file and all stored secrets from disk.

caution

Password Recovery: The vault is securely encrypted using AES-256-GCM. There is no backdoor, recovery key, or way to retrieve password-protected secrets if the master password is forgotten. If you lose your password, rumour vault reset is the only way to restore vault functionality by purging the old vault file, though all previously stored secrets will be permanently lost.

Referencing Secrets in Requests​

To inject a Vault secret into a request, use the vault. prefix inside the standard {{}} placeholder syntax:

name = "get_payments"

[request]
method = "GET"
url = "{{base_url}}/payments"

[headers]
Authorization = "Bearer {{vault.stripe_key}}"

The resolver strips the vault. prefix and looks up the remaining key name (stripe_key) in the encrypted vault store.

Running with the Vault​

When executing requests that reference vault. secrets, Rumour needs the vault password to decrypt them.

Automated / CI Mode (Recommended)​

For rumour run and workflow executions, the vault password is read exclusively from the RUMOUR_VAULT_PASS environment variable. There is no interactive prompt during request execution:

# Set the vault password in your shell environment
export RUMOUR_VAULT_PASS="my_secure_vault_password"

# Run your test suite — vault secrets are decrypted silently
rumour run get_payments.toml

If RUMOUR_VAULT_PASS is not set, any {{vault.*}} placeholder will fail to resolve and the request will report a missing variable error.

Interactive Mode (Vault CLI Only)​

The interactive password prompt is available for rumour vault management commands (set, get, rekey). If neither password flags nor RUMOUR_VAULT_PASS is provided, the CLI prompts securely:

rumour vault get stripe_key
# Vault Master Password: [input hidden]

Variable Debugging​

When using --vars to inspect runtime variables after execution, vault secrets are automatically masked in the output:

RUNTIME VARIABLES:
  base_url = http://localhost:3000
  vault.stripe_key = [MASKED]

Any variable whose key starts with vault. or whose resolved value matches a known vault secret is displayed as [MASKED].

warning

Never check your vault password (RUMOUR_VAULT_PASS) or the raw secrets into version control. Ensure ~/.rumour/vault.enc is excluded from git and handled as machine-local configuration.