← All posts

Claude Code Plugin Security Checklist for Team Review

The short answer: do not approve a Claude Code plugin because the marketplace looks familiar or the README sounds harmless. Use a Claude Code plugin security checklist that treats every plugin as executable software with instructions, hooks, MCP servers, binaries, settings, permissions, and update behavior.

For a security engineer or platform owner, the approval question is simple: what can this plugin cause Claude to attempt, and what code can it run without Claude asking? If you cannot answer both, the plugin is not ready for broad developer use.

Concretely, a safe review should end in one of four outcomes: approve, approve only in a sandbox, internalize or fork, or reject. The rest of this checklist gives you the evidence for that decision.

Related reading: MCP permission gateway patterns for Claude Code.

Why Claude Code Plugins Need Security Review

Claude Code plugins are not prompt packs. According to Anthropic's plugin security guidance, an installed plugin can execute arbitrary code on the developer's machine with that user's privileges.

That changes the review model. You are not only reading natural-language instructions. You are reviewing a package that may contain hooks, MCP servers, LSP servers, executables in bin/, skills, commands, agents, themes, output styles, settings, and background-updated files.

Some parts influence the model. Skills, commands, agents, rules, and tool descriptions can steer what Claude decides to do. Other parts execute code. Hooks, MCP stdio servers, LSP servers, and binaries can run outside Claude Code's normal permission prompt boundary.

That mixed trust boundary is the main risk. A plugin can add instructions that look helpful, then pair them with code paths that touch files, secrets, package managers, shell commands, or remote services.

Start With The Approval Decision

Do not start with "is this plugin useful?" Start with the decision gate.

  • Approve when the source, version, components, permissions, update path, runtime behavior, and owner are understood and acceptable.
  • Sandbox-only when the plugin is useful but includes shell execution, MCP servers, network access, package installation, broad filesystem access, or unclear dependencies.
  • Internalize or fork when the behavior is acceptable but the update channel, maintainer posture, dependency chain, or marketplace source is not.
  • Reject when the plugin rewrites permissions, hides execution, asks for broad authority without a clear need, exfiltrates data, loads untrusted code, or cannot be pinned and reviewed.

In practice, most third-party plugins with hooks or MCP servers should start as sandbox-only until your team proves otherwise.

Claude Code Plugin Security Checklist

Use this checklist before a plugin reaches a shared developer environment, project settings, base image, dev container, CI runner, or enterprise marketplace.

1. Identify The Marketplace And Source

Record where the plugin comes from. A marketplace name identifies the catalog publisher. It does not prove the behavior of every plugin inside that catalog.

Check the marketplace source, repository, owner, release process, plugin manifest, and install path. Anthropic reserves official and community marketplace names and applies source checks, but the brief is clear: those checks help integrity, not code review.

For third-party sources, require a specific repository, version, ref, archive hash, or commit. If the plugin cannot be tied to a reviewable artifact, do not approve it for team use.

2. Pin The Reviewed Version

Auto-update is a security decision. Claude Code auto-update is on by default for official marketplaces and most other official marketplaces, plus marketplaces added from claude.ai. It is off by default for community, third-party, and local development marketplaces.

Background updates can change files after your review. Running sessions keep loaded versions until reload or the next session, but disk contents can still drift.

For approved plugins, pin the version or commit where possible. For archive sources, use sha256 pinning when available. For internal marketplaces, publish reviewed versions only, and keep an audit trail of what changed between approvals.

3. Confirm Install Scope

Install scope controls blast radius.

  • User scope writes enabledPlugins to ~/.claude/settings.json.
  • Project scope writes .claude/settings.json and affects collaborators.
  • Local scope writes .claude/settings.local.json.

Project scope is the sensitive one for shared repos. It enables the plugin for collaborators, although each user still has to install it. Treat project-scope plugin changes like code that affects every developer's local agent runtime.

Related reading: AGENTS.md vs CLAUDE.md vs Cursor rules.

4. Read The Plugin Details And Local Cache

Use the official review path before installation. Run claude plugin marketplace list, inspect the plugin details pane, and read the source files directly.

After installation or for a local plugin directory, use claude --plugin-dir <dir> plugin details <name> or claude plugin details <name> against the installed cache.

The details pane may tell you a hook exists. It does not tell you everything that hook runs. The source files are the review target.

