02RULES

The secret broker

Let the agent use an API token or password in a command without ever seeing its value, limited to the commands and hosts you choose.

View .md

Blocking .env keeps secrets out of the agent's context, but agents still need to call APIs, publish packages and log in to tools. The secret broker lets the agent use a secret without seeing it.

How it works#

You store the secret in Warden. The value goes into the macOS Keychain.
The agent writes a placeholder in a shell command: {{secret:NPM_TOKEN}}.
Warden checks the command against your rules and the secret's own limits. Only if it is allowed (or you approve it) does Warden put the value into that one command's environment and run it.
The value is scrubbed from the output, including common encodings of it, before the agent reads it.

Every use is recorded by name, never by value, and shows a SECRET chip in Decisions.

What the agent writes

$ npm publish --//registry.npmjs.org/:_authToken={{secret:NPM_TOKEN}}
$ curl -H "Authorization: Bearer {{secret:STRIPE_KEY}}" https://api.stripe.com/v1/charges

Add a secret#

Open Policies → Secrets, for Global or one project. A project secret shadows a Global one with the same name.
Add a secret: a name in capitals (NPM_TOKEN, STRIPE_KEY) and the value (at least 8 characters, so it can be scrubbed reliably). Or Import from .env to bring several in at once.
Choose which commands may use it without asking (for example npm publish* or gh api), and which hosts it may be sent to (for example *.stripe.com).
Choose what happens otherwise: Ask me first or Block it.

Rules for secrets#

The secret key matches a command that uses a brokered secret:

YAML

default: allow
rules:
  - ask: { secret: "*" }
    when: { trigger_mode: automated }
    reason: "Unattended runs ask before using any secret"
  - deny: { secret: PROD_DB_PASSWORD }
    unless: { command: psql }
    reason: "The production database password is only for psql"

A command that names the secret's environment variable directly is denied, so the agent can't read the value through the back door.