How to Audit a Repo's Coding Agent Config for Backdoors (2026)

Nov 18, 2026 · 11 min · Ajay Kumar

This guide is for anyone whose developers or CI jobs run a coding agent inside repositories they did not write every line of. That covers internal monorepos, vendored code, open-source dependencies and pull requests from forks. At the end you will have a script that lists everything a repository can make Claude Code execute, a CI gate that fails when those files change without review, the right flags for running claude -p on code you do not trust, and managed settings that stop project files from running commands at all.

Why now: on 17 November 2026 Google's threat intelligence group reported a suspected DPRK cluster that modified .claude/settings.json files in internal repositories. Starting Claude Code then "automatically triggered" the download of a backdoor. My news write-up has the rest of that report. No vulnerability was involved. The settings file runs commands by design, and the attacker already had push access.

Everything below was tested on 18 November 2026 with Claude Code 2.1.327 (the current npm release), jq 1.7.1 and macOS bash 3.2. I used an isolated CLAUDE_CONFIG_DIR and a dummy API key, so no request reached a model.

Step 1: Know what a repository can make the agent run

Claude Code reads .claude/settings.json (committed) and .claude/settings.local.json (normally gitignored) from the project, and .mcp.json from its root. The settings reference lists these keys as allowed in "any file", which includes a project file:

Key or file What it does Runs a command?
hooks Commands at lifecycle events, including SessionStart "when a session begins or resumes" Yes
apiKeyHelper, awsCredentialExport, awsAuthRefresh, gcpAuthRefresh, otelHeadersHelper Produce credentials or headers "with your own command" Yes
statusLine, fileSuggestion Render the status line or @ file suggestions from a command Yes
env Environment variables for the session and its subprocesses Changes what runs
.mcp.json mcpServers Local MCP servers are started as processes Yes
enableAllProjectMcpServers, enabledMcpjsonServers Approve .mcp.json servers without a prompt Approves them
permissions.allow Tool uses approved without asking Widens what the agent may do
extraKnownMarketplaces, enabledPlugins Register plugin sources and turn plugins on Pulls in more code

Then there is trust. The permissions page has a table called "What runs before you trust a folder". Its first row is hooks in settings files, the env block and helper commands such as apiKeyHelper. It marks them "Used" in a claude -p or SDK session, which never shows the trust dialog, and also when you trusted only a parent folder. For .mcp.json servers in a -p run it says "Connected without asking, approved or not." The security page is shorter: "A -p session shows neither prompt."

So the risky cases are CI jobs and scripts that run claude -p on a checkout, and developers who trusted a whole parent folder such as ~/src.

Step 2: Reproduce it safely

Make a throwaway repository whose hook and MCP server only write a marker file:

export LAB=$(mktemp -d)            # scratch directory
mkdir -p "$LAB/repo/.claude" "$LAB/markers" "$LAB/conf"
cd "$LAB/repo" && git init -q

cat > .claude/settings.json <<EOF
{ "hooks": { "SessionStart": [ { "hooks": [
  { "type": "command", "command": "echo sessionstart >> $LAB/markers/hook.txt" } ] } ] } }
EOF

cat > .mcp.json <<EOF
{ "mcpServers": { "fixture": { "command": "sh",
  "args": ["-c", "echo mcp >> $LAB/markers/mcp.txt; sleep 2"] } } }
EOF

# Isolated config and a fake key: nothing reaches a model or your real login
export CLAUDE_CONFIG_DIR="$LAB/conf" ANTHROPIC_API_KEY=sk-ant-api03-dummy
claude -p hi < /dev/null
ls "$LAB/markers"

What I got on 2.1.327, one run per row:

Run Project hook .mcp.json command apiKeyHelper
claude -p hi Ran Ran (started twice) Ran
claude -p hi --settings '{"disableAllHooks": true}' Blocked Ran not tested
claude -p hi --setting-sources user Blocked Blocked Blocked
claude -p hi --setting-sources user --strict-mcp-config Blocked Blocked not tested

Each run ended with "Invalid API key", so everything in the "Ran" cells happened before authentication failed. Two lessons follow. First, disableAllHooks is not enough on its own, because it leaves .mcp.json servers running. Second, --setting-sources user is the one flag that stopped everything here. For the apiKeyHelper row I used a second repository whose settings had apiKeyHelper plus an env block setting ANTHROPIC_BASE_URL to a local listener.

What I could not test: whether that ANTHROPIC_BASE_URL override is honoured. The run stopped at key validation before sending any request, so my listener saw nothing. I also did not drive the interactive trust dialog, and I did not install managed settings, which needs root.

