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

> Discover how the static pin check in GitHub Actions safeguards against floating auto-exec MCP server launchers by analyzing source code for unpinned package manager vulnerabilities.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: internals
- Published: 2026-08-25

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/scan-plugins/lib/pin-check.sh)) traverses the plugin directory structure to locate server definitions. It parses:

- [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) files at the repository root or within `.claude-plugin/` directories
- [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```bash

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

```yaml

# .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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) and [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/static-pin-check.sh) for orchestration and [`pin-check.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/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.