Securing and using Claude Code at scale

#claude #claudecode #programming #ai

How to enforce policies in Claude Code from a security perspective

A common take from security folks at conferences is that 'security lives in CLAUDE.md' Unfortunately, that has nothing to do with how Claude Code actually enforces policy.

If you're rolling out Claude Code across a company, CLAUDE.md is not your security layer. It's behavioral guidance — Claude reads it and tries to follow it. The thing that actually enforces is managed settings: a JSON file the Claude Code client honors regardless of what your devs put in their project or user settings.

Where it goes

Platform	Location
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json` (or the `com.anthropic.claudecode` plist domain via MDM)
Linux / WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json` (the legacy `C:\ProgramData\ClaudeCode\` path was deprecated in v2.1.2 and is no longer supported as of v2.1.75)
Windows (registry)	`HKLM\SOFTWARE\Policies\ClaudeCode` → `Settings` value (`REG_SZ` or `REG_EXPAND_SZ`) containing JSON

Precedence inside the managed tier, highest to lowest:

server-managed (Claude.ai admin console)
  → endpoint-managed via MDM / OS-level policies (plist, HKLM)
    → file-based (managed-settings.json + managed-settings.d/*.json)
      → HKCU registry (Windows only, lowest managed priority)

Only one source within the managed tier wins — sources do not merge across the managed sub-tiers (it's first-source-wins: the moment a higher-priority source delivers a non-empty configuration, lower ones are ignored entirely).

However, array values like permissions.deny do merge across all settings scopes (managed + project + user + local), concatenated and deduplicated. So a managed deny list is a floor, not a ceiling.

For multi-team policy ownership (security team owns one slice, platform team owns another), drop fragments into managed-settings.d/ next to the base file. They merge in the systemd/sudoers drop-in style: alphabetical, scalars override, arrays concat, objects deep-merge.

Minimum-viable baseline

You can hand-write it or use a generator

Managed Settings generator (third-party, not affiliated with Anthropic — review output before deploying)

Here's the minimum-viable baseline I'd ship via Jamf, Intune, Group Policy, or Ansible or just use it locally.

{
  "$schema": "https://schemas.anthropic.com/claude-code/settings.json",

  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "YOUR-ORG-UUID-HERE",
  "minimumVersion": "2.1.75",
  "forceRemoteSettingsRefresh": true,

  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/credentials)",
      "Read(~/.aws/config)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(//etc/passwd)",
      "Read(//etc/shadow)",
      "WebFetch",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ],
    "ask": ["Write(**)", "Edit(**)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "disableAutoMode": "disable",

  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "github.com",
        "*.githubusercontent.com",
        "registry.npmjs.org",
        "pypi.org",
        "*.pythonhosted.org"
      ],
      "allowManagedDomainsOnly": true
    }
  },

  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverName": "github" }
  ],
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/claude-plugins" }
  ],
  "disableSkillShellExecution": true,

  "wslInheritsWindowsSettings": true,
  "cleanupPeriodDays": 7,

  "companyAnnouncements": [
    "Claude Code is governed by org policy. Report issues to #devops."
  ]
}

Note on Bash rule syntax: the documented specifier form uses a colon — Bash(curl:*), Bash(wget:*), Bash(sudo:*). The space form (Bash(curl *)) is also commonly seen in older examples and may still match, but prefer the colon form for new policies.

What each block actually does

Identity lock. forceLoginMethod + forceLoginOrgUUID prevent a dev from signing in with a personal Claude.ai account on a corp machine. This is the single highest-leverage anti-data-leak control. Without it, the rest is theatre.

Version floor. minimumVersion blocks the CLI from running below the specified version. forceRemoteSettingsRefresh: true (added in v2.1.92) makes the CLI fail closed at startup if it can't pull fresh server-managed policy — the CLI exits rather than proceeding without enforcement.

Permission rules. Use Tool(specifier) syntax — Read(...), Write(...), Edit(...), Bash(...), WebFetch. Single-slash paths are project-relative; double-slash (//etc/passwd) is absolute; ~/ is home. allowManagedPermissionRulesOnly: true causes Claude Code to ignore permission rules from user, project, and local settings, plus CLI arguments — only managed rules apply.

Caveat on Bash denies. Bash(curl:*) is a textual match against the command. Claude can route around a single-binary deny by using wget, python -c "import urllib...", nc, or shell tricks. Treat Bash denies as a soft layer; the real network control is sandbox.network.allowedDomains + allowManagedDomainsOnly.

Sandbox. This is the OS-level boundary (macOS Seatbelt, Linux/WSL2 bubblewrap), not a behavioral request. failIfUnavailable: true turns it into a hard gate — the CLI exits if sandboxing can't start. allowUnsandboxedCommands: false removes the dangerouslyDisableSandbox per-command escape hatch.

Known limitation: sandbox network allowlists operate at the system-call level (intercepting libc DNS resolution). Tools that use their own resolver path — notably some Node.js processes via libuv — can fail to resolve even allowed domains. Test your toolchain against the allowlist before committing.

Bypass and auto mode. disableBypassPermissionsMode: "disable" kills --dangerously-skip-permissions. disableAutoMode: "disable" removes auto mode from the Shift+Tab cycle and rejects --permission-mode auto.

Hooks, MCP, plugins. Three independent extensibility surfaces, three independent allowlists:

allowManagedHooksOnly — blocks user/project hooks; only managed hooks and hooks from plugins force-enabled in managed enabledPlugins will run.
allowManagedMcpServersOnly + allowedMcpServers — locks MCP servers to a vetted list. Without this, any .mcp.json in any repo can connect to anything.
strictKnownMarketplaces — plugin marketplace allowlist, enforced before network or filesystem ops. Use [] for full lockdown.

Skills. disableSkillShellExecution: true blocks inline !`...` shell execution in skills loaded from user, project, plugin, and additional-directory sources. Managed and bundled skills are exempt. Personally I'd leave this off unless you have a specific threat model that requires it.

WSL inheritance. wslInheritsWindowsSettings: true (added in v2.1.118; only honored when set in HKLM or C:\Program Files\ClaudeCode\managed-settings.json) makes WSL Claude Code read the Windows policy chain in addition to /etc/claude-code. Critical if your devs work in WSL.

CLAUDE.md is not in this file for a reason

Managed CLAUDE.md exists too (/Library/Application Support/ClaudeCode/CLAUDE.md, /etc/claude-code/CLAUDE.md, C:\Program Files\ClaudeCode\CLAUDE.md), and unlike user/project memory files, it cannot be excluded by claudeMdExcludes.

⚠️ Verify against current docs: earlier write-ups described CLAUDE.md as being injected as a user message after the system prompt with no strict-compliance guarantee. The exact delivery mechanism may have changed across versions. The takeaway that matters either way: CLAUDE.md is guidance the model interprets, not a hard control.

Use managed CLAUDE.md for behavioral guidance: coding standards, "always cite the internal style guide," compliance reminders. Use managed settings for technical enforcement: tool denies, sandbox, login lock, MCP allowlist.

If you write "never read .env files" in a managed CLAUDE.md, Claude will usually obey. If you put Read(./.env) in permissions.deny, the client physically refuses. Pick the right tool.

Verify it landed

On any dev machine, run /status inside Claude Code. It lists each active settings source with its origin — Enterprise managed settings (HKLM), Enterprise managed settings (file), Enterprise managed settings (remote), Enterprise managed settings (plist), etc. If your managed file has a syntax error, /status reports it.

For deeper debugging of which CLAUDE.md / rules / settings actually loaded, the InstructionsLoaded hook logs every instruction file at load time.

That's the baseline. Tighten it for your threat model: scope allowedDomains to your internal package mirror, lock availableModels to a Bedrock inference profile if you're routing through your own AWS account, add env blocks for OTEL_* variables to ship telemetry to your stack.

How to set up behaviors in Claude Code from a dev perspective

First, I'd enable forked subagents and agent teams by setting these environment variables:

CLAUDE_CODE_FORK_SUBAGENT=1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Heads-up on cost: fork mode lets parallel children share the parent's prompt cache prefix (which can dramatically reduce input token cost for children 2..N), but agent teams running in parallel still multiply overall token consumption. Be careful when adding agents in /agents.

This lets you run teams of agents and parallelize work where possible.

Next, focus on CLAUDE.md. The most specific CLAUDE.md takes precedence — yours can be sharper than the default. Example:

# prompts

Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.

My engineering preferences (use these to guide your recommendations):

- DRY is important — flag repetition aggressively.
- Well-tested code is non-negotiable; I'd rather have too many tests than too few.
- I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
- I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
- Bias toward explicit over clever.

## 1. Architecture review

Evaluate:

- Overall system design and component boundaries.
- Dependency graph and coupling concerns.
- Data flow patterns and potential bottlenecks.
- Scaling characteristics and single points of failure.
- Security architecture (auth, data access, API boundaries).

## 2. Code quality review

Evaluate:

- Code organization and module structure.
- DRY violations — be aggressive here.
- Error handling patterns and missing edge cases (call these out explicitly).
- Technical debt hotspots.
- Areas that are over-engineered or under-engineered relative to my preferences.

## 3. Test review

Evaluate:

- Test coverage gaps (unit, integration, e2e).
- Test quality and assertion strength.
- Missing edge case coverage — be thorough.
- Untested failure modes and error paths.

## 4. Performance review

Evaluate:

- N+1 queries and database access patterns.
- Memory-usage concerns.
- Caching opportunities.
- Slow or high-complexity code paths.

## For each issue you find

For every specific issue (bug, smell, design concern, or risk):

- Describe the problem concretely, with file and line references.
- Present 2–3 options, including "do nothing" where that's reasonable.
- For each option, specify: implementation effort, risk, impact on other code, and maintenance burden.
- Give me your recommended option and why, mapped to my preferences above.
- Then explicitly ask whether I agree or want to choose a different direction before proceeding.

## Workflow and interaction

- Do not assume my priorities on timeline or scale.
- After each section, pause and ask for my feedback before moving on.

## BEFORE YOU START

Ask if I want one of two options:

1. **BIG CHANGE:** Work through this interactively, one section at a time (Architecture → Code Quality → Tests → Performance), with at most 4 top issues in each section.
2. **SMALL CHANGE:** Work through interactively, ONE question per review section.

## FOR EACH STAGE OF REVIEW

Output the explanation, the pros and cons of each stage's questions, AND your opinionated recommendation and why, as `AskUserQuestion`. Also NUMBER issues and use LETTERS for options. When using `AskUserQuestion`, make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. The recommended option should always be the 1st option.

The general guidance: don't put a lot in CLAUDE.md — it's there to guide behavior. For specific, modular capability components, use skills. Or shorter:

SKILL.md = specific, modular capability components
CLAUDE.md = high-level behavioral and workflow guidance

I use skills for specific tasks and requirements - finops with specific tool, security reviews with specific tools, everything that could be described as process or workflow could be injected to the context via the skill