Secret Handling Policy

How applications and CI handle secrets and environment variables using keyctl.

Overview

Company standard: applications do not use local secrets. Secret values live remotely in Azure Key Vault and are fetched at runtime by the keyctl CLI. Plaintext secret values are not created, committed, or populated in the repo or on disk.

• Real secret values do not belong in .env, .env.local, config files, or code.
• API keys, tokens, connection strings, and passwords are not hardcoded.
• Secrets are injected into a process at runtime via keyctl run -- <command>.
• Needed secrets are declared in a committed keyctl.yaml by name only, never by value.

The committed setup key (write-only by default)

For internal, trusted repos, a write-only setup key (the -wo key) MAY be committed in keyctl.yaml as setupKey:. This lets the CLI auto-enroll a device on first use, so nobody runs keyctl login manually. A write-only key is safe to commit because:

• It can enroll a device and add/update secrets, but it cannot read them — so a leaked repo can never be used to exfiltrate secret values.
• It grants no read/rotate/admin power. Reading and rotation require separate credentials.
• Secret values still never touch the repo; the key is scoped to one project and is centrally revocable/rotatable.

Admin keys and the global admin token are out of scope for committing — they stay out-of-band. A read-only (-ro) key may also be committed when repo holders are intended to read secrets at runtime, and only when everyone with repo access is already trusted to read that project's secrets.

Running an app with secrets

Instead of npm start, python app.py, go run ./cmd/server, etc., wrap it:

keyctl run -- npm start
keyctl run -- python app.py

keyctl run reads keyctl.yaml, fetches the declared secrets over HTTPS, injects them as environment variables into the child process only, then discards them. Nothing is written to disk. Reading secrets requires a read-capable credential (admin or read-only, or the write-only device that wrote them).

The config file (commit this)

keyctl.yaml at the repo root maps environment variable names to Key Vault secret keys. Values are never stored here, so it is safe to commit.

project: payments-service
apiUrl: https://api.getkeyctl.com
setupKey: <write-only setup key>  # OPTIONAL, -wo key — enables auto-enroll for writes
secrets:
  DATABASE_URL: database-url      # ENV_VAR_NAME: keyvault-secret-key
  STRIPE_KEY:   stripe-secret-key

Each project's secrets are namespaced by the project name in the vault (stored as proj--<project>--sec--<key>). Scaffold config with keyctl init --project <name>.

Authentication model

keyctl uses a three-tier credential model:

Enrollment sends a setup key to POST /v1/enroll, receives a device-bound refresh token stored in the OS keychain, and discards the setup key. Every command then silently exchanges the refresh token for a fresh short-lived access token.

Setup key roles

Read-your-own-writes (write-only devices)

A write-only device is automatically recorded as the owner of every secret it creates and can read back its own secrets. Other devices — even those holding the same committed write-only key — cannot read those secrets (different device ID → 403). Ownership is also enforced on overwrites and deletes, preventing repo-clone poisoning.

Common commands

In CI, only the one-time setup key is stored (as KEYCTL_KEY); keyctl enrolls in-memory and mints an access token per run. Individual secrets are never added to CI variables.

env:
  KEYCTL_KEY: ${{ secrets.KEYCTL_SETUP_KEY }}
  KEYCTL_API_URL: https://api.getkeyctl.com
run: keyctl run -- <command>

Admin operations are human-only

Admin setup keys and the global admin token are human-only credentials. They are out of scope for automated tooling and are not expected to appear in generated output, logs, or commits. Rotating and minting keys, running keyctl login with an admin key, and demo-project resets are admin actions handled by a person.

Interim measure (before keyctl is set up)

Until a team fully adopts keyctl, an existing .env is tolerated only when it is encrypted at rest with the project setup key rather than left in plaintext: keep the plaintext file out of git, store only the encrypted form, and treat it as temporary — migrate the values into keyctl and delete the local file when possible. Prefer keyctl run over any local file whenever it is available.

Migrating a hardcoded secret into keyctl

When a hardcoded secret is found in code, the goal is to move the value into keyctl and out of the source. This is human-gated and must be done without leaking the value:

• Detect with tooling, not guesswork. Use the repo scanner (gitleaks detect / the committed pre-commit hook) to avoid false positives from test fixtures and placeholder values.
• Get explicit human approval first. Don't auto-migrate or auto-commit; show the finding (file, line, kind of secret) without pasting the value anywhere, and wait for confirmation.
• Write the value via stdin, never as a CLI argument — an argument exposes it in the process table, shell history, and command logs:

  printf '%s' "$VALUE" | keyctl secret set stripe-key --project payments-service --stdin

• Replace the literal with process.env.X and map it in keyctl.yaml, then run via keyctl run.
• Treat the exposed value as compromised — rotate it at the source, not just relocate it. Scrubbing git history is a destructive, human-owned follow-up.

Questions?

Email nir@dash.security or ask in #keyctl on Slack.