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

> The scan-plugins GitHub Action automatically scans Claude plugins for security issues in pull requests. Get AI-powered security insights with this non-blocking evaluation tool.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```yaml

# .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:

```yaml
      - 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:

```yaml
      - 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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/action.yml)** — Defines the composite action interface, inputs/outputs, and environment requirements.
- **[`scripts/scan.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/scan.sh)** — Core orchestration script that clones plugins, invokes Claude, parses JSON verdicts, and emits GitHub annotations.
- **[`lib/pin-check.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/lib/pin-check.sh)** — Implements the static analysis that detects floating package-manager commands.
- **[`policy/prompt.md`](https://github.com/anthropics/claude-plugins-community/blob/main/policy/prompt.md)** — The default policy prompt sent to Claude for security evaluation.
- **[`policy/schema.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.