How to Configure the allowed-hosts Parameter for Claude Plugin Source URL Validation

The allowed-hosts parameter is a space-separated whitelist that prevents Server-Side Request Forgery (SSRF) attacks by restricting which Git hosts the Validate Plugins and Scan Plugins actions can clone from, defaulting to github.com gitlab.com bitbucket.org.

Configuring the allowed-hosts parameter in the anthropics/claude-plugins-community repository allows you to safely extend plugin validation to private Git servers while maintaining strict security controls. This input parameter acts as a critical security guard that validates every source URL before executing git clone or git fetch commands in your CI pipelines.

Understanding the allowed-hosts Security Parameter

The allowed-hosts input serves as an SSRF protection mechanism implemented in both the Validate Plugins and Scan Plugins GitHub actions. Before any Git operation occurs, the host portion of the repository URL undergoes validation against this whitelist.

allowed-hosts rejects bare IP addresses automatically, regardless of whitelist contents, forcing the use of proper DNS hostnames. If a plugin source URL points to a host not present in the allowed list, the action aborts immediately with an error, preventing malicious redirects from compromising your CI environment.

The default value permits only major public Git hosting services:

github.com gitlab.com bitbucket.org

Where allowed-hosts is Defined in the Source Code

According to the anthropics/claude-plugins-community source code, the parameter definition appears in multiple locations to ensure consistent security enforcement.

Validate Plugins action: The input definition resides at line 23 of .github/actions/validate-plugins/action.yml, with accompanying documentation in the README at line 23.

Scan Plugins action: An identical input definition exists at line 30 of .github/actions/scan-plugins/action.yml, documented at line 30 of its respective README.

Implementation logic: The actual enforcement occurs in .github/actions/validate-plugins/lib/common.sh via the assert_safe_host helper function. This shell function parses the space-separated host list and performs the security check before passing URLs unchanged to Git commands.

How to Override allowed-hosts in Your Workflow

To customize the whitelist, supply the allowed-hosts input when invoking either action in your workflow file. The value accepts a space-separated string of hostnames without commas or quotes around individual entries.

The parameter override follows standard GitHub Actions syntax:

- uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@<PINNED-SHA>
  with:
    allowed-hosts: "github.com gitlab.com bitbucket.org git.mycorp.com"

When adding private hosts, always include the public defaults if you still need to validate plugins from GitHub, GitLab, or Bitbucket alongside your internal repositories.

Practical Examples for Private Git Hosts

Organizations hosting private plugin repositories on self-managed Git servers must expand the default whitelist. Below are production-ready workflow configurations demonstrating proper allowed-hosts usage.

Basic Workflow with Custom Hosts

This example validates plugins while allowing sources from an internal Git server:

# .github/workflows/validate-plugins-custom.yml

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@<PINNED-SHA>
        with:
          allowed-hosts: "github.com gitlab.com bitbucket.org internal-git.example.com"

Nightly Drift Detection Workflow

Use this configuration for scheduled validation of all external plugins while maintaining host restrictions:

# .github/workflows/validate-plugins-nightly.yml

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@<PINNED-SHA>
        with:
          validate-all-external: "true"
          skip-local-folders: "true"
          allowed-hosts: "github.com gitlab.com bitbucket.org git.mycorp.com"

Scan Plugins Configuration

The Scan Plugins action uses identical syntax for host validation:

# .github/workflows/scan-plugins.yml

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@<PINNED-SHA>
        with:
          allowed-hosts: "github.com gitlab.com bitbucket.org git.mycorp.com"
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Summary

• The allowed-hosts parameter in anthropics/claude-plugins-community prevents SSRF attacks by whitelisting permissible Git hosts before cloning operations.
• Default hosts are github.com gitlab.com bitbucket.org, defined in action.yml files at lines 23 and 30 for the validate and scan actions respectively.
• The assert_safe_host function in common.sh enforces the whitelist and automatically rejects bare IP addresses.
• Supply a space-separated list of hostnames to override defaults when validating plugins from private Git servers.
• Both Validate Plugins and Scan Plugins actions accept identical allowed-hosts syntax.

Frequently Asked Questions

What happens if a plugin source URL is not in the allowed-hosts list?

The action aborts execution with an error before initiating any Git operations. As implemented in the assert_safe_host helper within common.sh, the validation check occurs immediately after parsing the URL, protecting the CI runner from cloning untrusted repositories.

Why are bare IP addresses automatically rejected?

The security implementation treats IP addresses as inherently higher-risk vectors for SSRF attacks and redirection exploits. According to the source code logic in the validation helpers, this restriction ensures that all plugin sources must resolve through DNS hostnames, providing an additional layer of accountability and traceability for external dependencies.

Can I use wildcards or regular expressions in the allowed-hosts list?

No, the allowed-hosts parameter requires exact hostname matches. The assert_safe_host function performs literal string comparisons against the space-separated list provided. For subdomains, you must explicitly list each hostname (e.g., plugins.internal.com and api.internal.com require separate entries).

How do I verify my allowed-hosts configuration is working correctly?

Test your configuration by referencing a plugin from a host not included in your whitelist. The action should fail immediately with a clear error message indicating the disallowed host. For private repositories, ensure your CI runner has network access to the listed hosts and that DNS resolution functions correctly before relying on the whitelist for production validation pipelines.

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