SAYLOR Keep API keys, wallet keys, tokens, cookies, and recovery material out of prompts, repositories, logs, browser storage, and tool responses.
The result you're building
A secret architecture in which agents receive only narrowly scoped, short-lived capabilities; raw secrets stay out of prompts/repos/logs/browser storage/tool outputs; leaks are detected; and revoke/rotate recovery is tested.
Use this guide when
- Agents call authenticated APIs, browsers, wallets, cloud tools, or databases.
- Auditing a repository/workflow for secret leakage.
Do not use it as a substitute for
- Do not paste keys, seed phrases, tokens, cookies, or private env files into model context.
- Do not use redaction after logging as the only control.
Before you change anything
- Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
- Secret inventory, owners, consumers, scopes, expiry, and storage.
- Prompt/tool/log/browser/repository data flow.
- Secret manager or broker capabilities and rotation support.
- Canary, detection, incident, and revocation procedure.
Understand the system before fixing it
Minimize possession, not just disclosure
Best design lets the agent request a capability or operation without ever receiving reusable credential bytes.
Redaction must occur before serialization
Exceptions, HTTP traces, subprocess output, and provider responses can bypass application-level cleanup.
Rotation is part of normal design
A secret that cannot be revoked independently or whose consumers cannot reload safely creates operational lock-in.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Secret in source/history | Repository leak | Revoke then scan history/artifacts | Deletion/force-push alone does not invalidate copies. |
| Secret in prompt/tool output | Model/context leak | Identify provider/retention and revoke | Assume exposure beyond local transcript. |
| Secret only in logs/errors | Observability leak | Trace logger/exception path | Redact at source/central sink and restrict access/retention. |
| Agent needs broad long-lived token | Architecture | List actual operations/resources | Broker short-lived scoped token or server-side action. |
Step-by-step procedure
Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.
Step 01 — Inventory and classify secrets
Why: Unknown credentials cannot be protected or rotated.
Do: Record owner, purpose, system, scope, privilege, expiry, storage, consumers, and rotation/revocation.
Read the result: Unowned, shared, admin, non-expiring secrets are priority.
Next: Remove duplicates/obsolete entries after verification.
Step 02 — Keep raw secrets outside model path
Why: Instructions cannot guarantee non-disclosure.
Do: Use secret manager, server-side proxy, workload identity, OAuth consent, or broker issuing short-lived scoped capability; tool accepts reference, not value.
Read the result: Prompt/transcript/tool result contains no reusable secret.
Next: Separate agent role from secret reader.
Step 03 — Constrain scope and lifetime
Why: Leak impact follows privilege and validity.
Do: Use per-service/user/tenant credentials, least scopes/resources, short expiry, audience binding, IP/egress limits where suitable, and separate test/prod.
Read the result: Credential cannot access adjacent resources.
Next: Automate renewal without logging token.
Step 04 — Redact before logs and outputs
Why: Downstream sinks multiply copies.
Do: Centralize allowlisted structured logging; strip auth headers/cookies/query secrets/env/subprocess output; cap traces and error bodies.
Read the result: Canary never appears in logs/model output/artifacts.
Next: Protect crash dumps/support bundles.
Step 05 — Scan and test
Why: Leaks recur through new code paths.
Do: Run pre-commit/CI/history/artifact/container scans and runtime canary tests; block builds on verified secrets while handling false positives safely.
Read the result: Never upload private repo/history to unapproved scanner.
Next: Record findings without copying secret.
Step 06 — Exercise incident rotation
Why: A written plan can fail when consumers cache credentials.
Do: Revoke, issue replacement, deploy/reload consumers, verify old denial/new success, audit use, and document affected data.
Read the result: Emergency path meets downtime objective.
Next: Repeat periodically.
Worked example
Evidence collected
- Token was valid and had message-send permission.
- Snippet may be cached/indexed/copied.
- Git history and CI logs also contain value.
- No evidence yet of abuse.
Decision: Deletion is not containment; the token must be treated as compromised.
Actions taken
- Revoked token immediately and issued a least-scope replacement.
- Updated secret store/consumer, verified old denial/new success.
- Purged/redacted controlled logs/history where appropriate and audited activity.
Why this example matters: Truthful recovery assumes copies exist once a secret crossed the boundary.
Verify, recover, and hand off
Completion tests
- A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
- Agent/model never receives raw reusable secrets.
- Credentials are least-scope, short-lived, and environment-separated.
- Canary tests show no leak in logs/errors/outputs/artifacts.
- Old credential revocation and new reload are proven.
- Repository/CI/runtime scans run with approved privacy.
- Incident owner and audit trail exist.
Rollback or safe recovery
- Revoke first; then replace consumers and remove controlled copies.
- Return to prior credential only if it was never exposed and remains valid.
- Disable affected integration if safe rotation cannot be completed.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| App breaks after rotation | Consumer caches secret or update order wrong. | Use dual/overlap only if provider supports; reload and verify. |
| Scanner flags dummy strings | Pattern lacks validation/context. | Use verification/allowlist without weakening real-secret block. |
| Secret appears in URL | Client/protocol puts credential in query. | Move to secure header/token exchange and scrub proxies/logs. |
| Tool needs user password | Architecture lacks delegated auth. | Use OAuth/workload identity/server broker; do not collect password. |
Reusable handoff record
- Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
- Secret inventory and data-flow map.
- Broker/manager/scoped-credential architecture.
- Pre-serialization redaction and scan controls.
- Canary and cross-scope denial results.
- Revoke/rotate/audit/incident runbook.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| context | object | Versioned environment, target, and requested outcome. |
| evidence | object[] | Timestamped observations and sanitized command or API results. |
| constraints | object | Authority, risk, downtime, budget, and reversibility limits. |
| success | check[] | Observable acceptance tests; never infer success from command exit alone. |
Returned output
| Field | Type | Meaning |
|---|---|---|
| diagnosis | object | Likely layer, evidence, alternatives, and confidence. |
| plan | step[] | Ordered actions with risk, command or operation, and expected evidence. |
| verification | check[] | Pass/fail checks that prove the requested outcome. |
| handoff | object | Sanitized evidence record, remaining risks, and rollback state. |
Agent refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.
Official reference starting points