cfgaudit
Security auditor for AI-agent configuration files.
cfgaudit scans the configuration of AI coding assistants — starting with Claude Code — and flags settings that violate the principle of least privilege or leave sensitive files exposed to the agent's context.
Every finding maps to an OWASP GenAI LLM Top 10 2026 risk (the primary mapping). Two secondary lenses are also provided: the OWASP MCP Top 10 for the MCP-server rules, and the OWASP AISVS 1.01 mapping for teams who verify against the AI Security Verification Standard. A behavioral crosswalk to AVE (Agentic Vulnerability Enumeration) maps the rules to AVE's behavioral classes. The primary OWASP LLM id and the mapped AVE id ride in the JSON and SARIF output (OWASP/AVEID in JSON; properties.owasp_llm/properties.ave_id in SARIF, alongside the CFG ruleId). The rule→AVE mapping lives in a single file (cmd/cfgaudit/avemap.go) with the crosswalk doc as its human-readable companion.
Install
Homebrew (macOS / Linux):
brew install cfgaudit/tap/cfgaudit
With the Go toolchain:
go install github.com/cfgaudit/cfgaudit/cmd/cfgaudit@latest
Or download a pre-built binary (Linux / macOS / Windows, amd64 / arm64) from the releases page.
Container image:
docker run --rm -v "$PWD:/work" -w /work ghcr.io/cfgaudit/cfgaudit:latest .
The image includes ShellCheck, so --shellcheck (CFG045) works there and in the GitHub Action and GitLab components, which run the same image.
The image runs unprivileged as uid 65532, so the files you mount must be readable by that uid (normal 644/755 permissions are fine). cfgaudit only reads them — write the report with a shell redirection on the host (> report.sarif) rather than into the mount.
Verifying a release
Every release is built by a GitHub Actions workflow that publishes build provenance, and the container image is additionally signed with cosign. Both are keyless — the signing identity is the workflow, so a verified artifact provably came from this repository's release pipeline.
From v1.17.0 on, the release archives and the container image meet SLSA Build Level 3: they are built in reusable workflows (build-release.yml, build-image.yml) that the tag-triggered workflows only call, so the build workflow signs the provenance. That is the isolation GitHub documents as SLSA v1 Build Level 3 for artifact attestations. Releases v1.8.0 to v1.16.0 meet Build Level 2: their provenance is signed by release.yml and docker.yml themselves. --signer-workflow below requires the build workflow; drop it for releases before v1.17.0.
Release archive — provenance for the archive you downloaded:
gh attestation verify cfgaudit_1.17.0_linux_amd64.tar.gz -R cfgaudit/cfgaudit \
--signer-workflow cfgaudit/cfgaudit/.github/workflows/build-release.yml
checksums.txt — verify this too if you check downloads against it (the plugin wrapper in bin/cfgaudit does):
gh attestation verify checksums.txt -R cfgaudit/cfgaudit \
--signer-workflow cfgaudit/cfgaudit/.github/workflows/build-release.yml
Container image — provenance and signature, both bound to the image digest rather than a tag, since a tag can be repointed later:
DIGEST=$(docker buildx imagetools inspect ghcr.io/cfgaudit/cfgaudit:latest --format '{{.Manifest.Digest}}')
gh attestation verify "oci://ghcr.io/cfgaudit/cfgaudit@$DIGEST" -R cfgaudit/cfgaudit \
--signer-workflow cfgaudit/cfgaudit/.github/workflows/build-image.yml
cosign verify "ghcr.io/cfgaudit/cfgaudit@$DIGEST" \
--certificate-identity-regexp '^https://github.com/cfgaudit/cfgaudit/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
Attestations and the image signature are published from v1.8.0 onward, the first release built by the signing pipeline; checksums.txt is covered from the same release.
Without the GitHub API: from v1.8.0 onward, the same attestation is also attached to each release as two assets: cfgaudit_<version>.sigstore.json, the Sigstore bundle with the signature, signing certificate and transparency log entry, and cfgaudit_<version>.intoto.jsonl, the signed SLSA provenance on its own. One bundle covers all six archives and checksums.txt. Verify a download against it with cosign:
VERSION=<version> # e.g. the release you downloaded, without the leading v
cosign verify-blob-attestation \
--bundle "cfgaudit_${VERSION}.sigstore.json" \
--type slsaprovenance1 \
--certificate-identity-regexp '^https://github\.com/cfgaudit/cfgaudit/\.github/workflows/(build-)?release\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"cfgaudit_${VERSION}_linux_amd64.tar.gz"
The identity pins the signer to this repository's release workflow running on a tag, so a bundle signed by any other workflow or repository fails, as does a file whose digest is not in the provenance. The regex accepts release.yml, which signed releases before v1.17.0, and build-release.yml, which signs them from v1.17.0 on; use only the latter to require Build Level 3.
Rebuilding a release: the binaries are reproducible. Building the tag with the Go version recorded in the release binary and the release flags gives a byte-identical binary, so you can check a download without trusting the pipeline at all. For example, for the Linux amd64 binary of v1.17.1:
go version -m cfgaudit | head -1 # the Go version the release used, e.g. go1.24.13
git clone --branch v1.17.1 https://github.com/cfgaudit/cfgaudit.git cfgaudit-src && cd cfgaudit-src
GOTOOLCHAIN=go1.24.13 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -trimpath -ldflags "-s -w -X main.cfgauditVersion=1.17.1" -o cfgaudit-rebuilt ./cmd/cfgaudit
sha256sum cfgaudit-rebuilt ../cfgaudit # the binary from the release archive
Build from a fresh clone of the tag: Go records the commit and whether the working tree is clean in the binary, so a modified checkout or a git worktree gives a different hash.
A note on SBOMs
The container image carries its SBOM as a signed attestation. The per-archive .sbom.json files, by contrast, are published as plain release assets, not attestations — deliberately.
Each one lists cfgaudit itself, its two dependencies (gopkg.in/yaml.v3, github.com/BurntSushi/toml), the Go standard library, and the archive's own digest. That is the same information go.mod already makes public, and the archive it describes is covered by provenance — so a swapped SBOM cannot make a tampered archive verify. If you need an SBOM you can trust end to end, use the image attestation, or regenerate one from a verified archive with syft.
Usage
# Audit the current directory
cfgaudit
# Audit a specific project root
cfgaudit /path/to/project
# Output format defaults to "auto": a table on an interactive terminal, plain
# text when piped or redirected. Force either with --format table / --format text.
cfgaudit --format table
# Text and table output colour the severity and rule ID on a terminal. Turn it
# off with --no-color or NO_COLOR, or on in a CI log with FORCE_COLOR=1. JSON,
# SARIF and Code Climate are never coloured.
cfgaudit --no-color
# Output as JSON (for CI integration)
cfgaudit --format json
# Output as SARIF 2.1.0 (for GitHub Code Scanning)
cfgaudit --format sarif > cfgaudit.sarif
# Output as Code Climate JSON (for GitLab Code Quality / merge-request findings)
cfgaudit --format codeclimate > gl-code-quality.json
# A finding in a JSON or JSONC file carries the line of the key it reports, so
# GitHub and GitLab show it on the changed line of a pull or merge request. A
# missing key points at its parent, or the finding has no line. TOML and YAML
# findings have no line yet.
# Override the Claude Code version used for rule gating (otherwise detected via `claude --version`)
cfgaudit --claude-version 2.1.148
# Print cfgaudit version and exit
cfgaudit --version
# Run only specific rules (CSV or repeated; --only and --skip can be combined)
cfgaudit --only CFG001,CFG003
cfgaudit --only CFG001 --only CFG003
cfgaudit --skip CFG006,CFG009
# Use an explicit config file (otherwise .cfgaudit.yml is auto-discovered)
cfgaudit --config path/to/.cfgaudit.yml
# Also scan a Claude Code plugin/skill package
cfgaudit --plugins ./my-plugin
# Zero-tolerance CI: make warn findings fail the build too
cfgaudit --strict
# Deeper shell analysis of hook commands (CFG045, needs the shellcheck binary)
cfgaudit --shellcheck
# Also scan docs that agents read while they work, with the high-precision content rules
cfgaudit --content-paths 'README.md,CONTRIBUTING.md,docs/**/*.md'
# Explain a rule in the terminal (renders its docs)
cfgaudit explain CFG001
# List all rules (filter by OWASP — LLM or MCP — or output JSON)
cfgaudit list
cfgaudit list --owasp LLM03
cfgaudit list --owasp MCP05
cfgaudit list --format json
# Scaffold a hardened .claude/settings.json for a new project
cfgaudit init # write a safe-default deny list (profile: standard)
cfgaudit init --profile minimal # credential reads only
cfgaudit init --profile paranoid # + environment runners, shell interpreters, PowerShell
cfgaudit init --dry-run # print the JSON without writing
cfgaudit init --interactive # add project-specific deny entries
# Sync deny rules between settings.json and .cfgaudit.yml policy
cfgaudit policy generate # settings.json permissions.deny -> .cfgaudit.yml require-deny
cfgaudit policy apply --dry-run # preview: .cfgaudit.yml require-deny -> settings.json permissions.deny
cfgaudit policy apply # write the missing deny entries
init subcommand — scaffolds .claude/settings.json with a hardened permissions.deny so a fresh project starts safe-by-default and passes the policy rules (CFG006/CFG041–CFG044) immediately. Aborts if the file exists (use --force, or cfgaudit policy apply to merge); --dry-run prints the JSON; --interactive adds project-specific entries.
--profile picks how much it writes. Each profile is a superset of the one before it, and every one of them produces a file that scans clean across all rules:
The runners are in paranoid rather than standard because they get in the way, not because they matter less. Claude Code strips a fixed set of wrappers before matching a Bash rule but not these, and upstream states the consequence: "a rule like Bash(devbox run *) matches whatever comes after run, including devbox run rm -rf .". So every command-class entry in standard has a documented bypass through them. PowerShell is likewise a separate tool with its own rules, so nothing in the Bash entries applies to it on Windows.
What a deny list can and cannot do. The two halves are not equally strong, and it is worth saying so rather than presenting the file as a boundary:
- Path rules hold.
Read/Editpatterns are matched against the resolved path, symlinks included. Their one trap is the anchor: a bare**/pattern is anchored at the working directory, soRead(**/.ssh/**)in a project file leaves~/.sshreadable. The baseline uses the//filesystem-root anchor for every location-named entry for exactly this reason (CFG044 carries the measurement). - Removing a whole tool holds. A bare
"Bash"deny entry takes the tool out of the model's context entirely. - Argument-constrained Bash rules are guidance. Matching is a literal prefix, so a reordered or inserted flag walks past a rule that names specific flags. That is why the baseline denies
rmby name rather thanrm -rf, and why the force-push entries carry four spellings and still are not airtight. Upstream calls these patterns "fragile" and points at OS-level sandboxing andPreToolUsehooks for the part a pattern cannot enforce.
Compound commands are not a bypass, contrary to a claim that circulates: with Bash(touch *) denied, touch f && echo ok && ls was blocked in full on 2.1.231. A rule must match each subcommand independently, and a deny on any one of them blocks the call.
policy subcommand — keeps permissions.deny (enforced by Claude Code) and policy.require-deny (audited by cfgaudit / CFG025) in sync. generate freezes the current runtime deny list as an auditable policy, preserving the rest of your .cfgaudit.yml (comments included). apply rolls a policy out to a project's settings; both merge additively (nothing is removed) and are idempotent. apply rewrites settings.json as 2-space-indented JSON with alphabetically-ordered top-level keys — run --dry-run first to preview.
Zed .zed/settings.json command sites
Four fields of Zed's ProjectSettingsContent name something the editor launches, and cfgaudit reads all four from a committed file: context_servers (through the MCP rules) plus terminal.shell, lsp.<name>.binary and dap.<name>, whose program, argv and env ride the command-content family the way .zed/tasks.json does.
Two distinctions keep this honest:
- This file is worktree-trust gated, unlike
.zed/tasks.json. The findings say "runs on worktree trust" rather than implying zero-click. They are reported anyway on the footing that already applies tocontext_serversin the same file: trust is one prompt covering the whole worktree, granted for any Zed functionality at all, not consent to a specific binary. - Only a shell's arguments are shell text.
lsp.binary.argumentsanddap.argsgo toexecve, so a$VARor$(…)there is literal bytes. cfgaudit passes the full line to the content rules only when the program is an interpreter (sh,bash,pwsh, …), and the program alone otherwise. Without that split, a real config passing${projectRoot}#python-lsptonix runreported an interpolation that cannot happen.
.zed/debug.json is the third committed project file next to settings.json and tasks.json, and cfgaudit reads one field of it. Upstream: "Zed will use the build field to run any necessary setup steps before the debugger starts", and "Zed allows embedding a Zed task in the build field that is run before the debugger starts". So pressing Debug on a scenario labelled "Debug server" runs whatever that field names, under a label that describes the session rather than the command. program, args and env are not read: they name the binary the user asked to debug, which is the thing they picked, the same line .zed/tasks.json draws between a create_worktree hook task and one invoked from the task list. A build that names an existing task by label is resolved against .zed/tasks.json and the finding is attributed to that file, since that is where the command lives. Unlike settings.json, debug.json is applied without a worktree trust check: update_settings in crates/project/src/project_settings.rs routes only LocalSettingsKind::Settings through can_trust, while Tasks and Debug go straight to the task store (#650).
Scope-aware findings
Each finding carries a Scope (project, project-local, or user) reflecting which file it came from. Rules whose blast radius is amplified when the misconfiguration lives in user-global settings append an explanatory note to the message, and CFG009 (hook command interpolates a shell variable) escalates from warn to error at user scope — a malicious hook in ~/.claude/settings.json fires on every project the user opens.
Version gating
Some rules require a minimum Claude Code release before they make sense. cfgaudit runs claude --version once per invocation, compares the result to each rule's MinVersion, and replaces below-threshold rules with a single info-severity skip notice. The detected version is logged to stderr at the start of each scan; the --claude-version flag overrides detection (useful in CI containers where the binary is not installed). When neither detection nor the flag yields a version, every rule runs unconditionally.
Exit codes
Suppressing a finding
Suppression lives in .cfgaudit.yml (below), not in the scanned files: turn a rule off for the project with rules: { CFG001: off }, or drop every finding in a file or directory with exclude-paths. There is no inline suppression comment, so a scanned file cannot hide its own findings. Since a repository's own .cfgaudit.yml can do both, see scanning a repository you do not trust.
Configuration file (.cfgaudit.yml)
cfgaudit auto-discovers a .cfgaudit.yml (or .cfgaudit.yaml) in the scanned directory; --config <path> overrides discovery. CLI flags take precedence over the file.
Scanning a repository you do not trust. The discovered file belongs to the repository being scanned, and it decides which rules run and whether findings fail the exit code. A hostile repository can ship one that turns the relevant rules off or sets no-exit-codes: true; cfgaudit only names the file it uses on stderr. When you audit a repository before trusting it, such as a fresh clone before you open it with an agent, do not let it configure its own audit:
cfgaudit --config /dev/null path/to/repo # an empty config; use NUL on Windows
In CI the same applies to changes from people you do not fully trust. Both the GitHub Action and the GitLab components take a config that the change cannot edit. That protects the scan as far as the pipeline definition is not part of the change too: a pull request that can edit .cfgaudit.yml can usually edit the workflow, so review changes to either like code, and use required workflows or protected pipeline configuration where the scan must hold against the change itself.
# Per-rule overrides
rules:
CFG003: off # disable a rule (flat form)
CFG004:
severity: warn # override a rule's severity (also accepts the flat form CFG004: warn)
# Drop findings below this severity ("error", "warn", "info")
min-severity: warn
# Treat warn findings as errors for the exit code
strict: false
# Always exit 0 on a successful run (advisory mode for non-blocking CI)
no-exit-codes: false
# Run shellcheck on hook/helper commands (CFG045; needs the shellcheck binary)
shellcheck: false
# ShellCheck codes CFG045 never reports (with or without the SC prefix)
shellcheck-exclude: [SC2086]
# Files that are not agent instruction files but that agents read while they
# work. Off by default. Only the rules for text with no place in any Markdown
# file run on them (CFG024, CFG032, CFG057, CFG080), and they report warn at most.
content-paths:
- README.md
- docs/**/*.md
# Path globs (relative to the scanned dir) whose findings are excluded.
# Supports *, ** and a trailing / for directory prefixes.
exclude-paths:
- vendor/
- "**/.claude/settings.local.json"
# Org policy (CFG025): commands that must be denied / must not be allowed.
# Matching is containment-aware (Bash(git:*) covers Bash(git commit:*)).
policy:
require-deny:
- "Bash(git commit:*)" # must be covered by permissions.deny
forbid-allow:
- "Bash(git commit:*)" # must not be grantable by permissions.allow
GitHub Action
Run cfgaudit in a workflow without installing anything — the action wraps the published container image:
- uses: cfgaudit/cfgaudit@v1
with:
path: .
Upload findings to GitHub Code Scanning via SARIF (add permissions: security-events: write to the job):
- uses: cfgaudit/cfgaudit@v1
with:
format: sarif
output: cfgaudit.sarif
fail-on: never # advisory: let Code Scanning surface findings, don't fail the step
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: cfgaudit.sarif
For pull requests, take the config from the base branch so the change cannot rewrite it (why). A path outside the workspace, such as one under $RUNNER_TEMP, is mounted read-only into the scan:
- name: cfgaudit config from the base branch
env:
BASE_REF: ${{ github.base_ref }}
run: |
git fetch --depth=1 origin "$BASE_REF"
git show FETCH_HEAD:.cfgaudit.yml > "$RUNNER_TEMP/cfgaudit.yml" 2>/dev/null || : > "$RUNNER_TEMP/cfgaudit.yml"
- uses: cfgaudit/cfgaudit@v1
with:
config: ${{ runner.temp }}/cfgaudit.yml
Inputs: path (default .), format (text/json/sarif), strict, user, config (replaces the scanned directory's .cfgaudit.yml; relative to the workspace, or an absolute path outside it), plugins, output, fail-on (error/never), image.
Outputs: exit-code, output-file. By default the step fails on findings at or above the configured threshold; set fail-on: never for advisory mode.
GitLab CI/CD component
For GitLab pipelines, include the component (published to the CI/CD Catalog):
include:
- component: gitlab.com/cfgaudit/cfgaudit/[email protected]
inputs:
path: .
format: text
Inputs: stage, path, format, config, version (pinned ghcr.io image tag, optionally with @sha256:<digest>), allow_failure. The job fails the pipeline on error-severity findings unless allow_failure: true. path and config take path characters and $VAR / ${VAR} references only; quotes, backticks and $( ) are rejected when the pipeline is created. The output artifact expires after 30 days.
config replaces the scanned directory's .cfgaudit.yml. For merge requests, keep the config out of the repository, for example in a File-type CI/CD variable, so the merge request cannot change it (why):
include:
- component: gitlab.com/cfgaudit/cfgaudit/[email protected]
inputs:
config: $CFGAUDIT_CONFIG # File-type CI/CD variable holding the .cfgaudit.yml
To surface findings inline in merge requests via the Code Quality widget, use the second component (emits a GitLab Code Quality report):
include:
- component: gitlab.com/cfgaudit/cfgaudit/[email protected]
inputs:
path: .
Pin the component to a released tag, not a moving ref — consistent with cfgaudit's own supply-chain guidance (CFG010/CFG013).
Claude Code plugin
The repo doubles as a Claude Code plugin marketplace. Install it to get an on-demand scan command plus automatic scans when config files change:
/plugin marketplace add cfgaudit/cfgaudit
/plugin install cfgaudit@cfgaudit
The plugin adds:
/cfgaudit:scan— scan the current project on demand./cfgaudit:explain <RULE>— explain a rule (what it checks, why, how to fix); with no argument it lists the rules./cfgaudit:init— scaffold a project-aware.claude/settings.json: Claude inspects the project's tooling and tailors the deny list on top of the baseline, then verifies 0 findings.- A Stop hook (scan when a session ends) and a PostToolUse hook (scan after edits to
settings.json/CLAUDE.md/.mcp.json/.claude/files).
Hooks call a cfgaudit binary on your PATH (install via Homebrew or go install above); if none is found the bundled wrapper downloads the matching prebuilt release binary for your OS/arch (checksum-verified and cached) — no Go toolchain required. Team rollout via .claude/settings.json:
{
"extraKnownMarketplaces": {
"cfgaudit": { "source": { "source": "github", "repo": "cfgaudit/cfgaudit" } }
}
}
What cfgaudit checks
Rules are grouped by the part of the configuration they target.
settings.json — permissions, env, hooks & files
General Claude Code settings: the permission model, environment block, lifecycle hooks, command-running helpers, schema, and local-file hygiene.
MCP servers — settings.json mcpServers & .mcp.json
Rules about MCP servers. MCP is a shared standard, so the per-server checks (CFG010–CFG021) are cross-agent: they run against the inline mcpServers block in settings.json, the project's root .mcp.json (the file that enableAllProjectMcpServers / enabledMcpjsonServers auto-approve), and other agents' MCP configs when present — .cursor/mcp.json (+ ~/.cursor/mcp.json with --user), .vscode/mcp.json (VS Code's top-level servers key is handled), .github/mcp.json (Copilot CLI loads it since 1.0.61, "Auto-load MCP servers from .github/mcp.json workspace config file"; read as Copilot reads it, strictly and only under mcpServers: measured on 1.0.95, a file with VS Code's servers key is skipped as "malformed: mcpServers: Required", so such a file gives no finding), cline_mcp_settings.json, Windsurf's ~/.codeium/windsurf/mcp_config.json, the context_servers block of Zed's project-scoped .zed/settings.json (JSONC; its terminal.shell, lsp.<name>.binary and dap.<name> are read too, as command sites), Devin CLI's .devin/mcp_config.json and its gitignored twin .devin/mcp_config.local.json, plus the legacy mcpServers block of .devin/config.json and .devin/config.local.json (whose transport field is folded into type), the mcpServers block of Gemini CLI's .gemini/settings.json (+ ~/.gemini/settings.json with --user), the [mcp_servers] tables of OpenAI Codex CLI's .codex/config.toml (project-scoped, plus ~/.codex/config.toml with --user), the [mcp_servers] tables of xAI Grok CLI's .grok/config.toml (transport inferred from command vs url), the mcpServers list of Continue's .continue/config.yaml (+ ~/.continue/config.yaml with --user), the mcp block of OpenCode's project opencode.json (JSONC despite the extension; its command array is split into the executable and its arguments and environment maps onto env, and a server with enabled: false is skipped), the inline mcpServers: block in a Claude Code subagent definition's frontmatter (.claude/agents/*.md), which connects when that subagent starts, and the inline mcp-servers: block in a GitHub Copilot custom agent (.github/agents/*.md). Each finding is attributed to the file the server was declared in. A malformed config is reported as a tool error rather than silently skipped. CFG003 governs the blanket auto-approval flag and is Claude Code–specific (settings.json only).
The root .mcp.json is not Claude-Code-only: Kimi Code CLI reads the same repo-root file (agent-core/src/mcp/config-loader.ts — projectRoot: join(projectRoot, '.mcp.json'), resolved from the nearest .git ancestor) and executes its stdio entries when a session starts once the workspace is trusted: Kimi Code's trust prompt, which defaults to "Trust this folder", shows the project MCP launch targets up to 2.1.1 and, since 2.2.0, activation summaries and configuration paths instead (Kimi Code #4056), and loads project MCP only for a trusted workspace (includeProject: this.trust.isTrusted()); headless kimi -p skips it unless KIMI_CODE_TRUST_WORKSPACE=1 (#618). So the MCP rules cfgaudit already runs on .mcp.json protect Kimi users too, undocumented in Kimi's own MCP docs. (Kimi's project-local .kimi-code/mcp.json, which overrides this root file, is covered in the Kimi Code section below.)
VS Code reads it too (#614). Since 1.138.0 the workspace discovery loads <folder>/.mcp.json with trust inherited from the workspace (workspaceDotMcpDiscovery.ts, McpServerTrust.Kind.Trusted; before, each server waited for its own trust prompt), and since 1.139.0 it also accepts the file without the mcpServers wrapper, a server-name map at the top level (parseWorkspaceRootMcpConfiguration: wrapped ? value.mcpServers : value). Claude Code rejects that unwrapped shape (2.1.288: "MCP config errors ... Invalid input: expected record", and the server does not start), so cfgaudit reads an unwrapped root .mcp.json on a target of its own, keeping entries that carry a command or a url, and the MCP rules apply to it as to the wrapped file. Of 86 real unwrapped files sampled, 46 had findings.
OWASP MCP Top 10 mapping (secondary)
The MCP-server rules above carry a secondary mapping to the OWASP Top 10 for Model Context Protocol, in addition to their primary LLM Top 10 risk. It is a complementary lens for readers who think in the MCP taxonomy; the LLM mapping stays primary.
Provisional. Mapped against OWASP MCP Top 10 v0.1 (Beta, Phase 3) — IDs and titles may still change before final release. Filter from the CLI with
cfgaudit list --owasp MCP05.
MCP03 (Tool Poisoning), MCP06 (Intent Flow Subversion), MCP08 (Lack of Audit & Telemetry), and MCP10 (Context Injection & Over-Sharing) have no dedicated config rule yet — they involve runtime tool behaviour or live server inspection rather than a statically committed config surface.
Instruction files — CLAUDE.md & other agents
AI coding agents read their instruction files as trusted system-context every session, so a committed or user-global instruction file is a prompt-injection target. Claude Code reads five project instruction files, and all five are scanned: the project CLAUDE.md, plus .claude/CLAUDE.md and CLAUDE.local.md, plus AGENTS.md and .claude/AGENTS.md (the AGENTS pair is what Claude Code falls back to in a project with no CLAUDE-family file; cfgaudit reports it either way, since one deletion flips that condition). ~/.claude/CLAUDE.md is scanned with --user, as are .claude/rules/**/*.md and .claude/output-styles/**/*.md, both of which Claude Code discovers recursively. A file that these Claude Code instruction files pull in with an @path import is scanned with the same rules, up to the four hops Claude Code follows, and its findings name the import chain (CLAUDE.md -> docs/notes.md); an import that leaves the repository is not read and is reported by CFG116. The same content rules also scan, when present in the project: .cursorrules, .cursor/rules/**/*.mdc (recursive, the way Cursor organises rules in folders; a plain .md at the top of .cursor/rules is scanned too, though Cursor itself ignores it), .cursor/commands/*.md (Cursor 1.6+ custom commands: the filename becomes the slash command and the file's whole content becomes the prompt), Cursor's custom subagents .cursor/agents/*.md and skills .cursor/skills/**/SKILL.md (Cursor walks the skills root recursively; ~/.cursor/skills/ with --user), and the Codex directories Cursor reads for compatibility, .codex/agents/*.md and .codex/skills/**/SKILL.md, Zed's .rules (the first name on Zed's rules-file list, ahead of .cursorrules), Cline's .clinerules as a file or a directory (every .md / .markdown / .txt under it, recursively, except hooks/) and .cline/rules/, plus .cline/workflows/* (Markdown/text), .cline/agents/*.{yml,yaml} (frontmatter and prompt body) and .cline/skills/ (SKILL.md there or one directory down); a file in .clinerules/, .cline/rules, .cline/workflows or .cline/skills whose frontmatter sets disabled: true (or enabled: false without a disabled key) is skipped, because Cline does not load it, while a lone .clinerules file is still read for Zed, .windsurfrules, .windsurf/rules/**/*.md (recursive), the singular AGENT.md (Amp / Grok CLI convention, the sibling of the AGENTS.md above), GEMINI.md (Gemini CLI; ~/.gemini/GEMINI.md with --user), GitHub Copilot's .github/copilot-instructions.md, path-specific .github/instructions/**/*.instructions.md (recursive, as VS Code and Copilot discover them) and custom agents (.github/agents/*.md, also the *.agent.md spelling, whose body is the agent's system prompt), Gemini CLI's project agents (.gemini/agents/*.md), and Claude Code's custom subagents (.claude/agents/*.md), slash commands (.claude/commands/**/*.md; a subdirectory namespaces them, sub/deploy.md is /sub:deploy), skills (.claude/skills/*/SKILL.md), and modular rules (.claude/rules/**/*.md, discovered recursively) — these also under ~/.claude/ with --user. Cline reads .claude/skills as well since v4.1.24 and CLI 3.0.71 (changelog: "skills in .claude/skills are now discovered"), so a skill committed there reaches Cline users too. It also scans .agents/skills/**/SKILL.md (recursive), the cross-agent skills convention read from the scanned project by OpenHands, OpenAI Codex, crush, goose and Kimi — a committed skill there is trusted context for all of them; ~/.agents/skills/ is covered with --user. GitHub Copilot's project-skills directory .github/skills/**/SKILL.md (recursive) is scanned the same way: GitHub documents .github/skills, .claude/skills and .agents/skills as the three interchangeable project locations, and a skill committed there is read by Copilot CLI, the cloud agent, VS Code agent mode and — GA since 2026-07-29 — Copilot code review, which reviews pull requests. It is project-only, because Copilot's personal-skills paths are ~/.copilot/skills and ~/.agents/skills, not ~/.github/skills. Kimi Code's own skills root .kimi-code/skills/**/SKILL.md is scanned too, and so is a plain <name>.md at the top of it or of .agents/skills/, which Kimi registers as a skill unless a <name>/SKILL.md sits beside it. And it scans Kimi Code's project agent definitions — .kimi-code/agents/**/*.md and .agents/agents/**/*.md (both recursive) — whose bodies are trusted context and whose override: true frontmatter is flagged by CFG092. Findings name the file they came from.
A Claude Code subagent definition is more than instruction text. Beyond the flat frontmatter fields above, .claude/agents/*.md can carry two nested blocks that cfgaudit decodes and routes into the existing families: hooks: (the settings.json event → matcher → {type, command} schema) becomes command sites, so the command-content rules judge it, and a type: "http" handler there is read by CFG088 and CFG050 as in settings.json; and the inline mcpServers: list rides the MCP rules like any other server declaration. Both are attributed to the agent file.
The mcpServers: value must be a list whose entries are either a single-key mapping (an inline definition) or a bare string (a reference to a server configured elsewhere, which declares nothing of its own and is skipped). A mapping-shaped mcpServers: — the shape .mcp.json uses — is deliberately not decoded: Claude Code 2.1.220 ignores it, verified by running a subagent that declared a server each way and observing which process actually launched, so flagging it would report a server that never connects.
GitHub Copilot custom agents (.github/agents/*.md, also the *.agent.md spelling) are scanned the same way, with two shape differences: the key is kebab-case mcp-servers and its value is a mapping of server name to config, not a list. The per-server config is the format GitHub's repository-level MCP configuration uses (type of local/stdio/http/sse, command/args/env for local servers, url/headers for remote ones), so the whole MCP family applies. Since Copilot CLI 1.0.97 the frontmatter can also carry agent-scoped hooks ("Add agent-scoped declarative hooks for custom agents"): the same event → handlers shape as .github/hooks/*.json, with windows, linux and osx overriding the command per platform. Agent files in subfolders of .github/agents count too: measured on Copilot CLI 1.0.95, an agent in .github/agents/team/deep/ was listed and ran, and cfgaudit walks the directory recursively. They run only while that agent is selected and, per the hooks reference, "Repository and inherited-agent hooks require workspace admission". cfgaudit decodes them for the command-content rules, CFG087 and CFG088; CFG086 does not apply, since selecting an agent is not opening the repository (#747). Unlike the Claude Code side, this shape rests on GitHub's reference documentation plus the customization spec checked into the microsoft/vscode tree rather than on a run against the agent itself.
The frontmatter hooks have a narrower trigger than a settings.json hook: they fire when the agent is spawned through the Agent tool or an @-mention, or when it runs as the main session via --agent or the agent setting, and since 2.1.218 they also require the agent file's folder to have accepted workspace trust. That is why CFG067 (committed hooks run on everyone who opens the repo) and CFG086 (zero-click event) are not extended to them — the command content is the finding, not the trigger. The inline mcpServers: block has no such gate: it connects when the subagent starts, including in a folder whose trust dialog was never accepted.
A Claude Code skill or slash command can run shell commands itself. An inline !`cmd` (at the start of a line or after whitespace) and a ```! fenced block in .claude/skills/*/SKILL.md, .claude/commands/**/*.md or a plugin's SKILL.md run when the skill is invoked, by a user typing the slash command or by the model through the Skill tool, before the text reaches the model (#643). Measured with 2.1.296, the command runs with no prompt when the file's allowed-tools or the project's allow list covers it, and it also runs inside an ordinary code fence or an HTML comment. cfgaudit reads each one as a command site, so the command-content rules (CFG008/014/015/027/028/037/038/039/072/077/078) judge it. A project whose own settings set disableSkillShellExecution: true switches the blocks off, and cfgaudit then reads none. A ! in a .claude/agents body does not run and is not read.
A skill or slash command can also carry hooks. Its frontmatter takes the same hooks: block as settings.json and a subagent, and Claude Code runs it while the skill or command is active (#935). Measured on 2.1.310 through claude -p: a skill's PreToolUse and Stop hooks and a command's Stop hook all ran, in a workspace whose trust dialog had not been accepted. cfgaudit reads the block in .claude/skills/**/SKILL.md, .claude/commands/**/*.md (also under ~/.claude/ with --user) and a plugin's skills (not a plugin's commands, whose frontmatter hooks did not run on 2.1.310, #937): command handlers go to the command-content rules, http handlers to CFG088 and CFG050. As for subagents, CFG067 and CFG086 are not extended to them, because they fire on invocation rather than on opening the repository. The cross-agent skill roots (.agents/skills, .github/skills, …) are not read for hooks, since no other agent is known to run such a block.
Plugin & skill packages
Installing an agent plugin is a supply-chain trust decision. With --plugins <dir> (and auto-discovered when the scanned project bundles a .claude-plugin/ or a kimi.plugin.json, for every skills-directory plugin under .claude/skills/, and for ~/.claude/plugins/ and ~/.claude/skills/ under --user), cfgaudit looks inside the package and runs the existing rules against its bundled artifacts:
Findings are attributed to the in-package file.
Skills-directory plugins are the repository-side case. Claude Code loads any folder under the project's .claude/skills/ that holds a .claude-plugin/plugin.json as a plugin (<name>@skills-dir), with no install step and no enabledPlugins entry, once the workspace trust dialog is accepted. A repository can therefore ship hooks and MCP servers this way, so cfgaudit scans these folders by default (#609). Measured on Claude Code 2.1.281 through 2.1.288: a SessionStart hook in .claude/skills/<name>/hooks/hooks.json ran and a stdio server in its plugin.json started. A folder without that manifest is an ordinary skill and stays with the instruction-content rules. A manifest that does not parse keeps the whole plugin from loading, so it is reported as CFG109 and nothing else of that plugin is scanned. A plugin that does not load is skipped with a note on stderr: one whose manifest sets "defaultEnabled": false, or one that .claude/settings.json or .claude/settings.local.json sets to false under enabledPlugins (the later file wins, and a setting keyed by the manifest's name counts, not one keyed by the folder name). A settings file Claude Code discards whole for a type error disables nothing. A SKILL.md that the project skill scan already reads is reported once. Unlike --plugins, which walks the whole package for its author, a skills-directory plugin is scanned for what Claude Code loads from it: hooks/hooks.json and any hook file the manifest names under hooks, the manifest's MCP servers, and every SKILL.md under skills/ or a path the manifest names under skills. These folders often vendor a whole upstream repository, and on 2.1.288 a hooks.json nested below the plugin's own hooks/ did not run unless the manifest named it.
A root skills/ folder is scanned by default too. Skill collections and plugin repositories keep their skills under skills/<name>/SKILL.md (or skills/<author>/<name>/SKILL.md), the folder a plugin installs from and skill installers copy from. Every SKILL.md below the scanned directory's own skills/ folder is read with the instruction-content rules even without --plugins (#912), so scanning a skill collection before installing from it reports what is in its skills. A plugin's hooks and MCP servers still need --plugins (or an auto-discovered .claude-plugin/), which also reads the manifest; a file both paths read is reported once.
This half is author-side, and deliberately so. A Kimi Code plugin is loaded from the user's install store, never from a scanned repository, and there is no committed key that enables one — enablement lives in that store (PluginManager reads readInstalled(kimiHomeDir)), which a repo cannot write. So a kimi.plugin.json is scanned for the benefit of the author publishing the plugin and the reviewer reading it before installing, which is exactly what the .claude-plugin/ handling already offers. It is not a vector against the scanned repo's own contributors, and cfgaudit does not claim otherwise. The manifest's hooks array is a distinct schema from the event-to-matcher-groups map every other agent uses and is not decoded. Bundled binaries / arbitrary scripts are not content-scanned (that is general SAST, outside cfgaudit's config-audit scope).
Agent-skills lockfile — skills-lock.json
The vercel-labs/skills CLI (skills.sh) records the external sources it pulls agent skills (instruction content) from in a skills-lock.json at the repo root. cfgaudit scans the committable project-root file; the user-global ~/.agents/.skill-lock.json is out of scope (not committable).
VS Code workspace — .vscode/
.vscode/ files are committed into repositories and read by VS Code and its forks (Cursor, Windsurf), so a committed workspace config is a repo-controlled auto-run / supply-chain surface. cfgaudit scans these automatically when present and attributes findings to the source file.
Cursor & GitHub Copilot — hooks, permissions and repository settings
Cursor's .cursor/hooks.json and Copilot's .github/hooks/*.json declare shell commands, prompts and HTTP callbacks the agent runs at points in its lifecycle. Copilot has a second spelling of its own: an inline hooks table in .github/copilot/settings.json, which the CLI's settings help describes as "the same schema as .github/hooks/*.json" acting "as repo-level hooks", and cfgaudit reads both. A handler can also use Copilot CLI's shell-free form, exec with args ("Runs the executable directly without a shell"), which the command rules read as one joined line, as for Claude Code's exec form. Its disableAllHooks is global rather than per-file ("whether to disable all hooks (repo-level and user-level)"), so a repository setting it suppresses every Copilot hook finding, the inline table and the files alike. Cursor's docs say hooks are "stored in version control alongside your code" and "automatically load for all team members", so both are committable execution surfaces. Their command content is judged by the command-content rules (CFG008/009/014/015/027/028/037/038/039/059/072/077/078), which run over these files too; the rules below cover what the command text cannot show — the trigger, the permission decision, the declared network channel, and the plugin supply chain.
Copilot CLI also reads .github/lsp.json (#648): its lspServers entries are language servers the CLI starts in a session for matching files, and keeps running. copilot lsp list (1.0.95) lists a repository's servers as configured, and the CLI's /lsp help names the file as the project config. Each command and its args is a command site. Copilot CLI project extensions, .github/extensions/<name>/extension.{mjs,cjs,js}, run with Node.js and are reported by CFG114 at info, since they load only with experimental features on and the folder trusted.
Cursor 2.5 added a second committable file, .cursor/permissions.json, naming what runs without an approval prompt: terminalAllowlist (matched on the command prefix), mcpAllowlist ("<server>:<tool>" patterns, "*:*" = everything), and autoRun instructions that steer the Auto-review classifier in natural language. Cursor concatenates the per-repo file with a teammate's ~/.cursor/permissions.json instead of letting either override the other — only a team-admin dashboard policy outranks it — and the docs ask you to "commit the per-repo file so teammates inherit the same rules". So an entry shipped in a repo cannot be taken back by the person who clones it. cfgaudit scans the project file only; a user's own copy is self-intentional. Both rules name Cursor's own precondition (permissions.json applies only when Run Mode is enabled) rather than implying the entries always fire, and neither makes any claim about how Cursor treats chained commands, pipes or subshells, which its reference does not document.
Cursor 2.5 also added .cursor/sandbox.json, the profile bounding what agent-run commands may touch: type (workspace_readwrite by default, or insecure_none, which disables the sandbox), a networkPolicy object whose documented default is deny, and additionalReadwritePaths / additionalReadonlyPaths. The two sandbox files are merged with the user's field by field: path grants and network allow lists are unioned, a "deny" default and restrictive booleans win, and readBoundary / additionalReadPaths are taken from the repository (#649). So a committed profile adds to a teammate's grants, flips the defaults for a teammate with no file of their own, and decides the read boundary. CFG095 reports the weakening directions only: workspace_readonly and disableTmpWrite make the sandbox stricter and are deliberately not flagged, and a grant that stays inside the workspace is silent.
Gemini CLI — .gemini/settings.json & GEMINI.md
Gemini CLI stores its config in settings.json with a security surface that mirrors Claude Code's. cfgaudit discovers .gemini/settings.json (project) and ~/.gemini/settings.json (with --user), and GEMINI.md (project) / ~/.gemini/GEMINI.md — the latter scanned by the same content rules as CLAUDE.md (CFG024–CFG036, CFG057). A Gemini mcpServers block rides the shared MCP rules (CFG010–CFG021, CFG049–CFG059), attributed to the settings file. Its hooks block (the nested hooks.<Event>[].hooks[].command shape) is scanned too: every hook command rides the command-content rules (CFG008/009/014/015/…), a SessionStart hook — Gemini's one zero-click event — is flagged by CFG086 as a committed command that runs before anyone asks the agent for anything, and a BeforeTool hook that rewrites the tool arguments (hookSpecificOutput.tool_input) is flagged by CFG087 (warn). Gemini hooks cannot auto-approve a tool call (decision: "allow" is inert in the CLI), so CFG087 has no error case for them. The hooksConfig.enabled: false / hooksConfig.disabled kill switches are honoured, and event names are matched as exact PascalCase (Gemini does not normalize them). Three rules cover the Gemini-specific settings:
| ID