Claude Code Security Best Practices

Claude Code Security Best Practices

Claude Code is a powerful automation tool. Like any tool with broad access to a codebase and the ability to run shell commands, it introduces a security surface that requires deliberate management. The risks are not exotic, they are the standard problems of credential exposure, over-permissioned access, and insufficient audit visibility, applied to a new context.

Eight practices address the most common failure modes seen in Claude Code deployments. Implement them before problems occur rather than after.

For the organizational layer, governance, SSO, and team-level policy, the enterprise development guide covers those controls in full.

Practice 1: Never Put Secrets in Prompts

Prompts sent to Claude Code are transmitted to the Anthropic API. Anything in the prompt is sent over the network, stored in logs, and potentially visible to API monitoring infrastructure. Secrets, API keys, passwords, database connection strings, tokens, should never appear in prompts.

This is a common mistake because it feels natural: Here is our API key, use it to call the endpoint and check the response. The prompt works. The key is now in a network request log.

Use environment variables for secrets. Reference them in the code Claude Code generates, not in the prompt.

If Claude Code needs to understand the structure of a configuration file, provide a redacted example with placeholder values, not real credentials.

Practice 2: Add CLAUDE.md to .gitignore if It Contains Sensitive Information

The CLAUDE.md file provides persistent context to Claude Code sessions. When it contains sensitive information, internal system descriptions, internal API endpoint structures, team-specific operational details, it should not be committed to a repository that others can access.

Add CLAUDE.md to .gitignore for repositories where the file contains information that should not be broadly shared. For organization-wide or team-wide CLAUDE.md files, store them in a controlled location outside the repository and reference them via the CLAUDE_CONFIG environment variable rather than checking them in.

The CLAUDE.md guide covers how to structure the file so it is useful without exposing sensitive details.

This is especially important for open-source repositories or repositories with broad internal access. A well-crafted CLAUDE.md may contain exactly the information an attacker needs to understand an internal system.

Practice 3: Review Before Run

Claude Code’s bash tool can execute shell commands. In interactive sessions, each tool use requires explicit approval by default. In headless mode with --yes, approvals are automatic.

The discipline: in interactive sessions, read what Claude Code proposes to execute before approving. This sounds obvious. In practice, developers in flow state approve quickly without reading.

Establish a personal rule to pause and read each proposed command before approving, regardless of how confident you are that it is correct.

For headless CI/CD runs, scope bash access tightly:

• If the automated task only needs to read files, disable the bash tool entirely.
• Reserve --yes with bash access for tasks that genuinely require file writes.

Approving a command without reading it is the Claude Code equivalent of sudo-ing a script you downloaded without reading it first. The speed is the same. The risk is the same.

Practice 4: Use Read-Only MCP Servers in CI

MCP servers extend Claude Code’s ability to interact with external systems. In CI/CD pipelines, the principle of least privilege applies: automated runs should only have access to the capabilities they require for the specific task. For guidance on how MCP servers are configured and what access controls are available, the MCP setup guide covers the configuration options in detail.

Configure read-only MCP server variants for CI use:

• A database MCP server used in CI for query analysis should have read-only credentials, not the same read-write credentials used in development.
• A file system MCP server in CI should be scoped to the specific directory structure needed, not the full file system.

Review the MCP servers enabled in each pipeline step. If a step only needs to read repository content, it should not have access to MCP servers that connect to production systems.

Practice 5: Rotate API Keys on a Schedule

The Anthropic API key used by Claude Code should be rotated on a defined schedule:

• Interactive developer use: 90-day rotation is reasonable.
• CI/CD pipeline automation: Rotate every 30–60 days, and immediately upon any team member departure.

Store API keys in secret management systems, AWS Secrets Manager, HashiCorp Vault, GitHub Secrets, rather than in environment files or configuration files that may be committed. Automate rotation where possible: a key that is rotated automatically on a schedule is more reliable than one that depends on a human remembering.

When a key is rotated, confirm the old key is revoked, not just replaced. A key that is replaced without revocation remains valid and exploitable.

Practice 6: Scope Permissions to the Minimum Required

Claude Code supports configuring which tools are available in a session. The default configuration enables a broad set of capabilities. Production deployments should scope permissions to exactly what is needed:

