SAYLOR The result you are building
Finished result: 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
- 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
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.
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.
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.
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.
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.
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
Starting problem: A bot token appears in a public code snippet and is deleted minutes later.
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.
Proof of completion: Old token is invalid; new token never enters source; consumer works; audit window and incident record are complete.
Why this example matters: Truthful recovery assumes copies exist once a secret crossed the boundary.
Verify, recover, and hand off
Completion tests
- 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
- 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.
For agents
This guide also defines a structured diagnose/propose/execute contract for building an agent-facing tool around this workflow (a design reference, not a live endpoint on this site today):
Required inputs: context, evidence, constraints, success. Returned output: diagnosis, plan, verification, handoff.
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.
References
- https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
- https://owasp.org/www-project-top-10-for-large-language-model-applications/