> For the complete documentation index, see [llms.txt](https://handbook.harmonic.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.harmonic.security/handbook/4.-data-protection-and-residency/4.7-secrets-and-credential-hygiene-in-prompts-and-tools.md). # 4.7 Secrets and credential hygiene in prompts and tools How to keep secrets out of prompts, files, tool parameters, shell history, logs, telemetry, and model-visible context. *Last reviewed: August 18, 2026* {% hint style="info" %} Secrets should never be normal prompt material. Give agents safe credential paths, and block secrets from prompts, files, and telemetry. {% endhint %} ## What security teams need to know about secrets and credential hygiene in prompts and tools Secrets leak into AI systems through copy-paste, code snippets, logs, environment files, CI output, tool parameters, and screenshots. Once included, they may appear in transcripts, telemetry, outputs, and downstream tools. The control pattern is to deny direct reads where possible, inject secrets at runtime through approved systems, and redact before telemetry leaves the runtime. ## Common secrets and credential hygiene in prompts and tools security failures * Agents read `.env` or cloud credential files during debugging. * A user pastes an API key into a prompt to make an example work. * Tool parameters send secrets to logs or traces. * CI outputs environment variables into a transcript. * A generated fix commits a secret into source control. ## Secrets and credential hygiene in prompts and tools security controls checklist * Block known secret files from agent reads. * Use secret managers and short-lived credentials for tools. * Add secret scanning to repos, CI logs, prompts, and telemetry where feasible. * Redact tool parameters before SIEM ingestion. * Rotate credentials after suspected prompt or log exposure. ## Prefer mediated credentials A model rarely needs the raw secret. Let a broker or tool perform the approved operation using a short-lived credential bound to the agent, task, destination, and action. Return only the minimum result to the model. Block secrets from prompts, files, environment discovery, tool arguments, command output, traces, error messages, and generated artifacts. Scan both inputs and outputs, because agents can retrieve secrets from local files or tool results even when the user did not paste them. Test revocation during an active run and confirm the agent cannot continue using a cached token. ## Anthropic ### Overview Claude Code offers a credential path that avoids pasted secrets: `apiKeyHelper` can provide dynamic or rotating credentials, and the documented precedence chain — cloud provider credentials, bearer token, API key, `apiKeyHelper`, then OAuth and subscription credentials — tells you exactly which credential a session will use when several are present. Pair that with permission rules: deny rules take precedence over ask and allow rules, so a deny on `.env` files, key files, and credential directories holds even where broad read access is allowed, and managed settings can enforce those permission rules organization-wide. For hosted work, Managed Agents supports vault-based authentication for credentials, keeping secrets out of prompts and environment blocks entirely. Keep skill scripts, hooks, and MCP servers inside the same review, since each can read files or emit tool parameters that end up in telemetry. Cowork expands the secret boundary. Remote sessions can call connected tools with short-lived credentials in an Anthropic-managed sandbox, while local Cowork can reach desktop files, browser sessions, and applications. Its OpenTelemetry stream can include full prompts, tool parameters, and file paths. Deny sensitive locations, narrow connector scopes, and redact telemetry before it reaches shared storage. Claude Tag keeps provisioned credentials outside the thread sandbox. Agent Proxy retrieves a matching secret from a separate store and injects it at the network boundary, so the model and sandbox do not receive the stored key. That protection depends on narrow connection rules: constrain the host, path prefix, HTTP methods, workspace, and channel scope, and use a dedicated service account that can be revoked without affecting a person. ### Anthropic documentation * [Claude Code authentication](https://code.claude.com/docs/en/team) * [Configure permissions](https://code.claude.com/docs/en/permissions) * [Claude Code settings](https://code.claude.com/docs/en/settings) * [Claude Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview) * [Claude Cowork architecture overview](https://support.claude.com/en/articles/14479288-claude-cowork-architecture-overview) * [Monitor Claude Cowork activity with OpenTelemetry](https://support.claude.com/en/articles/14477985-monitor-claude-cowork-activity-with-opentelemetry) * [Claude Tag security and data handling](https://claude.com/docs/claude-tag/concepts/security-and-data) ### Applicable Harmonic guides for Anthropic * [Securing Claude Cowork: A Security Practitioner's Guide](https://www.harmonic.security/resources/securing-claude-cowork-a-security-practitioners-guide) ## OpenAI ### Overview OpenAI's guidance starts with key handling: store API keys in environment variables or secret management services, and use separate projects to isolate staging from production with different rate and spend limits — separation that also limits how far one leaked key reaches. Workload identity federation removes the long-lived secret altogether: trusted workloads exchange external identity tokens for short-lived OpenAI access tokens, with service account mappings controlling which external identities may mint them. For agent runs, Codex sandbox policy bounds file, command, and network access, which is the mechanism for keeping credential files out of an agent's reach during local or cloud work. Desktop Work and Computer Use can also reach local files and applications under approved permissions, so review shell profiles, credential stores, browser sessions, and app tokens in the local threat model. OpenAI Work compliance records omit files, actions, and tool calls, which makes prevention and downstream logging more important. None of this protects a secret pasted into a ChatGPT prompt, so detection and rotation still matter on chat surfaces. ### OpenAI documentation * [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices) * [Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation) * [Codex sandboxing](https://developers.openai.com/codex/concepts/sandboxing) * [Work Admin FAQ](https://learn.chatgpt.com/docs/enterprise/work-admin-faq) * [Computer Use](https://learn.chatgpt.com/docs/computer-use) ### Applicable Harmonic guides for OpenAI * [Securing Codex Best Practice](https://www.harmonic.security/resources/securing-codex-best-practice) ## Frequently asked questions about secrets and credential hygiene in prompts and tools ### Can secrets be pasted into AI tools? No — treat a pasted secret as exposed. It can persist in conversation history, provider-side storage, telemetry, and any downstream tool the session touches. Use secret managers, runtime environment injection, or brokered credentials such as Claude Code's `apiKeyHelper` or OpenAI workload identity federation instead. ### Which files should agents be blocked from reading? Start with `.env` files, private keys, cloud credential files, SSH keys, token stores, password exports, and CI secret files. In Claude Code, express these as deny rules, which take precedence over ask and allow rules; in Codex, keep the sandbox policy narrow enough that credential paths sit outside the agent's reachable filesystem. Revisit the deny list whenever a new tool, hook, or skill gains file access. ### How do secrets leak through tools? Tool parameters are the quiet path: a secret read from a file can be passed as an argument, logged in a trace, echoed in command output, or committed by a generated fix. Screenshots and CI logs add further copies that outlive the session. Redact tool parameters before telemetry leaves the runtime, and scan generated code before it merges. ### What should happen after a secret is exposed? Revoke or rotate the credential first — assume any copy in a transcript or log is compromised. Then find the durable copies: conversation history, telemetry, SIEM events, generated files, and downstream systems the session wrote to. Finish by asking whether the exposure path — a missing deny rule, an over-broad sandbox — needs a control fix, not just a cleanup. ### Should telemetry include tool parameters? Only with redaction and a clear reason, because parameters routinely carry secrets, tokens, and customer data. Filter or hash sensitive fields before SIEM ingestion, and prefer counts and classification metadata over raw values. Where raw parameters are needed for investigations, restrict access and shorten retention accordingly. ## Applicable regulations and frameworks | Governance page | Relationship to this article | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | G.1 Map your controls to NIST AI RMF and CSF 2.0 | This article supplies implementation evidence for the NIST AI RMF and matching NIST CSF 2.0 outcomes. | | G.3 DORA and AI resilience in financial services | Conditional: for a DORA-regulated workflow, this supports data protection, integrity, and third-party service review. | | G.5 SANS Critical AI Security Guidelines mapping | This article implements relevant SANS Data Protection guidance. | | G.6 Write an AI Acceptable Use Policy that holds up | This article supplies a technical or process control used to enforce the acceptable-use policy. | | G.7 Ownership and RACI for AI security | This control depends on the ownership and evidence responsibilities defined in the RACI. | | G.9 HIPAA controls for AI systems handling PHI | Conditional: for a workflow handling ePHI, this supports HIPAA PHI identification, minimum-necessary handling, retention, and disclosure controls. | *G.2, G.3, G.4, and G.9 are conditional mappings. They apply only when the deployment is within the legal or regulatory scope described on the linked governance page.* ## Related handbook guidance * [4. Data Protection & Residency](/handbook/4.-data-protection-and-residency.md) * [1.6 API keys and service accounts governance](/handbook/1.-identity-and-access/1.6-api-keys-and-service-accounts-governance.md) * [3.8 File and filesystem access controls](/handbook/3.-runtime-sandbox-and-autonomy/3.8-file-and-filesystem-access-controls.md) * [5.2 Data exfiltration via tools and connectors](/handbook/5.-threats-and-adversarial/5.2-data-exfiltration-via-tools-and-connectors.md) * [2.4 Analyzing skills for risk](/handbook/2.-supply-chain-and-extensibility/2.4-analyzing-skills-for-risk.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://handbook.harmonic.security/handbook/4.-data-protection-and-residency/4.7-secrets-and-credential-hygiene-in-prompts-and-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.