# Scanner quick start

> Install the scanner, run the main commands, and understand supported ecosystems.

Canonical: https://hol.org/guard/docs/plugin-scanner/quick-start · Updated: 2026-10-23 · Applies to: Guard 3.x

`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`](https://github.com/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.

```bash
pip install plugin-scanner
```

For an isolated shell:

```bash
pipx install plugin-scanner
```

Optional Cisco skill scanning needs Python 3.11 through 3.14:

```bash
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](https://hol.org/guard/docs/plugin-scanner/report-formats-and-ci) for the flags.

## First pass

```bash
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:

```bash
plugin-scanner verify . --online
```

Use `doctor` for targeted diagnostics and a bundle you can attach to a support request or CI run:

```bash
plugin-scanner doctor . --component mcp --bundle dist/doctor.zip
```

## Supported ecosystems

```bash
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.json` surfaces
- 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

## Next guides

- [Ecosystems and repository mode](https://hol.org/guard/docs/plugin-scanner/ecosystems-and-repo-mode)
- [Quality suite commands](https://hol.org/guard/docs/plugin-scanner/quality-suite-commands)
- [Policies, output, and trust provenance](https://hol.org/guard/docs/plugin-scanner/policies-and-output)
- [GitHub Action quality gate](https://hol.org/guard/docs/plugin-scanner/github-action)
- [Guard get started](https://hol.org/guard/docs/guard/get-started)