• Code review only: Disable bash, disable file write tools, disable MCP servers.
• Code generation + writing: Enable file writes to the specific directory, disable network MCP servers.
• CI/CD security scan: Read-only file access, no execution capability.

Document the permission scope for each automated Claude Code use case. When someone reviews the workflow six months later, the rationale for the permissions should be explicit, not inferred.

Practice 7: Enable Audit Logging

If someone asks “what did Claude Code do in that pipeline run last Tuesday?” you should be able to answer. Without audit logging, you cannot.

In enterprise tier deployments, audit logging is available as a built-in feature. In API-based deployments, implement logging at the application layer: record the prompt, the tools invoked, the outputs produced, and the session metadata for every automated run.

For interactive developer sessions, audit logging is harder to enforce but still valuable for sensitive repositories. Consider requiring that Claude Code sessions in sensitive environments be run with output logging enabled, with logs forwarded to your SIEM (security information and event management) system.

Audit logs serve two purposes:

• Incident response, understanding what happened after something goes wrong.
• Compliance, demonstrating that controls exist and are functioning.

Practice 8: Network Isolation for Sensitive Repositories

Repositories containing particularly sensitive IP, unreleased product code, core algorithm implementations, regulated data processing logic, warrant additional network controls beyond standard Claude Code configuration.

Consider running Claude Code for these repositories in an environment where network access is restricted to the Anthropic API endpoint only. This prevents a compromised session from exfiltrating data to arbitrary external endpoints via MCP servers or bash commands.

For organizations operating in highly regulated environments (financial services, healthcare, defense-adjacent), evaluate whether Claude Code is appropriate for use with the most sensitive codebases at all. The zero-data-retention enterprise agreement addresses model training concerns. It does not address the broader question of whether a network-connected AI tool is appropriate for your highest-sensitivity code.

Organizations that need a fully consolidated and security-governed AI environment may find a Private AI Workspace a better fit than self-managed developer configurations.

Security Risk Reference

Common Questions on Claude Code Security

Is code sent to Claude Code stored by Anthropic?

Under the standard API agreement, Anthropic does not use API inputs for training by default. The enterprise agreement adds explicit zero-data-retention provisions.

For sensitive codebases, confirm the current data handling terms directly with Anthropic and ensure the applicable agreement is in place before use.

Can Claude Code be used in air-gapped environments?

Claude Code requires network access to the Anthropic API. Air-gapped operation is not currently supported.

For environments requiring air-gapped AI coding tools, evaluate locally-hosted model options. Claude Code specifically is not designed for offline use.

How do we detect if a Claude Code session did something unexpected?

Audit logging (Practice 7) is the primary detection mechanism. Review logs for tool invocations that fall outside the expected pattern for a given use case.

Unexpected bash commands, file writes to unexpected locations, or MCP server calls that were not expected for the task type are signals worth investigating.

What is the biggest security mistake teams make with Claude Code?

Using the same high-permission API key across interactive developer sessions and automated CI/CD pipelines. Interactive sessions benefit from high permissions because a developer is in the loop to review actions.

Automated sessions should have the minimum permissions needed for the specific task. One compromised automated pipeline step should not have the same access as a senior developer’s full interactive session.

Security as a Design Constraint, Not an Afterthought

The eight practices above are most effective when they are part of the initial deployment design rather than retrofits applied after an incident. Teams that treat security as a design constraint for their Claude Code deployment avoid the cleanup work that follows from treating it as a compliance checkbox.

The risk table makes the prioritization clear: the highest-impact risks, secret exposure and compromised API keys, are also the most preventable with discipline and process.

Path one: implement the practices yourself. Start with Practices 1, 3, and 5 (secrets handling, review discipline, and key rotation). These address the highest-probability risks and require no infrastructure changes. Add the remaining practices as your deployment matures. For teams implementing authentication-gated workflows alongside Claude Code, the authentication implementation guide covers how to add those controls at the application layer.

Path two: work with Phos AI Labs. If you want the security framework designed for your specific environment, the audit logging integrated with your existing security tooling, and the permission model validated against your compliance requirements, that is implementation work we do with development teams. Start the conversation here.