GitHub - cfgaudit/cfgaudit: Static security auditor for AI-agent configuration: Claude Code, MCP…

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 aqua:

aqua g -i cfgaudit/cfgaudit && aqua i

cfgaudit is in the aqua standard registry from v4.585.0 on. aqua checks each download against checksums.txt and the attestation of cfgaudit's release workflow (Verifying a release).

With Python tooling (the wheel carries the prebuilt binary, no Python code):

pipx install cfgaudit      # or: uv tool install cfgaudit
uvx cfgaudit .             # run once without installing

Pin it next to your other linters with cfgaudit==X.Y.Z in a requirements file.

With Node.js (the package runs the prebuilt binary for your platform, no install script):

npx [email protected] .                                   # run once without installing
npm install --save-dev --save-exact [email protected]     # pin it in a JavaScript project

Keep the version pinned: cfgaudit reports an unpinned npx package in an MCP server (CFG010) for the same reason.

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.

Usage

cfgaudit .                                   # audit the current directory
cfgaudit --format sarif . > cfgaudit.sarif   # for GitHub Code Scanning
cfgaudit explain CFG001                      # a rule's documentation in the terminal
cfgaudit list --agent cursor                 # the rules for one agent
cfgaudit init                                # a hardened .claude/settings.json for a new project

cfgaudit exits 1 when it reports an error finding (or a warn finding with --strict), 0 when it reports only warn or info findings (without --strict) or none, and 2 on a usage or tool error. Usage has every flag, the output formats (with the schema of the JSON output), the init, policy, baseline, lock and inventory subcommands, the exit codes and the configuration file.

Configuration file. A .cfgaudit.yml in the scanned directory turns rules off or changes their severity, excludes paths and sets an organisation policy: see Configuration file, and point your editor at the JSON Schema to have it checked while you type. When you scan a repository you do not trust, do not let its own file configure the audit (Scanning a repository you do not trust).

GitHub Action

- uses: cfgaudit/cfgaudit@v1
  with:
    path: .

SARIF upload to GitHub Code Scanning and every input and output are in CI integration.

GitLab CI/CD component

include:
  - component: gitlab.com/cfgaudit/cfgaudit/[email protected]
    inputs:
      path: .

The Code Quality template and every input are in CI integration.

pre-commit hook

For the pre-commit framework, see CI integration.

Claude Code plugin

/plugin marketplace add cfgaudit/cfgaudit
/plugin install cfgaudit@cfgaudit

The plugin adds /cfgaudit:scan, /cfgaudit:explain and /cfgaudit:init, and hooks that scan after edits to agent configuration and when a session ends. Team rollout and the details are in CI integration.

What cfgaudit checks

The rules are grouped by the configuration they read. Rules lists every rule with its severity and OWASP risk, and cfgaudit list prints them:

How the rules map to the OWASP risks, and which risks a configuration file cannot show, is in OWASP mapping.

Verifying a release

Releases from v1.17.0 on carry SLSA Build Level 3 provenance, and the container image is signed with cosign. The commands to check a download before you run it are in Verifying a release.

Badge

Using cfgaudit on your project? Show it in your README:

[![agent security: cfgaudit](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cfgaudit/cfgaudit/main/assets/badge/v1.json)](https://github.com/cfgaudit/cfgaudit)

To show it on a GitLab project page, add it under Settings → General → Badges with:

Link: https://github.com/cfgaudit/cfgaudit
Badge image URL: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cfgaudit/cfgaudit/main/assets/badge/v1.json

Contributing

See CONTRIBUTING.md for dev setup, the test loop, and the step-by-step recipe for adding a new rule. How cfgaudit is tested is in TESTING.md. Participation is governed by the Code of Conduct; what is planned next is in the roadmap. What cfgaudit does for people who use assistive technology, and how to report a barrier, is in ACCESSIBILITY.md.

If cfgaudit is useful to you, a star on GitHub helps other people find it.

License

Apache 2.0, see LICENSE. The repository follows the REUSE specification: every file carries or is assigned its copyright and license, and reuse lint passes.

cfgaudit/cfgaudit

Measured star growth

About

README.md