OpenACA - Open Agent Composition Analysis

Your dependency scanner can see your libraries. It usually cannot see the plugins, MCP servers, skills, hooks, commands, and bundled dependencies that compose your AI agent stack.

OpenACA is the open reference scanner for Agent Composition Analysis (ACA). It resolves stable identities for agent-stack components, builds an Agent BOM, and matches those components against known security advisories (OSV / GHSA / CVE / MAL).

Status: V0 - early and evolving, available on PyPI. Start with the Quickstart, then see the docs for scan modes, coverage, CLI reference, and schema details.

What OpenACA does

• Identity Resolution - normalize agent config such as npx @scope/foo@1.4.0, Git-backed skills, and plugin marketplace refs into stable component identities.
• Composition Graph - show how components enter the stack: host -> plugin -> skill / MCP server / hook -> dependency.
• Risk Attribution - trace a vulnerable dependency back to the plugin, skill, or MCP server that introduced it.
• Advisory Intelligence - match components against upstream OSV / GHSA / CVE / MAL records, enriched with agent-specific context where OpenACA has overlays.

OpenACA builds on upstream advisory records rather than minting its own IDs. It contributes agent-component identity, composition, and context on top.

Why OpenACA

Agent components are installed and activated through files most general-purpose SCA scanners do not read: mcp.json, .mcp.json, claude_desktop_config.json, .claude-plugin/plugin.json, .claude/settings.json, SKILL.md, and related host-specific state.

ACA is the AI-agent analogue of Software Composition Analysis (SCA):

The two work together. Use a general-purpose SCA scanner for normal software dependencies, and OpenACA for the agent-installation surface those tools do not parse today.

Quickstart

Install

curl -fsSL https://raw.githubusercontent.com/open-agent-security/openaca/main/scripts/install.sh | sh

This bootstraps uv if needed, then installs OpenACA as an isolated CLI tool.

Scan your endpoint

openaca scan endpoint

This scans your user-level Claude Code config (~/.claude). Add --project <path> to include project-local skills, MCP servers, commands, agents, hooks, and plugin manifests.

To generate a component-centric exposure report from the same scan evidence:

openaca scan endpoint --report exposure --format markdown --output openaca-exposure-report.md

Exposure reports are static composition reports. They rank components using available scan evidence; they do not monitor runtime behavior or prove exploitability.

Try it on a sample project

Drop a sample .mcp.json in any empty directory and scan it:

mkdir openaca-demo && cd openaca-demo
cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server@1.1.0"]
    }
  }
}
EOF
openaca scan repo --target . --fail-on none

Expected output, abbreviated:

Inventory

repo .
└── direct components/
    └── MCPs/ (1)
        └── @cyanheads/git-mcp-server@1.1.0 (stdio via npx) (from .mcp.json)  [! GHSA-3q26-f695-pp76]

Findings

Found 1 vulnerability in 1 package.

@cyanheads/git-mcp-server 1.1.0
  location: .mcp.json
  fix:      upgrade to >=2.1.5

  HIGH  GHSA-3q26-f695-pp76  fixed in 2.1.5  @cyanheads/git-mcp-server vulnerable to command injection in several tools  [osv.dev]
        owasp-asi: ASI02, ASI05  [owasp-agentic-top-10-2026]

Next
  emit Agent BOM: openaca bom repo --target . --output-dir boms/

For clean scans, posture examples, and expected output, clone the openaca-demo repo.

Scan modes

OpenACA has two primary scan modes:

• openaca scan repo - review agent components declared in a repository, usually in CI or a PR check.
• openaca scan endpoint - review agent components installed on a machine, such as a developer laptop or managed runner.

Both modes produce inventory and findings. The mode tells you what observation context the result came from: declared-in-source-control vs. installed-on-this-machine.

See Scan Modes for the details, including --project <path>.

Endpoint policy for Claude Code

OpenACA can compile an admission and risk policy into a Claude Code managed settings drop-in for one endpoint. Compilation scans the endpoint first, so risk-gate results and the resulting artifact reflect the installed components on that machine. OpenACA writes the artifact you name; an administrator or device-management tool installs it into Claude Code's system settings directory.

openaca policy validate policy.yaml
openaca policy compile policy.yaml --target "$HOME/.claude" --host claude --output /tmp/50-openaca-policy.json
sudo install -m 644 /tmp/50-openaca-policy.json "/Library/Application Support/ClaudeCode/managed-settings.d/50-openaca-policy.json"

