Skip to content
Legion

Secrets Broker

The Secrets Broker hands agent sessions the secret values they need, one request at a time, so an agent never holds a long-lived API key. An agent asks for a secret by name; the broker decides from the secret’s owner and tier whether to grant it at once, refuse it, or ask a person; and the person approves or denies it in Dispatch. A granted value reaches only the session that asked, in the environment of the command it runs, and every request, decision and use is recorded. That command is the agent’s choice and can read the value, so approve a secret only for a session you would trust with the value itself. The command keeps the value in its environment for as long as it runs; the grant’s expiry or revocation stops the session from reading the value again, not a command that already has it, and once the session’s own person revokes a grant it got without asking, that session asks before it gets those secrets again.

Terminal window
agent-secrets DEMO_API_KEY --reason "Deploy the example service" -- ./deploy.sh

That one command is all an agent runs. Everything else on this page explains what happens behind it.

Why it exists

Section titled “Why it exists”
  • No long-lived keys in agents. An agent’s environment, transcript and tools are the easiest place for a key to leak. With the broker, an agent session holds only a signing key of its own that dies with the session, and fetches a value for exactly the command that needs it.
  • A person approves what needs approval. Each secret’s owner and tier, two tags on the secret itself, say who gets it automatically and who needs a person’s yes. Approving is one click in Dispatch, where that person already works.
  • Every grant is recorded. Each approval rests on a signed, content-addressed record of who asked, for what, why, and who decided, which the broker re-verifies every time it releases a value.

How a request flows

Section titled “How a request flows”
sequenceDiagram
    participant Agent as Agent session
    participant CLI as agent-secrets
    participant Helper as agent-secrets-helper
    participant Broker as Secrets Broker
    participant Dispatch
    actor Person as Approver
    Agent->>CLI: agent-secrets DEMO_API_KEY -- ./deploy.sh
    CLI->>Helper: sign this request as my session
    Helper-->>CLI: signed request and proof
    CLI->>Broker: POST /v1/requests
    Broker->>Broker: read the secret's owner and tier
    alt granted at once
        Broker-->>CLI: granted
    else a person must approve
        Broker-->>CLI: pending, and the approver its record names
        Dispatch->>Broker: pending requests for the person signed in
        Person->>Dispatch: Approve
        Dispatch->>Broker: approve, as that person's login
        CLI->>Broker: poll until granted
    end
    CLI->>Broker: POST /v1/grants/{id}/values
    Broker-->>CLI: the values, read fresh from the secret store
    CLI->>Agent: run ./deploy.sh with DEMO_API_KEY in its environment

On a machine, agent-secrets-helper holds each agent session’s key and signs for it. In a container (a box) the container holds its own key, and in Kubernetes each Legion worker pod does; the request flow is the same. Run an agent in a container shows a box’s setup.

The pieces

Section titled “The pieces”
Piece What it does Where it runs
Secrets Broker (envoy-broker) Enrolls sessions, decides each request from the secret’s owner and tier, records requests and decisions, and releases granted values. A server, beside Postgres and the secret store.
agent-secrets The command an agent runs to use a secret, the tool people and launchers use to log machines in and inspect sessions, the tool people list and revoke their machine logins and live grants with (machine list, grant list), and the tool people manage the secrets themselves with, under their own cloud sign-in. Wherever agents run, and a person’s own machine.
agent-secrets-helper A per-user daemon that holds each host agent session’s key, enrolls it, and signs for it. Each machine that runs agents directly.
Dispatch Shows people the requests they must decide and the grants they can revoke, and passes their decisions to the broker. Dispatch’s server and web app.
Legion Enrolls every worker pod it runs on Kubernetes, so a phase worker can use agent-secrets like any other session. Legion’s daemon.

How it fits with Legion and Dispatch

Section titled “How it fits with Legion and Dispatch”

Dispatch is where people decide: its Inbox lists Credential requests beside the asks waiting on them, its credential pages show what an agent asked for and why, and its Settings page lists the live grants a person can revoke. The broker holds no Dispatch credential; Dispatch’s server calls the broker on the signed-in person’s behalf.

Legion runs agents. When its Kubernetes runtime is configured with the broker, the Legion daemon logs itself in with its own Kubernetes ServiceAccount token, which no person approves, and enrolls every worker pod it starts, so each pod’s agent gets only the grants of that pod. See how Legion, Dispatch and the broker fit together.

Where to go next

Section titled “Where to go next”