hol-guard MCP工具

Install HOL Guard

Requires Python 3.10 or newer and pipx.

pipx install hol-guard
hol-guard init

The first-run wizard discovers supported agents and walks you through protection setup. It asks before each setup change, including opening the dashboard, installing agent integrations, and connecting optional cloud services.

Check your installation:

hol-guard --version
hol-guard status

To update an existing installation:

hol-guard update

For manual setup, see the installation guide. Release details and prereleases are on the releases page.

CLI Usage

```bash

Config + Baseline Example

Configure the scanner in .plugin-scanner.toml:

[scanner]
profile = "public-marketplace"
baseline_file = "baseline.txt"
ignore_paths = ["tests/*", "fixtures/*"]

[rules]
disabled = ["README_MISSING"]
severity_overrides = { CODEXIGNORE_MISSING = "low" }

The GitHub Action requires trust_repository_policy: true before repository-owned configuration and baselines can change its verdict. Enable that option only for policy you intend the workflow to trust.

Optional Cisco analysis

The baseline packages work without Cisco dependencies. To add Cisco skill scanning, use Python 3.11 through 3.14 and install the extra in an isolated environment:

pipx install 'plugin-scanner[cisco]'

For Cisco MCP analysis, use the repository's Docker image or the cisco-mcp dependency group:

uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13
uv run plugin-scanner scan . --cisco-skill-scan on --cisco-mcp-scan on

The published cisco extra provides skill scanning; the separate cisco-mcp group supplies the MCP scanner. Dependency versions and Python constraints are maintained in pyproject.toml.

Check a package

hol-guard supply-chain sync
hol-guard supply-chain scan
hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm

The package verdict includes the available advisory evidence and ecosystem coverage. See the get-started guide for package-manager interception and the remediation guide for handling false positives.

<a id="scanner-quickstart"></a> <a id="choose-the-right-package"></a>

Plugin Scanner

This repository also ships plugin-scanner, a CLI for maintainers who want security and quality checks before publishing agent plugins, skills, and MCP integrations.

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

The scanner detects Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code, and OpenCode package formats. Use plugin-scanner --list-ecosystems to list them or --ecosystem to select one. At a Codex marketplace root, it discovers local plugin entries automatically.

Checks cover manifests, secrets, MCP transport and command configuration, approval defaults, skills, dependency lockfiles, and GitHub Actions permissions. Optional Cisco integrations add skill and MCP analysis. Reports support text, JSON, Markdown, and SARIF.

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

Quality grades use the checks applicable to each package. Trust scoring has separate provenance and weights; see the skill, MCP, and plugin scoring references.

<a id="ci-and-automation"></a>

Verify package readiness; --online permits live probes

plugin-scanner verify ./my-plugin --format json plugin-scanner verify ./my-plugin --online --format text

Generate a submission artifact for one plugin

plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json

Collect component diagnostics

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

For a repository marketplace, scan, lint, verify, and doctor can target the root. submit targets one plugin package.

Plugin Author Submission Flow

Use submission_enabled: true to open or reuse a submission issue when a plugin meets the configured threshold. submission_token must have permission to create issues in the target submission repository. The action emits submission status and issue URLs as outputs.

See the action's input reference for submission_score_threshold, submission_token, and the target repository options.

Registry Payload For Plugin Ecosystem Automation

Set registry_payload_output to write a machine-readable payload for a registry or badge pipeline. The action also exposes score, grade, grade_label, max_severity, and findings_total outputs and can write a job summary.

The HOL Registry Broker plugin is an example of an agent plugin in the HOL Plugin Registry. Its registry listing provides current trust information.

What is the difference between HOL Guard and Plugin Scanner?

Install hol-guard to protect agent activity on your machine. Install plugin-scanner to inspect plugin packages and enforce security and quality checks in CI. This repository builds and publishes both distributions.

Contribute a New Extension

Use the Extension Builder CLI to turn exported command metadata or an MCP tool inventory into contribution files and tests. It works offline: it reads the export without importing or running the target tool.

1. Propose the coverage. Check the Extension directory for existing coverage. For a new capability, open an Extension proposal with the proposed command.<name> ID, supported operations, destructive examples, safe counterparts, and upstream references. Extend an existing extension when it already owns the operation.

Follow the development setup, then run the examples below from your HOL Guard checkout. uv run --no-sync uses that checkout's installed development version.

2. Generate a contribution kit. This example uses the checked-in, synthetic samplectl inventory. For your own contribution, replace the input and metadata with your tool's export and public publisher details.

uv run --no-sync hol-guard extensions generate --from cli \
  --input docs/guard/extension-builder/examples/cli-surface.json \
  --slug samplectl --executable samplectl --name 'Sample CLI' \
  --publisher community.example --publisher-name 'Example Maintainer' \
  --homepage https://example.test/samplectl \
  --upstream-version 1.0.0 --output samplectl-kit

uv run --no-sync hol-guard extensions validate samplectl-kit

The output directory must be new, with an existing parent directory. The kit includes discovery.json, review.json, report.json, contribution metadata, a native detector, generated tests, and a file manifest.

Other inputs: --from help reads saved command help; --from click reads a Click Context.to_info_dict() export; --from oclif reads oclif.manifest.json; --from mcp reads a complete exported tools/list result; and --from snapshot replays discovery.json. The cli example above uses normalized guard.cli-surface.v1 JSON.

For MCP contributions, the generator uses --launcher and --package instead of --executable. See the MCP kit example for a complete command and pagination requirements.

3. Review the operations and regenerate. Read report.json and compare the discovered operations with the upstream implementation. Copy the review file before editing:

cp samplectl-kit/review.json samplectl-review.json

Edit samplectl-review.json, keeping its discovery binding and operation IDs intact. CLI operations use review or block; the root operation stays review. Set reviewed: true for entries you have assessed, with rationale and a public HTTPS evidence reference. Add safeArgv only for exact, verified safe invocations. The review format includes a complete entry example.

Recompile from the saved snapshot rather than editing generated detectors or manifests:

uv run --no-sync hol-guard extensions generate --from snapshot \
  --input samplectl-kit/discovery.json \
  --review samplectl-review.json --output samplectl-reviewed

uv run --no-sync hol-guard extensions validate samplectl-reviewed
uv run --no-sync hol-guard extensions diff samplectl-kit samplectl-reviewed

diff exits 0 for equal kits and 1 when valid kits differ. If the upstream export changes, generate and review a new snapshot.

4. Preview and apply the integration. On your contribution branch, preview the changes to the current checkout:

uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .

Inspect the listed paths and generated files. Copy the printed plan digest into the following command before running it:

uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo . \
  --expected-plan THE_PRINTED_PLAN_DIGEST \
  --write

The write applies the reviewed plan to contribution files, the external trust map, catalog registration, packaging, and authoring ownership records. Existing IDs or conflicting files stop integration for review.

5. Test and submit a pull request. For the samplectl example:

uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
uv run --no-sync pytest -q tests/test_generated_cli_samplectl_extension.py
uv run --no-sync pytest -q \
  tests/test_guard_extension_contribution.py \
  tests/test_guard_extension_trust.py \
  tests/test_guard_command_extension_registry.py
uv run --no-sync python scripts/render_command_extension_directory.py
uv run --no-sync python scripts/render_command_extension_directory.py --check
git diff --check

Use your generated test filename for a different slug. Add cases for destructive operations, safe previews, aliases, reordered flags, quoting, malformed input, and compound commands. Run lint and formatting checks on changed Python files. Inspect the final diff, commit the integration and regenerated directory, and open a PR against main linking the proposal and test results. Include the generated authoring records; keep scratch kit directories and raw upstream exports out of the PR.

Community contributions remain External and off by default. Tests must prove they are inert until a local administrator enables them. Generating, applying, or merging a contribution does not activate it, and its detector cannot weaken Guard's required protections.

Full builder reference · Contribution review requirements · External extension contract · Builder validation

<a id="quick-start-for-contributors"></a>

Frequently Asked Questions