Purpose of the scan-plugins GitHub Action: AI Security Scanning for Claude Plugins

The scan-plugins GitHub Action is a Claude-based policy scanner that automatically evaluates external marketplace plugins in pull requests, surfacing security concerns through GitHub annotations while remaining non-blocking by default.

The scan-plugins GitHub Action in the anthropics/claude-plugins-community repository provides an automated safety gate for Claude marketplace plugins. This CI/CD component leverages Anthropic's Claude AI to perform intelligent code review on plugin changes, ensuring potential security or policy violations are caught before merging into the main branch.

What scan-plugins Does in CI/CD

The scan-plugins action operates as a specialized Claude-based policy/safety scanner designed to evaluate any external marketplace plugins that have been added or changed in a pull request. It complements existing automation such as validate-plugins and bump-plugin-shas by providing an AI-driven layer of security review that examines both the plugin’s code and its manifest.

According to the source code in .github/actions/scan-plugins/README.md, the action is designed to be non-blocking by default. Findings appear as GitHub ::warning annotations and in a step-summary table, allowing teams to incrementally adopt the tool. Setting the fail-on-findings: true input converts warnings into hard failures that block the job.

How the scan-plugins GitHub Action Works

The action executes a five-step workflow defined in the repository documentation:

1. Identify changed external plugins (or scan all plugins during a nightly sweep).
2. Clone each plugin at its pinned SHA into an isolated temporary directory to ensure reproducible analysis.
3. Run claude -p headlessly with the policy prompt to evaluate security and compliance.
4. Parse the JSON verdict and emit GitHub warnings or errors based on the findings.
5. Summarize results in a step-summary table for easy review in the GitHub UI.

This workflow is orchestrated by scripts/scan.sh, which handles the coordination between plugin discovery, Claude invocation, and result formatting.

Security Features and Policy Enforcement

AI-Driven Policy Review

At the core of scan-plugins is an AI policy engine that uses the bundled policy/prompt.md file to solicit a simple pass/fail verdict from Claude. Organizations can override this default behavior by providing a custom policy prompt via the policy-prompt input, allowing tailored security policies without modifying the action itself. The expected response format is validated against policy/schema.json.

Static Pin Check for Floating Commands

Independent of the AI review, the action performs a critical static analysis implemented in lib/pin-check.sh. This check flags any “floating” package-manager commands (such as unpinned npx or pipx invocations) that could execute untrusted code at runtime. This provides an immediate, deterministic safety layer beyond the AI evaluation.

Configurable Blocking Behavior

By default, violations surface as annotations and table entries without failing the workflow. Teams can opt into hard enforcement by setting fail-on-findings: true in their workflow configuration, making the scanner a mandatory quality gate.

Configuration and Usage Examples

Basic Pull Request Scanning

Add the scanner to any workflow that touches plugin definitions:

# .github/workflows/scan-plugins.yml

name: Scan Plugins
on:
  pull_request:
    paths:
      - '.claude-plugin/**'

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read          # needed to checkout the repo

      id-token: write         # only if using WIF auth

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@<PINNED-SHA>
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Nightly Full Sweep of All External Plugins

For comprehensive security audits, scan every external plugin regardless of recent changes:

      - uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@<PINNED-SHA>
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          scan-all-external: "true"

Custom Policy Prompts

Override the bundled policy with organization-specific rules:

      - uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@<PINNED-SHA>
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          policy-prompt: .github/policy/prompt.md

Authentication Methods

The action supports two authentication modes defined in action.yml:

• Anthropic API Key: Pass via the anthropic-api-key input.
• Workload Identity Federation (WIF): Use anthro-federation-rule-id for short-lived credential exchange.

If no credentials are configured, the action skips gracefully, allowing the workflow to be added universally without immediate credential rollout.

Core Implementation Files

The scan-plugins GitHub Action consists of several key components:

• action.yml — Defines the composite action interface, inputs/outputs, and environment requirements.
• scripts/scan.sh — Core orchestration script that clones plugins, invokes Claude, parses JSON verdicts, and emits GitHub annotations.
• lib/pin-check.sh — Implements the static analysis that detects floating package-manager commands.
• policy/prompt.md — The default policy prompt sent to Claude for security evaluation.
• policy/schema.json — JSON schema defining the expected structure of Claude’s verdict response.

Summary

• The scan-plugins GitHub Action provides AI-augmented security scanning for Claude marketplace plugins, running automatically on pull request changes.
• It operates non-blocking by default but can be configured to fail builds via the fail-on-findings input.
• The action performs dual-layer validation: an AI policy review via Claude and a deterministic static pin check for floating commands.
• Authentication requires only an Anthropic API key or Workload Identity Federation, with graceful degradation if credentials are absent.
• Organizations can customize security policies by overriding the bundled policy/prompt.md with repository-specific rules.

Frequently Asked Questions

Is scan-plugins a blocking check by default?

No. By default, the action emits findings as GitHub ::warning annotations and includes them in a step-summary table without failing the workflow. You must explicitly set fail-on-findings: true to block merges on violations.

What credentials does scan-plugins require?

The action requires either an anthropic-api-key or a Workload Identity Federation rule ID (anthro-federation-rule-id). If neither is provided, the action skips execution gracefully, allowing teams to deploy the workflow across repositories before completing credential distribution.

Can I use a custom security policy instead of the default one?

Yes. While the action bundles a minimal policy prompt in policy/prompt.md, you can override it by providing a file path via the policy-prompt input. This allows organizations to enforce specific compliance requirements without forking the action.

What is the static pin check and why does it matter?

The static pin check, implemented in lib/pin-check.sh, scans for unpinned package-manager commands (like npx or pipx without explicit version SHAs) that could execute arbitrary code. This check runs independently of the AI review and provides deterministic protection against supply-chain attacks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}