5. Inspect Hooks First

Hooks are the highest-priority file review. Read hooks/hooks.json line by line.

Command hooks execute shell commands with the user's full permissions. They can read, modify, or delete anything the user account can access. They also run outside the normal Claude tool-call permission model.

Look for hooks on sensitive events such as PreToolUse, PermissionRequest, ConfigChange, and Stop. Those hooks can be useful for policy enforcement, but they can also become an approval bypass, permission rewriter, or hidden execution path.

Reject or sandbox any plugin that uses hooks to change permissions, suppress visible output, call package managers, run shell scripts from remote URLs, write to settings files, or approve actions on the user's behalf.

For enterprise rollout, prefer managed hook policy. Claude Code can restrict hooks with allowManagedHooksOnly. HTTP hooks can be constrained with allowedHttpHookUrls and httpHookAllowedEnvVars.

6. Review MCP Servers And Tool Metadata

Read .mcp.json. Then review every MCP server implementation or remote endpoint the plugin introduces.

MCP is powerful because it gives Claude tools. It is risky because tool names, descriptions, schemas, outputs, errors, OAuth scopes, and server instructions can all influence the agent. A malicious or sloppy MCP server can turn metadata into instructions and tool results into prompt injection.

Check whether the server is local stdio, HTTP, SSE, or remote. Record the package source, executable path, environment variables, OAuth scopes, network destination, and who can change the server behavior.

Important gotcha: project .mcp.json servers prompt for approval in interactive sessions, but Claude Code loads project-scoped servers without that prompt in claude -p, Agent SDK sessions, and cloud sessions. That matters for background agents, CI, and any non-interactive use.

7. Inspect bin/, LSP Servers, And Package Scripts

Anything in bin/ may be added to Bash PATH. Treat it as developer-workstation code.

Review shell scripts, Node packages, Python packages, compiled binaries, install scripts, postinstall hooks, and update scripts. Identify package-manager calls, download-and-execute patterns, dynamic imports, encoded payloads, and writes to shell profiles or Claude settings.

If you cannot inspect the binary or reproduce the build, require sandbox-only use or an internal rebuild from source.

8. Read Skills, Commands, Agents, And Rules As Policy

Skills, commands, agents, and rule files may not execute code directly, but they can steer Claude toward code execution.

Review them for hidden instructions, sensitive file reads, requests to ignore project policy, references to external URLs, tool-use escalation, and instructions that persist into future sessions. Anthropic's enterprise skills review guidance treats scripts inside a skill directory as high risk because they run with full environment access.

Also check whether the plugin adds instructions that make Claude trust MCP output, shell output, or remote content too broadly.

9. Check Settings And Permissions

Review changes to .claude/settings.json, .claude/settings.local.json, user settings, and managed settings. Confirm what the plugin asks to allow, deny, or ask.

Claude Code permission rules are enforced by Claude Code, not by the model. Deny rules evaluate before ask rules, and ask rules evaluate before allow rules. Broad allow rules reduce friction, but they also increase the damage from prompt injection or plugin compromise.

Be especially strict with bypassPermissions. Anthropic says to use it only in isolated containers or VMs because it skips prompts, including protected paths.

10. Map Network Egress And Secrets Access

List every network destination the plugin can reach: MCP endpoints, webhook URLs, package registries, update endpoints, analytics, OAuth flows, and shell commands that call tools such as curl.

Then list the secrets it can touch: API keys, local env files, SSH keys, cloud credentials, GitHub tokens, package registry tokens, and CI secrets. The key question is whether the plugin can read a secret and send it somewhere else without an obvious user approval path.

For OAuth, inspect scopes. For HTTP hooks, constrain allowed URLs and allowed environment variables. For CI or cloud use, assume untrusted markdown, issue content, PR descriptions, and repository files can try to steer the agent.

11. Use Enterprise Scanning, But Do Not Stop There

Enterprise skill and plugin scanning is useful. It scans third-party skills and plugins, plus bundled skills, on upload or edit in supported Claude, Claude Cowork, and Enterprise plugin marketplace surfaces. Results can pass, warn, or fail, and most scans finish in about one to two minutes.

