How the Static Pin Check Detects Floating Auto-Exec MCP Server Launchers

The static pin check is a GitHub Action that analyzes plugin source code to flag unpinned package manager launchers—such as npx, uvx, or pipx—that would automatically fetch unversioned code at runtime.

In the anthropics/claude-plugins-community repository, security automation prevents external marketplace plugins from executing arbitrary untrusted code. The static pin check inspects MCP server declarations to ensure every auto-execution launcher points to an immutable, pinned dependency rather than a floating version range or latest tag.

How the Detection Pipeline Works

The check operates as a shell-based analysis pipeline defined in .github/actions/scan-plugins/scripts/static-pin-check.sh. It validates that no MCP server configuration relies on unpinned package manager invocations that could introduce supply-chain risks.

Target Discovery and Source Cloning

The process begins by identifying which external marketplace entries require inspection. The resolve_scan_targets function from .github/actions/scan-plugins/lib/targets.sh generates a list of plugins based on the marketplace JSON file and base reference.

For each target, the script clones the repository at the exact commit SHA recorded in the marketplace entry (lines 12-18 of static-pin-check.sh). This guarantees the analysis evaluates the precise code that will be distributed to users, eliminating drift between scan time and execution time.

Collecting Declared MCP Servers

The pin_check_tree function (defined in .github/actions/scan-plugins/lib/pin-check.sh) traverses the plugin directory structure to locate server definitions. It parses:

• .mcp.json files at the repository root or within .claude-plugin/ directories
• plugin.json or .claude-plugin/plugin.json files containing mcpServers objects

For each discovered server, the extractor captures the command binary and its argument array (args) to prepare for launcher classification.

Parsing Launcher Specifications

The detection logic recognizes four primary package manager launchers: npx, bunx, uvx, and pipx (lines 54-58). Helper functions npmspecs, uvxspecs, and pipxspecs (lines 101-145) parse the argument arrays to isolate the package specification string that will be executed.

Classification functions npmclass and pipclass (lines 64-100) categorize each spec into one of several security classes:

• pinned — Exact version constraints (pkg@1.2.3 or pkg==1.2.3)
• floating — Dist-tags (@latest), version ranges (@^1), or bare package names
• bare — Name without version; requires filesystem verification
• vendored, local, vcsref, or none — Alternative safe configurations

Refining Bare Specifications with Filesystem Checks

A bare specification might reference a locally vendored dependency rather than a registry package. The pin_check_refine_bare function (lines 71-92) inspects node_modules/<pkg>/package.json to verify physical presence and ensure the path is not a symbolic link.

If the package exists as a real directory, the classification upgrades to vendored. Otherwise, the spec is demoted to floating, triggering a security flag.

Identifying Floating Launchers

The pin_check_floating_specs function (lines 25-28) filters the classified results to return only entries marked as "floating". If this filtered list contains any entries, the plugin fails the security check unless a valid waiver covers the specific package pattern.

Waiver Processing and Exemptions

When the LAUNCH_SHAPE_WAIVERS environment variable points to a waivers file, the script applies whitelist logic:

1. pin_check_entry_waived (lines 86-95) looks up the plugin slug to determine if exemptions exist
2. pin_check_waiver_prefixes (lines 31-45) retrieves the allowed package prefixes for that entry
3. pin_check_specs_all_waived (lines 50-84) verifies that every floating spec matches at least one allowed prefix

Only when all floating specs are covered by waivers does the check mark the entry as waived and permit the execution.

Result Reporting and Enforcement

The action constructs a pin_scanned JSON payload containing the assessment status, floating spec details, and waiver applications. It renders a summary table to the GitHub Step Summary (lines 78-84) for visibility in pull request checks.

If FAIL_ON_UNPINNED_AUTOEXEC is set to true and any non-waived floating launchers remain, the script terminates with exit code 2, blocking the workflow to prevent potentially unsafe code from reaching the marketplace.

Running the Static Pin Check Locally

You can execute the security scan outside of GitHub Actions to validate plugin configurations during development:

# Clone the community plugins repository

git clone https://github.com/anthropics/claude-plugins-community.git
cd claude-plugins-community

# Configure required environment variables

export MARKETPLACE_PATH=./.github/marketplace.json
export BASE_REF=main
export ALLOWED_HOSTS="github.com"
export FAIL_ON_UNPINNED_AUTOEXEC=true
export ACTION_PATH=.github/actions/scan-plugins
export VALIDATE_LIB=.github/actions/validate-plugins/lib/common.sh

# Execute the static analysis

bash $ACTION_PATH/scripts/static-pin-check.sh

The script generates pin-scanned.json and exits with code 2 if it detects unpinned auto-execution launchers that lack waivers.

Integrating the Check in GitHub Actions

Add the static pin check to your continuous integration workflow to enforce security gates on marketplace submissions:

# .github/workflows/static-pin-check.yml

name: Static Pin Check
on:
  workflow_dispatch:
  pull_request:
    paths:
      - marketplace.json

jobs:
  pin-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run static pin check
        uses: ./.github/actions/scan-plugins
        with:
          marketplace_path: ${{ github.workspace }}/.github/marketplace.json
          base_ref: ${{ github.ref_name }}
          allowed_hosts: "github.com"
          fail_on_unpinned_autoexec: true
          launch_shape_waivers: ${{ github.workspace }}/waivers.txt

This configuration automatically invokes static-pin-check.sh against modified marketplace entries, producing annotations and step summaries for any floating auto-exec MCP server launchers detected.

Summary

• The static pin check prevents supply-chain attacks by ensuring MCP servers do not execute floating package versions at runtime.
• It clones plugin source at the exact SHA specified in the marketplace to analyze the authentic shipping code.
• The detection parses npx, bunx, uvx, and pipx invocations from .mcp.json and plugin.json files, classifying specs as pinned, floating, or vendored.
• Bare specs undergo filesystem verification to distinguish between vendored dependencies and registry packages.
• Floating specs trigger workflow failures (exit code 2) unless explicitly waived via the LAUNCH_SHAPE_WAIVERS mechanism.
• Key implementation files include static-pin-check.sh for orchestration and pin-check.sh for the core classification logic.

Frequently Asked Questions

What constitutes a "floating" auto-exec launcher according to the static pin check?

A floating launcher is any package manager invocation—such as npx package@latest, uvx package>=1.0, or bare pipx run package—that resolves to a mutable version range rather than an immutable digest. The check specifically flags commands lacking exact version pins (e.g., package@1.2.3 or package==1.2.3) because these can silently upgrade to compromised versions between sessions.

How does the check distinguish between vendored dependencies and registry packages?

The pin_check_refine_bare function examines the filesystem for a node_modules/<package>/package.json file that is not a symbolic link. If the package exists as a concrete directory within the repository, the classifier marks it as vendored (safe). If the path is missing or is a symlink pointing outside the tree, the bare spec is reclassified as floating and flagged for review.

Can I whitelist specific floating packages if I trust the source?

Yes. Provide a waivers file via the LAUNCH_SHAPE_WAIVERS environment variable containing per-plugin prefixes that the check should ignore. The pin_check_specs_all_waived function validates that every floating spec matches at least one allowed prefix in the waiver list. Only when all floating specs are covered by waivers will the check permit the launcher to pass.

What exit codes does the static pin check return?

The script returns exit code 0 when all plugins pass the pin check or when all floating specs are properly waived. It returns exit code 2 when FAIL_ON_UNPINNED_AUTOEXEC is enabled and the scan detects non-waived floating auto-exec MCP server launchers. Other non-zero exit codes typically indicate configuration errors, missing dependencies, or cloning failures encountered during target resolution.

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