What Security Checks Are Performed by the `scan-plugins` GitHub Action in Claude Plugins Community

The scan-plugins GitHub Action performs automated safety validations including static pin-checks for URL/SHA integrity and AI-based policy scanning using Anthropic's Claude model before merging plugin changes.

The scan-plugins GitHub Action is a critical security gate in the anthropics/claude-plugins-community repository. This action runs automatically on pull requests that modify plugin definitions, ensuring that only vetted, safely-sourced code enters the ecosystem. Understanding what security checks are performed by the scan-plugins GitHub Action helps contributors prepare compliant submissions and helps security teams replicate similar controls.

Static Pin-Check Validation

Before any AI analysis begins, the action performs rigorous static validation in scan.sh. These checks enforce supply-chain security fundamentals.

Required Field Validation

Every plugin entry must contain both a url and sha field. The script at .github/actions/scan-plugins/scripts/scan.sh line 72 emits a warning and skips any entry missing these required fields:

scan-plugins: ... has no url or sha; skipping

URL Security Enforcement

Two URL-based checks run sequentially:

• Scheme validation (line 79): Only https:// URLs are permitted. Non-HTTPS schemes trigger scan-plugins: ... url unsafe; skipping
• Host allow-listing (line 85): The URL's host must appear in a built-in whitelist. Unknown hosts trigger scan-plugins: ... host not in allowlist; skipping

SHA Format Verification

The sha field must match a valid 40-character Git commit SHA. Malformed SHAs at line 89 produce: scan-plugins: ... sha malformed; skipping

Sub-Directory Path Sanitization

The optional subdir field undergoes traversal and character checks. Unsafe paths at line 93 trigger: scan-plugins: ... subdir unsafe; skipping

Repository Integrity Verification

After static checks pass, the action clones and validates the actual plugin source.

Git Operations Check

The script attempts to clone, fetch, and checkout the repository at the specified SHA. Failures at line 102 emit: scan-plugins: ... clone/fetch/checkout failed; skipping

Sub-Directory Existence Check

If a subdir is declared, the action verifies it exists in the checked-out tree. Missing directories at line 107 trigger: scan-plugins: ... subdir not found at sha; skipping

Claude-Based Policy Scan

The second major component sends plugin source code to Anthropic's Claude model for safety analysis.

Authentication-Conditional Execution

The policy scan runs only when credentials are present. As declared in action.yml line 139:

no Anthropic auth (anthropic-api-key or anthropic-federation-rule-id) configured; skipping policy scan.

AI Response Parsing

The action attempts to parse Claude's structured verdict. Parsing failures at line 128 produce: scan-plugins: ... could not parse verdict; raw output in step log

Policy Violation Handling

Claude's assessment produces two severity levels:

• Blocking violations (line 159): Fail the CI job with scan-plugins: ... FAILS policy — ...
• Non-blocking violations (line 161): Emit warnings with scan-plugins: ... fails policy (non-blocking) — ...

Implementing the scan-plugins Action

Add the action to your workflow with optional authentication:

# .github/workflows/validate-plugins.yml

name: Validate Plugins
on:
  pull_request:
    paths:
      - '.claude-plugin/**'
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Scan plugins
        uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@<PINNED-SHA>
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Without ANTHROPIC_API_KEY or ANTHROPIC_FEDERATION_RULE_ID, the policy scan becomes a no-op while static checks still execute.

Key Source Files

File	Purpose
.github/actions/scan-plugins/scripts/scan.sh	Core validation logic and warning generation
.github/actions/scan-plugins/action.yml	Action interface and authentication handling
.github/workflows/validate-plugins.yml	Workflow triggering the action on plugin changes
.github/actions/scan-plugins/README.md	Usage documentation and security posture explanation

Summary

• The scan-plugins GitHub Action combines static supply-chain validation (URL scheme, host allow-list, SHA format, path safety) with AI-powered policy review
• All checks execute in scan.sh with explicit warning messages at lines 72, 79, 85, 89, 93, 102, 107, 128, 159, and 161
• The Claude policy scan is opt-in via environment credentials as controlled by action.yml
• The action fails fast on blocking violations while surfacing non-blocking issues as warnings
• Repository integrity is verified through actual Git clone/checkout operations, not just string validation

Frequently Asked Questions

What happens if I forget to include a SHA in my plugin submission?

The action logs scan-plugins: ... has no url or sha; skipping and bypasses that plugin entry. The CI job may still pass, but your plugin won't be validated or merged until both fields are present.

Can I use a non-HTTPS URL for my plugin repository?

No. The static check at line 79 explicitly rejects non-HTTPS schemes as unsafe. You must host your plugin on HTTPS-enabled infrastructure included in the allow-list.

Does the action work without Anthropic credentials?

Yes. The static pin-checks run regardless, but action.yml line 139 confirms the policy scan is skipped when neither anthropic-api-key nor anthropic-federation-rule-id is configured. This allows forks to use the action without AI capabilities.

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