But the exclusions are central to this review. Scanning does not cover MCP servers, hooks, MCP-shared skills, API-uploaded skills, pre-existing assets, or some regulated-data configurations such as CMEK, ZDR, and HIPAA setups.

A pass means the scan did not find the targeted malicious-access-misuse class. It is not a guarantee that the plugin behaves as intended.

12. Apply Supply Chain Controls

For procurement and platform policy, use normal software supply-chain language. The relevant controls are straightforward:

  • Pin refs, releases, archive hashes, or commits.
  • Prefer signed releases and documented provenance where available.
  • Review transitive dependencies and package-manager scripts.
  • Keep an internal record of approved versions.
  • Diff the installed plugin cache after updates.
  • Require owner review before enabling a new marketplace.

Frameworks such as NIST SSDF and SLSA are useful vocabulary here. You do not need to force a heavy process on every plugin, but you do need artifact identity, source traceability, and repeatable review.

Enterprise Controls To Put Around Plugins

The safest team pattern is an allowlisted internal marketplace with reviewed versions and managed settings.

Managed settings can register marketplaces, force-enable approved plugins, allowlist or blocklist marketplace sources, disable --plugin-dir, disable --plugin-url, disable CLAUDE_CODE_PLUGIN_DIRS, limit hooks to managed settings and force-enabled plugins, and stop claude.ai synced plugins from loading.

Use those controls to separate developer choice from platform trust. Developers can request plugins. The platform team decides which sources and versions become available for team use.

Add telemetry. Claude Code supports OpenTelemetry and Analytics API patterns for audit. Be aware of naming redaction behavior for non-official plugins unless you configure enough detail for your inventory needs.

CI, Cloud, And Background Agent Review

CI and cloud runners need a stricter checklist than a local terminal.

In non-interactive sessions, trust prompts may not appear. Project MCP servers can load without the interactive approval prompt. Repository content, issues, pull requests, markdown, logs, and generated files may all become input to an agent with access to runner secrets.

For CI, pin action versions, plugin versions, and MCP server versions. Disable project-defined MCP servers unless explicitly approved. Keep runner secrets minimal. Block broad shell and network access unless the job needs it. Treat untrusted PR branches as hostile input.

Related reading: Claude Code GitHub Actions security checklist.

Common Red Flags

  • A plugin requests broad permissions.allow rules without a narrow workflow reason.
  • A hook changes Claude settings, approval behavior, or permission files.
  • An MCP server has vague tool descriptions or broad OAuth scopes.
  • A binary cannot be traced to source.
  • An install script downloads and runs code from a URL.
  • Auto-update is enabled for a third-party plugin without a review process.
  • The plugin writes instructions into persistent project files.
  • The plugin suppresses output or hides hook behavior from the user.
  • The maintainer cannot explain network egress, dependencies, or release signing.

The Final Review Checklist

Before approval, the reviewer should be able to answer yes to each item below.

  • The plugin source, owner, marketplace, version, and install scope are recorded.
  • The reviewed artifact is pinned by version, commit, ref, or hash where possible.
  • hooks/hooks.json has been read and every command hook is justified.
  • .mcp.json has been reviewed, including server source, scopes, tools, and endpoints.
  • bin/, LSP servers, scripts, and package-manager hooks have been inspected.
  • Skills, commands, agents, and instructions have been checked for hidden policy changes or escalation.
  • Settings and permissions do not grant broad authority without a documented reason.
  • bypassPermissions is blocked outside isolated containers or VMs.
  • Network egress and secrets exposure are mapped.
  • Enterprise scanning results are captured when available, with exclusions noted.
  • Auto-update behavior is known and tied to a re-review process.
  • Managed settings enforce marketplace, hook, and plugin-source policy.
  • Telemetry or audit logging can show plugin use and suspicious changes.
  • CI, cloud, and non-interactive sessions have stricter MCP and secret controls.
  • Rollback steps are documented, including disabling the plugin and cleaning cached files.

The rule is simple: approve the plugin only when its code paths, instruction paths, update paths, and data paths are visible. If one of those paths is unclear, narrow the scope, sandbox it, fork it, or reject it.

Get started

Deploy your fleet.

Put a fleet of sandboxed agents to work on your own infrastructure, provisioned in seconds and watched live from one console.

Get started →

Admin-provisioned · Self-host in one command · Your data never leaves your VM