plugin-scanner is the maintainer and CI-facing quality suite for AI plugin repositories. Use it after a plugin is scaffolded and before release, registry ingestion, or GitHub review.
The scanner lives in the hashgraph-online/hol-guard repository. The plugin-scanner and hol-guard PyPI packages are built from that one repository and share a version number. The older hashgraph-online/ai-plugin-scanner repository only points to it.
Install
The scanner needs Python 3.10 or newer.
pip install plugin-scanner
For an isolated shell:
pipx install plugin-scanner
Optional Cisco skill scanning needs Python 3.11 through 3.14:
pipx install 'plugin-scanner[cisco]'
The cisco extra covers skill scanning only. Cisco MCP analysis needs the cisco-mcp dependency group in a source checkout or the container image. See Report formats and CI automation for the flags.
First pass
plugin-scanner lint .
plugin-scanner verify .
plugin-scanner scan . --format json
A bare path runs scan, so plugin-scanner . is the same as plugin-scanner scan ..
Add online probing when you want HTTP remote endpoints checked over the network:
plugin-scanner verify . --online
Use doctor for targeted diagnostics and a bundle you can attach to a support request or CI run:
plugin-scanner doctor . --component mcp --bundle dist/doctor.zip
Supported ecosystems
plugin-scanner --list-ecosystems
The built-in adapters are Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code, and OpenCode. Each one detects packages from its own manifest files:
| Ecosystem | --ecosystem value | Detection surfaces |
|---|---|---|
| Codex | codex | .codex-plugin/plugin.json, .agents/plugins/marketplace.json, marketplace.json |
| Claude Code | claude | .claude-plugin/plugin.json, .claude-plugin/marketplace.json |
| DeepSeek Harness | deepseek-harness (alias dsh) | package.json with a dsh.bundle object |
| Gemini CLI | gemini | gemini-extension.json |
| Kimi Code | kimi | kimi.plugin.json, .kimi-plugin/plugin.json |
| OpenCode | opencode | opencode.json, opencode.jsonc, .opencode/ |
Core commands
| Command | Purpose |
|---|---|
scan | weighted repository or plugin scan with policy evaluation |
lint | rule-level findings, --list-rules, --explain, and safe autofix with --fix |
verify | manifest, marketplace, MCP, skill, app, and asset readiness checks, with optional --online probing |
submit | scan, verify, and policy gate that writes a plugin-quality.v1 artifact |
doctor | offline diagnostics and troubleshooting bundles |
Repository mode
If the repository has a Codex marketplace file at .agents/plugins/marketplace.json, run the scanner from the repository root. It discovers local ./plugins/... entries, scans each local plugin manifest, and skips remote marketplace entries instead of treating the root as one plugin. In the GitHub Action, keep plugin_dir: "." for the same behavior.
What it checks
plugin-scanner covers:
- plugin manifests and marketplace metadata
- MCP remote HTTP configuration, and stdio server declarations flagged for manual review
- skills, assets, and
.app.jsonsurfaces - security posture such as secrets, dangerous commands, GitHub Actions pinning and permissions, and dependency lockfiles
- trust provenance for skills, MCP configuration, and top-level plugin packages