Step 3: Scan repositories with a script

This script lists every executable or approval-widening entry in a repository's agent config. It exits 1 if it finds anything, so it works in CI. It also reads .cursor/mcp.json and .vscode/mcp.json, but I tested it only against Claude Code's files.

#!/usr/bin/env bash
# audit-agent-config.sh: list repository files that make a coding agent run commands.
# Usage: audit-agent-config.sh [repo-dir ...]   Exit 1 if anything is found.
set -euo pipefail
command -v jq >/dev/null || { echo "jq is required" >&2; exit 2; }
found=0
report() { found=1; printf '%s\t%s\t%s\n' "$1" "$2" "$3"; }

for repo in "${@:-.}"; do
  for f in "$repo/.claude/settings.json" "$repo/.claude/settings.local.json"; do
    [ -f "$f" ] || continue
    if ! jq empty "$f" 2>/dev/null; then report "$f" parse-error "not valid JSON, review by hand"; continue; fi
    while IFS=$'\t' read -r k v; do report "$f" "$k" "$v"; done < <(jq -r '
      ( .hooks // {} | to_entries[] | .key as $ev | .value[]? | .hooks[]?
        | "hook:\($ev)\t\(.type // "command"): \(.command // .url // .prompt // "" )" ),
      ( ["apiKeyHelper","awsCredentialExport","awsAuthRefresh","gcpAuthRefresh","otelHeadersHelper"][] as $k
        | select(.[$k] != null) | "\($k)\t\(.[$k])" ),
      ( select(.statusLine.command != null) | "statusLine\t\(.statusLine.command)" ),
      ( select(.fileSuggestion != null) | "fileSuggestion\t\(.fileSuggestion | tostring)" ),
      ( .env // {} | to_entries[] | "env\t\(.key)=\(.value)" ),
      ( select(.enableAllProjectMcpServers == true) | "enableAllProjectMcpServers\ttrue" ),
      ( .enabledMcpjsonServers[]? | "enabledMcpjsonServers\t\(.)" ),
      ( .permissions.allow[]? | select(test("^Bash(\\(\\*?\\))?$|^Bash\\(.*\\*") ) | "permissions.allow\t\(.)" ),
      ( .extraKnownMarketplaces // {} | keys[] | "extraKnownMarketplaces\t\(.)" ),
      ( .enabledPlugins // {} | keys[] | "enabledPlugins\t\(.)" )
    ' "$f")
  done
  for f in "$repo/.mcp.json" "$repo/.cursor/mcp.json" "$repo/.vscode/mcp.json"; do
    [ -f "$f" ] || continue
    while IFS=$'\t' read -r k v; do report "$f" "$k" "$v"; done < <(jq -r '(.mcpServers // .servers // {}) | to_entries[]
      | "mcp:\(.key)\t\(if .value.command then "\(.value.command) \(.value.args // [] | join(" "))" else (.value.url // "?") end)"' "$f" 2>/dev/null)
  done
  if [ -d "$repo/.claude" ]; then
    while read -r f; do report "$f" frontmatter "hooks or mcpServers in frontmatter"; done \
      < <(grep -rlE '^(hooks|mcpServers):' "$repo/.claude/agents" "$repo/.claude/skills" 2>/dev/null || true)
  fi
done
[ "$found" = 0 ] && echo "no executable agent configuration found" >&2
exit "$found"

I ran it against five fixture repositories:

Fixture Output Exit
Hook plus .mcp.json from Step 2 hook:SessionStart and mcp:fixture lines 1
apiKeyHelper plus env apiKeyHelper and env ANTHROPIC_BASE_URL=... 1
statusLine, Bash(*) allow, a plugin and a subagent with frontmatter hooks five lines, Bash(npm test) correctly not flagged 1
Truncated JSON parse-error 1
Only a deny rule "no executable agent configuration found" 0

My first version piped jq into while read, which runs the loop in a subshell. It printed findings and still exited 0. The process substitution above fixes that, so keep it if you edit the script.

To sweep many repositories, clone them shallowly and pass them all: audit-agent-config.sh repos/*. A finding is not a verdict. Most hooks are linters and formatters. You are looking for downloads (curl, wget, iwr), base64, writes outside the repo, and anything added by someone who does not normally touch that file.

Step 4: Gate changes in review and CI

Make these paths need a code owner. In .github/CODEOWNERS:

/.claude/        @your-org/platform-security
/.mcp.json       @your-org/platform-security
/.cursor/        @your-org/platform-security
/.vscode/mcp.json @your-org/platform-security

Turn on "Require review from Code Owners" in the branch protection rule or ruleset. That catches the MIDNIGHT NEPTUNE pattern only if the attacker cannot push to the default branch directly, so check who can bypass the ruleset too.

Then fail CI when a pull request touches them. I have not run this workflow; it uses only git and the script above:

# .github/workflows/agent-config.yml
on: pull_request
permissions: { contents: read }
jobs:
  agent-config:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0, persist-credentials: false }
      - run: |
          if git diff --name-only "origin/${GITHUB_BASE_REF}...HEAD" \
             | grep -E '^(\.claude/|\.mcp\.json$|\.cursor/|\.vscode/mcp\.json$)'; then
            ./tools/audit-agent-config.sh . || true
            echo "::error::Agent config changed. Needs platform-security review."
            exit 1
          fi

Step 5: Run claude -p on untrusted code safely

In CI, in scripts, and anywhere a checkout comes from a fork or a third party, pass --setting-sources user. Then Claude Code reads neither the project's settings nor its .mcp.json. Put the configuration you want in the runner's user settings or pass it with --settings:

claude -p "review this diff" \
  --setting-sources user \
  --strict-mcp-config \
  --settings ./ci/claude-settings.json < /dev/null

--strict-mcp-config makes Claude Code use only the MCP config you pass explicitly. It was not needed in my test once --setting-sources user was set, but it costs nothing. Do not rely on --settings '{"disableAllHooks": true}' alone: the .mcp.json server still started. For running the agent itself inside Actions, see how to run an AI coding agent in GitHub Actions safely.

Step 6: Lock it down with managed settings

For company laptops, a managed settings file overrides everything else. The managed settings page gives the paths: /Library/Application Support/ClaudeCode/managed-settings.json on macOS and /etc/claude-code/managed-settings.json on Linux and WSL.

{
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }
  ]
}

Per the hooks reference, with allowManagedHooksOnly "your user, project, local, and plugin hooks are blocked", and statusLine and fileSuggestion are narrowed to managed settings too. The managed MCP page says that with allowManagedMcpServersOnly, "allowlists from user, project, and local settings are ignored." Three details from that page matter. Match servers by serverUrl or serverCommand, because "a serverName entry, in either list, is not a security control." Always set the list, because with the lock on and no list "every server that passed the denylist loads." And [] means no servers at all. Test on one machine first. I did not install this file myself. If you use GitHub Copilot as well, its equivalent is strictPluginOnlyCustomization, covered in Copilot can now force MCP servers through plugins.

Finally, tell developers not to trust broad parent folders. Trusting ~/src means every repository cloned under it runs its hooks without a dialog.

Troubleshooting

Symptom Cause Fix
Script prints findings but exits 0 Loop running in a pipe subshell Use done < <(jq ...) as above
parse-error on a file Claude Code accepts Comments or trailing commas Review it by hand. Do not skip it
Hook still fires with disableAllHooks Managed hooks are not disabled from outside managed settings Remove them from the managed file, or accept them as policy
MCP server starts in -p despite no approval Documented -p behaviour --setting-sources user, plus --strict-mcp-config
"this workspace has not been trusted" on stderr Project permissions.allow ignored in an untrusted -p run Expected. Pass the rules with --settings instead
claude --version shows an old release A second install earlier on PATH (Homebrew and npm) which -a claude and remove the stale one

FAQ

Do Claude Code project hooks run without the trust dialog?

In a claude -p or SDK session, yes: the permissions docs mark project hooks, the env block and helper commands as used there, and I saw a SessionStart hook run. They also run when you have only trusted a parent folder. In an interactive session in a new folder, Claude Code shows the trust dialog first.

How do I stop a repository's .mcp.json from starting servers?

For scripted runs, pass --setting-sources user (and --strict-mcp-config). For a fleet, set allowManagedMcpServersOnly with an allowedMcpServers list in managed settings. A disabledMcpjsonServers entry in any settings file also rejects a named server.

Is the .claude/settings.json backdoor a Claude Code vulnerability?

No. In the case Google reported, the attacker already had access to internal repositories and edited a file that runs commands by design. The defences are review on those paths, safe flags in automation and managed settings, not a patch.

Related: How to Block Dangerous Commands With Claude Code Hooks, How to Write AGENTS.md and CLAUDE.md and Plugin4Shell.

Spot an error or something out of date? Email me and I will fix it and log it on the corrections page.

I'm Ajay Kumar — I build and operate PandaStack, an open-source Firecracker microVM cloud for AI agents, and write about the infrastructure and tooling around it.

Need this kind of infrastructure work? See what I do or email hello@ajayk.sh.


Related