When a remote policy is configured, the equivalent endpoint command fetches the current organization policy before doing the same fresh local scan and compilation:

openaca remote configure --token "$OPENACA_REMOTE_TOKEN"
openaca remote policy compile --target "$HOME/.claude" --host claude --output /tmp/50-openaca-policy.json
sudo install -m 644 /tmp/50-openaca-policy.json "/Library/Application Support/ClaudeCode/managed-settings.d/50-openaca-policy.json"

It does not install the artifact. If the remote has no policy, cannot be reached, or returns an invalid policy, compilation fails without replacing an existing artifact.

The current Claude target can enforce exact MCP admission, explicit plugin blocks, and a category-wide block on standalone skills. It does not provide a managed allowlist for already-installed plugins. A policy with plugins.default: blocked is therefore reported as not enforceable for Claude Code.

After deploying an artifact, start a fresh Claude session and check /status. It must show the file drop-in as a selected managed source. For a blocked plugin, check /plugin's Installed view and a command supplied by that plugin. Do not use claude plugins list as an effective-policy assertion: it can show a persisted installation record even when managed policy prevents the plugin from loading. For a standalone-skill block, check that a direct skill is unavailable while a skill supplied by an admitted plugin remains available.

The policy verification fixtures provide copyable policy files and a full MCP, plugin, and skill test sequence.

GitHub Action

Add to .github/workflows/openaca.yml:

name: OpenACA
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: open-agent-security/openaca@v1
        with:
          fail-on: high           # high | any | none (default: any)
          # target: .             # path to scan (default: workspace)
          # sarif: results.sarif  # output path (default: openaca-results.sarif)

Findings appear as GitHub annotations on the PR. With GitHub Advanced Security, upload the SARIF to the Security tab via github/codeql-action/upload-sarif@v3.

Claude Code plugin

Prefer staying inside Claude Code? The OpenACA plugin wraps the scanner in slash commands:

/plugin marketplace add open-agent-security/openaca-claude-plugin
/plugin install openaca@openaca

• /openaca:scan - run an endpoint or repo scan
• /openaca:bom - generate an Agent BOM
• /openaca:explain - explain a finding in conversation
• /openaca:triage - guided review after agent config changes

The plugin is explicit-invocation only: no hooks, no background monitors, and no modification of your Claude Code settings.

Current coverage

OpenACA V0 focuses on declared and installed agent composition for Claude Code and Claude-family filesystem conventions.

Today it reads:

• host-specific agent config such as .claude/settings.json, .mcp.json, mcp.json, claude_desktop_config.json, installed_plugins.json, SKILL.md, hooks, commands, and subagents;
• package manifests and lockfiles when they belong to agent components, such as dependencies bundled by a Claude Code plugin.

Use --include-posture to include configuration-hygiene findings such as unpinned installs, insecure MCP endpoints, endpoint overrides, and MCP auto-approval.

See Coverage, CLI Reference, and Posture Findings for the full details.

Limitations

OpenACA V0 does not yet see:

• programmatic SDK configuration embedded directly in source code;
• non-Claude agent-host local state such as Codex CLI, Cursor, Windsurf, or VS Code agent-mode config;
• vulnerabilities for local-only or source-less components that do not provide a package, Git, or external match coordinate;
• live tool invocations or runtime blocking.

The Agent BOM format is pre-1.0. Field names, identities, and CLI output may change before the first stable schema release.

Docs

• Getting Started
• Scan Modes
• Identity Model
• CLI Reference
• Coverage
• Overlay Reference
• Agent BOM Schema
• Posture Findings

Status

V0, in development. See docs/specs/openaca-thesis.md for the thesis and V0 -> V1 roadmap, docs/adrs/ for architecture decisions, and docs/plans/ for implementation plans.

Contributing

See CONTRIBUTING.md for contribution guidance.

Coordinated disclosure

OpenACA does not mint vulnerability IDs. Vulnerabilities in agent components are filed upstream (CVE / GHSA / OSV / PYSEC / MAL); once an upstream record is public, contribute an OpenACA overlay per CONTRIBUTING.md.

For security issues in OpenACA's own code, see SECURITY.md. Do not file public issues for unembargoed vulnerabilities.

License

• Code: Apache License 2.0.
• Overlay data (YAML under overlays/ and the static exports derived from them): Creative Commons Attribution 4.0 International (CC-BY-4.0) - matches OSV.dev. Attribution: OpenACA - Open Agent Composition Analysis, https://openaca.dev.