Agent Secret Management Specification

TL;DR

Agents amplify the blast radius of every leaked credential. A single prompt injection (see Prompt Injection Defense for Agents) that exfiltrates a service-account token compromises every account that token can reach. The fix is mechanical: secrets live in a vault, the agent never sees raw secret material, every tool call uses a short-lived scoped credential, and secret access is logged independently of normal traces.

Scope

This specification covers how an agent runtime acquires, scopes, uses, rotates, and audits secrets at runtime. It assumes a conventional secret store (HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or equivalent) backed by an HSM-grade KMS — AWS KMS HSMs are FIPS 140-2 Level 3 certified, for example. Selecting and operating that store is out of scope.

1. Storage Tier

The runtime MUST store every secret in a vault that provides:

• HSM- or KMS-backed encryption at rest.
• Per-secret access policies tied to identity (per OWASP Secrets Management Cheat Sheet).
• Versioning, with a documented previous-version retention window.
• An audit log of every read.

The runtime MUST NOT store secrets in:

• Source repositories, even encrypted.
• Container images or build artifacts.
• Application configuration files committed to disk.
• Long-lived environment variables on shared hosts.
• Any field that is logged, traced, or sent to telemetry.

For cloud workloads, IAM instance / task / workload identity is preferred over long-lived static keys; the runtime SHOULD authenticate to the vault via workload identity, not an embedded token.

2. Static vs Dynamic Secrets

Where the target service supports them, the runtime MUST prefer dynamic, short-lived secrets over static long-lived ones. Dynamic secrets — generated on demand, automatically revoked after a TTL — sharply reduce the window of compromise and make manual rotation unnecessary, as documented in HashiCorp Vault's static vs dynamic secrets guide.

3. Tool-Scoped Permissions

Every secret MUST be scoped to the narrowest possible (tool, action, tenant, user). The runtime MUST:

1. Resolve the secret reference at the moment of the tool call, not at agent start.
2. Bind the secret's IAM scope to the requesting user where possible (per the Databricks defense framework).
3. Reject any tool call that would require a secret outside the scope already authorized for the run.
4. Never grant the agent a secret that covers more than one tenant.

A single "god" service-account secret used by every tool is the canonical anti-pattern — it converts every prompt injection into a tenant-wide compromise.

4. Exposure Prevention

Secrets MUST never enter the LLM context window. The runtime MUST:

• Pass tool arguments by secret reference ({ "secretRef": "vault://prod/stripe/api_key" }), not by value. The tool resolves the reference inside its own process boundary.
• Strip any secret-shaped substrings (high-entropy tokens, known prefixes like sk-, ghp_, xoxb-) from tool outputs before they are returned to the model.
• Strip the same patterns from logs, traces, and crash dumps. The OWASP DevSecOps guideline lists secret-detection tooling (Yelp detect-secrets, gitleaks, OWASP DeepSecrets) that SHOULD be wired into log pipelines, not only into CI.
• Never echo secret material in error messages or stack traces shown to users.

Agents MUST NOT be allowed to read raw .env files, fetch arbitrary KMS-encrypted blobs, or call generic "get any secret" tools.

5. Rotation Policy

The runtime MUST support secret rotation without an agent restart. At minimum:

• Static secrets: maximum lifetime per secret class, with an automated rotation hook (per AWS KMS automatic rotation and the OWASP rotation guidance).
• Dynamic secrets: TTLs short enough that rotation is implicit (default 1 hour or less for human-driven workflows, seconds-to-minutes for fan-out workflows).
• Compromise-driven rotation: a documented "break-glass" path that revokes and re-issues every secret in a class within minutes.

Rotation events MUST be auditable: who triggered, what was rotated, when, and which downstream services were notified.

6. Audit Logging

Secret operations MUST emit an audit stream separate from application traces. Each entry MUST contain:

• Timestamp.
• Identity that requested the secret (user, agent, workflow ID).
• Secret reference (never the value).
• Operation (read, rotate, revoke).
• Source IP / network identity where applicable.
• Outcome (success, denied, error).

Audit logs MUST be append-only, retained per the regulatory regime in scope (GDPR, HIPAA, SOC 2), and protected from being read by the same identities that read secrets.

7. Compromise Response

The runtime SHOULD assume any individual secret will eventually be compromised and define:

• Detection: log signatures, anomalous-access alerts, off-hours-read alerts, dead-letter queues for repeated denied reads.
• Containment: instant revocation primitives that work without code deploys.
• Recovery: redeploy with new secrets, audit downstream usage, notify affected users.

For static secrets that may have been exposed in code or logs, the OWASP DevSecOps guideline is unambiguous: "when a credential is leaked, it is already compromised and should be invalidated." Cleaning the logs is not a substitute for rotation.

FAQ

Q: Can the agent itself rotate secrets?

No. Rotation is a privileged, infrequent operation that should be performed by a dedicated workflow with stricter approval gates than the agent runtime.

Q: Should secrets ever appear in tool arguments shown to the model?

No. Pass references; resolve inside the tool. Anything in the model's context is exfiltratable via prompt injection (see Prompt Injection Defense for Agents).

Q: What about OAuth user tokens?

Same rules. Store in the vault, scope to one user, prefer short-lived access tokens with refresh rotation handled outside the agent loop. Never log the bearer token.

Q: Do we need an HSM?

For regulated workloads (FIPS 140-2/3, PCI, HIPAA), yes — either a managed HSM (AWS CloudHSM, GCP Cloud HSM, Azure Dedicated HSM) or a KMS that itself runs on FIPS-certified HSMs (e.g. AWS KMS at FIPS 140-2 Level 3).

Q: How does this interact with agent observability?

Secret access logs MUST be a separate stream from regular traces, with stricter access controls. See Agent Tracing and Spans for how to keep span attributes secret-safe while preserving debug utility.