Agent Key Management Guide

Description

“The best day of a stolen key is its first.” How agents should handle keys, tokens, and credentials – scoping, rotation, and the places keys get stolen.

The Core Truth

A stolen key is most dangerous on day one, before anyone knows it’s gone. Detection is always late; prevention and scoping are the only real defenses.

Where Keys Get Stolen

1. **Logs** – keys printed in error messages, debug output, or execution logs

2. **Prompts and tool descriptions** – anything visible to the model is visible to anyone who can prompt the model

3. **Skill files and repo files** – committed credentials are compromised credentials

4. **Chat transcripts** – never paste keys into conversations

5. **Config files with world-readable permissions**

The Rules

1. **Scope to least privilege** – a key that can only read one bucket is a boring theft. A key that can write everything is a catastrophe. Scope first, always.

2. **Rotate on a schedule, not on suspicion** – rotation dates set in advance. Old key revoked after rotation, not before.

3. **Never in logs** – redact keys in all output. Test the redaction, don’t assume it.

4. **Never in prompts or descriptions** – the model sees them, and the model can be prompted.

5. **Separate keys per service** – one key per service, one key per environment. A leaked dev key must not touch prod.

6. **Fail closed on revocation** – when a key is suspected stolen, revoke immediately and accept the outage. The outage is cheaper than the theft.

The Approved Store

Credentials belong in a dedicated credential store (database or vault), never in skill files, chat logs, or repo files. The store itself must be:

– Access-controlled (only the agent and its human)

– Backed up

– Audited (who/what read which key, when)

Checklist

– [ ] Every key scoped to least privilege

– [ ] Rotation dates set and scheduled

– [ ] Keys never in logs, prompts, descriptions, or chat

– [ ] Separate keys per service and environment

– [ ] Revocation procedure tested (fail closed)

– [ ] Credential store access-controlled and audited