What is the HOL Plugin Scanner? Checks for agent plugins before release

The HOL Plugin Scanner is an open-source command-line tool, published on PyPI as plugin-scanner, that checks AI agent plugins, skills and MCP configurations for security and quality problems before you publish them. It runs on your machine or in CI through a GitHub Action, and reports findings with a score, a grade and trust provenance.

It is built by HOL and ships from the same repository as HOL Guard. Guard protects agents at runtime. The scanner is the check a maintainer runs before a plugin reaches anyone's agent.

The problem it solves

A plugin for Codex, Claude Code or Gemini CLI is a bundle of manifests, skills, commands and MCP server definitions that an agent loads and trusts. Small mistakes in that bundle travel to every user: an API key left in a config file, an MCP server bound to all interfaces over plain HTTP, an approval default that lets tools run without asking, a GitHub workflow with write permissions it does not need. Marketplaces also reject packages for broken paths, missing screenshots or a missing privacy policy URL. The scanner catches both kinds of problem in one pass, before release.

What the HOL Plugin Scanner checks

From the project README:

• Manifest validation: required fields, versions, declared paths, interface metadata, links and assets.
• Security: hardcoded secrets, unsafe MCP commands and transports, and risky approval defaults.
• Operational security: GitHub Actions permissions and pinned dependencies, privileged checkout patterns, Dependabot and lockfiles.
• Packaging: README and license files, skill frontmatter, ignore rules and accidentally committed environment files.
• Marketplace: manifest validity, local package discovery and safe source paths.
• Code quality: dynamic code execution and shell-injection patterns.
• Optional Cisco integrations for deeper skill and MCP analysis.

The HOL Guard page adds that bundled skills are scanned for prompt-injection markers, zero-width characters, dangerous shell commands and secret leaks, and that MCP checks flag insecure HTTP endpoints, wildcard binds and missing auth.

Supported plugin ecosystems

The scanner detects six package formats on its own: Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code and OpenCode. Point it at a repository and it finds them, or pass --ecosystem to pick one. At a Codex marketplace root it discovers each local plugin entry automatically. plugin-scanner --list-ecosystems prints the current list.

The five commands

• scan: security findings and a quality report across the package.
• lint: rule-level authoring feedback, with --explain for a single rule and --fix for supported mechanical fixes.
• verify: install-surface and runtime readiness. --online allows live probes of remote HTTP MCP servers; stdio servers are not executed and are left for manual review.
• submit: a scan, verify and policy gate that writes a plugin-quality artifact for one plugin.
• doctor: component diagnostics and a zipped troubleshooting bundle.

Reports come out as text, JSON, Markdown or SARIF, and policy profiles are default, public-marketplace and strict-security.

How to get started

The scanner needs Python 3.10 or newer. From the scanner quick start:

pipx install plugin-scanner
plugin-scanner scan .
plugin-scanner lint .
plugin-scanner verify .

To fail a build on serious findings, or to feed GitHub code scanning:

plugin-scanner scan . --fail-on-severity high
plugin-scanner scan . --format sarif --output plugin-scanner.sarif

Per-repository settings go in .plugin-scanner.toml, including the profile, a baseline file for accepted findings, ignored paths and per-rule severity overrides.

Run it in GitHub Actions

The AI Plugin Scanner Action wraps the same CLI for pull requests:

- uses: hashgraph-online/ai-plugin-scanner-action@v1
  with:
    plugin_dir: "."
    min_score: 80
    fail_on_severity: high

The action's README recommends pinning it to a full commit SHA or an immutable v1.x.y tag rather than the floating v1. It installs an exact plugin-scanner release and verifies the wheel's hash and PyPI provenance before running. With the default online: false, scans read only local repository content and external analyzer keys are removed from the environment. Outputs include score, grade, max_severity and findings_total, and upload_sarif: true sends findings to code scanning.

Scores, trust and the Plugins Registry

Each scan reports a quality grade normalized across the checks that apply to that package, so optional surfaces do not inflate it. Trust is scored separately with documented provenance. Bundled skills use the HCS-28 baseline weights, and MCP and plugin trust use their own published adapters. Plugins that pass can show Scanner Clean, MCP Hardened and Marketplace Ready badges.

The HOL Plugins Registry shows scanner-backed signals next to every listing. HOL says plainly that a scan is not a safety guarantee, and that the public catalog score is a static scan, not a live exploit test. Running the scanner yourself in CI gives you the full report on your own code, not just the catalog summary.

Who it is for

Plugin authors and marketplace maintainers who publish for Codex, Claude Code, Gemini CLI, Kimi Code, OpenCode or DeepSeek Harness. If you only use plugins and want protection while your agent runs them, install HOL Guard instead. Maintainers who also run agents can use both.

What it is not

The scanner is static analysis plus optional reachability probes. It does not run your plugin's code in a sandbox, does not execute stdio MCP servers, and cannot prove a plugin is safe. It also does nothing at runtime on a user's machine; that is Guard's job.

If you used the older codex-plugin-scanner or the hashgraph-online/ai-plugin-scanner repository: that repository is archived and points to hol-guard. The package name plugin-scanner did not change, and the codex-plugin-scanner command still works as an alias.

FAQ

Is the HOL Plugin Scanner free and open source?

Yes. It is Apache-2.0, installs from PyPI as plugin-scanner, and its source lives in hashgraph-online/hol-guard.

Which plugin formats does it support?

Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code and OpenCode packages, plus skills and MCP server configuration inside them. It can scan one plugin or a whole marketplace repository.

What is the difference between the Plugin Scanner and HOL Guard?

Install plugin-scanner to check plugin packages and gate releases in CI. Install hol-guard to review what an AI agent does on your machine at runtime. The same repository builds both.

Does a passing scan mean a plugin is safe?

No. A pass means the package cleared the checks that apply to it. HOL describes scores as signals, not a safety guarantee, and the scanner does not run a live exploit test.

Can I use it in GitHub Actions?

Yes. Use hashgraph-online/ai-plugin-scanner-action, pinned to a commit SHA or release tag, with min_score and fail_on_severity to block pull requests. It can also upload SARIF to GitHub code scanning.

Does the scanner send my code anywhere?

Not by default. scan, lint and offline verify work on local files. Network access happens only when you opt in, for example with verify --online or the action's online and submission settings.