managed-settings.jsonc

{
  // ============================================================
  // Enterprise Managed Settings (IT-deployed, root-owned)
  // ============================================================
  // Deploy at:
  //   Linux:   /etc/claude-code/managed-settings.json
  //   macOS:   /Library/Application Support/ClaudeCode/managed-settings.json
  //   Windows: C:\Program Files\ClaudeCode\managed-settings.json
  //   (Changed in v2.1.75 — the old C:\ProgramData path is no longer read)
  //
  // Directory-based deployment (v2.1.83+):
  //   Linux:   /etc/claude-code/managed-settings.d/*.json
  //   macOS:   /Library/Application Support/ClaudeCode/managed-settings.d/*.json
  //   Windows: C:\Program Files\ClaudeCode\managed-settings.d\*.json
  //
  // Files in managed-settings.d/ are merged alphabetically on top of the base
  // managed-settings.json. Useful for modular deployment (e.g., separate hook
  // config from deny rules via SSM/Puppet/Chef).
  //
  // Ownership: root:root 0644 (Linux/macOS) or Administrators:Full (Windows)
  // Users CANNOT modify this file.
  //
  // Schema version: 1.0
  // Last updated: 2026-05-28

  // --- Admin-only lockdowns [TESTED ✅] ---
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,

  // --- Sandbox (OS-level enforcement) [TESTED ✅ on Linux] ---
  // [NOTE] Sandbox not supported on native Windows — use sandbox.failIfUnavailable
  // to force WSL2, or omit the sandbox block in Windows managed settings.
  "sandbox": {
    "enabled": true,
    // [SECURITY-CRITICAL] In versions before v2.1.78, a bug (CVE-level severity)
    // allowed the sandbox to be silently disabled when bubblewrap was missing.
    // With failIfUnavailable: true, Claude Code refuses to start rather than
    // running unsandboxed. Always set this to true in enterprise deployments.
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "allowWrite": ["./"],
      "denyRead": [
        "~/.aws/credentials",
        "~/.aws/config",
        "~/.ssh/",
        "~/.gnupg/",
        "~/.netrc",
        "~/.git-credentials"
      ],
      "allowManagedReadPathsOnly": true
    },
    "network": {
      "allowedDomains": [
        "bedrock-runtime.*.amazonaws.com",
        "*.bedrock-runtime.*.vpce.amazonaws.com"
        // Add your enterprise domains here:
        // "*.internal.yourcompany.com",
        // "registry.npmjs.org",
        // "pypi.org"
      ],
      "deniedDomains": [
        "github.com",
        "gitlab.com",
        "bitbucket.org",
        "pastebin.com",
        "transfer.sh",
        "file.io"
      ],
      "allowManagedDomainsOnly": true
    }
  },

  // --- Permission controls (FULL deny list — replicated from user settings) ---
  // Placing deny rules here makes them un-removable by users when
  // allowManagedPermissionRulesOnly: true is set above.
  "permissions": {
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable",
    "deny": [
      // --- Destructive filesystem ---
      "Bash(rm -rf:*)",
      "Bash(rm -fr:*)",
      "Bash(dd:*)",
      "Bash(mkfs:*)",
      "Bash(shutdown:*)",
      "Bash(reboot:*)",

      // --- Git (push handled by git-guard.sh hook for fine-grained control) ---
      "Bash(git push:*)",                  // baseline: hook adds branch/remote allowlist
      "Bash(git reset --hard:*)",          // backup: hook also catches this

      // --- Network exfiltration ---
      "Bash(curl:*)",
      "Bash(wget:*)",

      // --- Privilege escalation ---
      "Bash(sudo:*)",
      "Bash(su:*)",

      // --- Sensitive AWS operations ---
      "Bash(aws iam:*)",
      "Bash(aws sts:*)",
      "Bash(aws secretsmanager:*)",

      // --- Sensitive file reads (gitignore-style) ---
      "Read(**/.aws/credentials)",
      "Read(**/.aws/config)",
      "Read(**/.ssh/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/id_rsa*)",
      "Read(**/.netrc)",
      "Read(**/.git-credentials)",
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/secrets.yaml)",
      "Read(**/secrets.yml)",
      "Read(**/secrets.json)",
      "Read(**/credentials.json)",

      // --- Web tools ---
      "WebFetch",
      "WebSearch"
    ]
  },

  // --- Feature restrictions ---
  // [UNVERIFIED on headless Linux — re-test on actual workstation deployment]
  "disableRemoteControl": true,
  "disableAgentView": true,
  "disableDeepLinkRegistration": true,

  // --- MCP lockdown ---
  "allowedMcpServers": [],
  "deniedMcpServers": ["*"],

  // --- Plugin / Marketplace controls (v2.1.130+) ---
  // [ACTION REQUIRED] Uncomment the lines below to enforce plugin marketplace blocking.
  // Blocks installation of plugins from untrusted sources.
  // "blockedMarketplaces": ["*"],          // deny all marketplace installs
  // "strictKnownMarketplaces": true,       // only allow vetted marketplace sources

  // --- Hooks (audit + policy enforcement) ---
  // ALL five hooks are deployed:
  //   1. git-guard.sh      — enterprise git policy (allowlist, branch protection)
  //   2. gh-guard.sh       — the same writes without git: gh CLI, gh api,
  //                          curl/wget straight to the REST API
  //   3. mcp-repo-guard.sh — repo writes from MCP servers. NOTE the separate
  //                          "mcp__.*" matcher block below: a hook registered
  //                          under "Bash" is never invoked for an MCP call, so
  //                          omitting that block leaves the path unguarded
  //                          (docs/known-issues.md Issue 13).
  //   4. pii-guard.sh      — PII/secrets scanner (UserPromptSubmit + PreToolUse)
  //   5. audit-logger.sh   — append-only audit log (PostToolUse + UserPromptSubmit)
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/pii-guard.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/git-guard.sh"
          },
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/gh-guard.sh"
          },
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/pii-guard.sh"
          }
        ]
      },
      {
        // MCP tool calls carry no "command" field and never match "Bash".
        // This entry is what makes the MCP write path enforceable.
        "matcher": "mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/mcp-repo-guard.sh"
          },
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/pii-guard.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/etc/claude-code/hooks/audit-logger.sh"
          }
        ]
      }
    ],
    // --- Session lifecycle hooks (for audit completeness) ---
    // SessionStart and SessionEnd fire at session boundaries.
    // Useful for login/logout auditing and resource tracking.
    // "SessionStart": [
    //   {
    //     "hooks": [
    //       {
    //         "type": "command",
    //         "command": "/usr/local/etc/claude-code/hooks/audit-logger.sh"
    //       }
    //     ]
    //   }
    // ],
    // "SessionEnd": [
    //   {
    //     "hooks": [
    //       {
    //         "type": "command",
    //         "command": "/usr/local/etc/claude-code/hooks/audit-logger.sh"
    //       }
    //     ]
    //   }
    // ]
  },

  // --- Environment variables ---
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    // Note: DISABLE_UPDATES blocks the `claude update` command.
    // DISABLE_AUTOUPDATER (v2.1.118+) separately blocks background auto-update checks.
    // Set both for complete update control in enterprise:
    "DISABLE_UPDATES": "1",
    "DISABLE_AUTOUPDATER": "1",
    // Scope: blocks telemetry, update checks, marketplace browsing,
    // and any non-essential outbound network connections.
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "BASH_DEFAULT_TIMEOUT_MS": "30000",
    "BASH_MAX_TIMEOUT_MS": "120000",

    // Bedrock service tier (v2.1.122+) — controls priority/throughput tier
    // "ANTHROPIC_BEDROCK_SERVICE_TIER": "standard",

    // Model alias control (override which model resolves for "sonnet" / "opus"):
    // "ANTHROPIC_DEFAULT_SONNET_MODEL": "us.anthropic.claude-sonnet-4-6",
    // "ANTHROPIC_DEFAULT_OPUS_MODEL": "us.anthropic.claude-opus-4-8",

    // AWS credential refresh for long-running sessions:
    // "awsCredentialExport": "/usr/local/bin/refresh-aws-creds.sh",  // v1.0.53+
    // "awsAuthRefresh": "/usr/local/bin/aws-auth-refresh.sh",        // v2.1.141+

    // git-guard configuration (customize per enterprise)
    "GIT_GUARD_ALLOWED_DOMAINS": "gitlab.yourcompany.com,*.internal.yourcompany.com",
    "GIT_GUARD_PROTECTED_BRANCHES": "main,master,release/*,production",
    "GIT_GUARD_ALLOW_FORCE_PUSH": "false",

    // audit-logger configuration
    "CLAUDE_AUDIT_LOG": "/var/log/claude-code/audit.jsonl",
    "CLAUDE_AUDIT_ALERT_CMD": "" // optional: webhook URL for SIEM
  }
}