hol-guard MCP工具

How do I require human proof before saved approvals?

Enable the local approval gate when saved allow decisions, global trust, policy clears, or settings changes should require a human password before Guard persists them:

hol-guard settings approval-password enable \
  --new-password '<password>' \
  --confirm-password '<password>' \
  --cooldown-seconds 900
hol-guard settings approval-password status

Use cooldown only for ordinary non-global allow decisions. Guard still requires fresh proof for global allow, policy clear, settings import/reset, disabling the gate, disabling TOTP, and recovery. When TOTP is enabled, cooldown is disabled so every protected action requires both factors. To unlock or lock the current password-only approval window from a terminal:

hol-guard approvals unlock --duration 15m
hol-guard approvals lock

For Google Authenticator-compatible second-factor proof, enroll TOTP after the password gate is enabled:

hol-guard settings approval-totp enroll --current-password '<password>' --device-label '<device>'
hol-guard settings approval-totp verify --current-password '<password>' --code 123456
hol-guard settings approval-totp status

TOTP uses SHA-1, 6 digits, 30-second steps, and a Base32 otpauth://totp/HOL%20Guard:<device> provisioning URI. Guard stores the seed encrypted locally, rejects replayed steps, and never includes the seed in settings export, receipts, or public status. Disabling TOTP or the password gate requires fresh password proof plus a current TOTP code when TOTP is enabled.

Require Cisco skill scanning with a strict policy

plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict

Require optional Cisco MCP static analysis

plugin-scanner scan ./my-plugin --cisco-mcp-scan on ```

Use the bare plugin-scanner ./my-plugin form only for compatibility with older automation. New scripts and docs should prefer explicit subcommands so scan, lint, verify, submit, and doctor have predictable help, flags, and output.

Install The Package You Need

Lean baseline install

Guard package:

pip install hol-guard

Scanner package:

pip install plugin-scanner

The lean baseline keeps Python 3.10+ support intact. It includes the shipped cisco-ai-skill-scanner integration on Python 3.10 through 3.13; on Python 3.14+ Guard installs without the LiteLLM-dependent Cisco scanner path and reports Cisco evidence as unavailable until patched LiteLLM releases support that runtime.

Guard Quickstart

pipx install hol-guard
hol-guard init

To update an existing pipx install from PyPI:

pipx upgrade hol-guard

If you installed Guard with pipx, verify the active user command before testing local flows:

command -v hol-guard
hol-guard --version

For a local wheel build, install into the pipx-managed hol-guard environment. Do not test with PYTHONPATH=src; that bypasses the same package path users run.

python3 -m build --wheel
hol-guard update --wheel dist
hol-guard --version

hol-guard update --wheel accepts either a specific .whl file or a directory and picks the newest matching hol_guard-*.whl.

To force a specific release, use Python package specifier syntax:

pipx install --force 'hol-guard==2.0.345'

Do not use hol-guard@<version>; pipx treats that as a separate app name, not a package version.

hol-guard init is the first-run guided setup. It shows a progressive plan first, then gates each side effect: approve dashboard, Guard completes it, then approve app protection, Guard completes it, then approve Cloud connect and notifications. Nothing opens or changes until you approve that checkpoint. Use hol-guard init --yes only for automation when you already trust the plan.

Manual and follow-up commands:

pipx run hol-guard bootstrap
pipx run hol-guard hermes bootstrap
pipx run hol-guard run codex --dry-run
pipx run hol-guard run codex
pipx run hol-guard approvals
pipx run hol-guard receipts
pipx run hol-guard status
pipx run hol-guard connect
pipx run hol-guard connect status
pipx run hol-guard connect repair
pipx run hol-guard sync
pipx run hol-guard supply-chain sync
pipx run hol-guard supply-chain scan
pipx run hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm
pipx run hol-guard explain install-connect

What you get from Guard:

• Detects local harness config on your machine
• Records a baseline before you trust a tool
• Pauses cleanly on new or changed artifacts before launch
• Queues blocked changes in a localhost approval center when the harness cannot prompt inline
• Stores receipts locally so you can review decisions later
• Keeps sync optional until you actually want shared history

See docs/guard/get-started.md for the full local flow.

<details> <summary>Guard commands at a glance</summary>

- hol-guard start Shows the next step for the harnesses Guard found. - hol-guard init Runs first-run onboarding as approval checkpoints: local dashboard, harness discovery and install, optional Guard Cloud connect, and desktop notification setup. - hol-guard bootstrap Detects the best local harness, starts the approval center, and installs Guard in front of it. - hol-guard hermes bootstrap Installs the Guard-managed Hermes overlay bundle directly. - hol-guard status Shows what Guard is watching now. - hol-guard install <harness> Creates the launcher shim for that harness. - hol-guard uninstall --self Removes Guard-managed harness wiring, package shims, local Guard state, and uninstalls the current hol-guard package. - hol-guard update Updates the installed hol-guard package in the current environment. - hol-guard run <harness> --dry-run Records the current state once before you trust it. - hol-guard run <harness> Reviews changes before launch and hands blocked sessions to the approval center when needed. - hol-guard approvals Lists pending approvals or resolves them from the terminal. - hol-guard receipts Shows local approval and block history.

</details>

<details> <summary>Harness approval strategy</summary>

- claude-code Guard prefers Claude hooks first, then the local approval center when the shell cannot prompt. - copilot Guard can wrap the copilot CLI, detect ~/.copilot/config.json, ~/.copilot/mcp-config.json, workspace .vscode/mcp.json, and install Guard-managed Copilot hook wiring for documented preToolUse and postToolUse events. Guard does not treat a VS Code Copilot inline permission sheet by itself as proof of Guard interception; current proof should come from Guard hook responses, Guard receipts, or an MCP client that explicitly answers Guard elicitation. - codex Guard asks inline in the same Codex chat when the interactive CLI or Codex App can answer MCP elicitations, and falls back to the local approval center only for codex exec or any other nonresponsive session. When Guard has the right Codex thread binding, approving or blocking in the browser resumes the same Codex thread with HOL Guard-branded continuation copy. Live app-server sessions continue in place, and headless codex exec sessions resume through codex exec resume with the exact blocked command context. If the session cannot be identified, Guard says so plainly and tells you the manual next step instead of pretending it resumed. - cursor Guard respects Cursor’s native tool approval and focuses on artifact trust before launch. - opencode Guard authors package-level policy while OpenCode keeps native once, always, or reject prompts for managed MCP tools. - kimi Guard installs managed PreToolUse and UserPromptSubmit hooks in ~/.kimi-code/config.toml, blocks with exit code 2 and a JSON permissionDecision: "deny" response, and fails open on hook crash or timeout. - grok Guard installs managed Grok hook JSON under ~/.grok/hooks/ plus permission deny rules in ~/.grok/managed_config.toml, blocks with exit code 2 and a Grok-native {"decision":"deny"} response, and never reads ~/.grok/auth. - pi Guard scans ~/.pi/agent/ and project .pi/ packages, extensions, skills, prompts, and themes; installs a managed Pi extension that reviews input and tool_call events inline; and blocks with a Pi-native {"decision":"deny"} response when Guard policy says no. - zcode Guard detects ~/.zcode/cli/config.json, configured MCP servers, enabled plugins, the plugin cache, and plugin manifests; installs managed PreToolUse and UserPromptSubmit hooks in the config hooks section without touching user mcp or plugins; and blocks with exit code 2 and a permissionDecision: "deny" response. - hermes Guard installs a managed Hermes overlay bundle, routes MCP servers through Guard proxies, and prefers native-or-center delivery for blocked requests. - gemini Guard scans extensions and falls back to the local approval center for blocked changes.

</details>

Scanner Quickstart

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

```yaml

Quick Start For Contributors

git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --extra dev --extra cisco --group cisco-mcp
pytest -q

Use uv sync --extra dev --python 3.10 when you need the lean baseline path without the Cisco MCP extra.

CLI Usage

```bash

Config + Baseline Example

```toml

Example Output

🔗 Plugin Scanner v2.0.0
Scanning: ./my-plugin

── Manifest Validation (31/31) ──
  ✅ plugin.json exists                           +4
  ✅ Valid JSON                                   +4
  ✅ Required fields present                      +5
  ✅ Version follows semver                       +3
  ✅ Name is kebab-case                           +2
  ✅ Recommended metadata present                 +4
  ✅ Interface metadata complete if declared      +3
  ✅ Interface links and assets valid if declared +3
  ✅ Declared paths are safe                      +3

── Security (16/16) ──
  ✅ SECURITY.md found                            +3
  ✅ LICENSE found                                +3
  ✅ No hardcoded secrets                         +7
  ✅ No dangerous MCP commands                    +0
  ✅ MCP remote transports are hardened           +0
  ✅ No approval bypass defaults                  +3

── Operational Security (0/0) ──
  ✅ Third-party GitHub Actions pinned to SHAs    +0
  ✅ No write-all GitHub Actions permissions      +0
  ✅ No privileged untrusted checkout patterns    +0
  ✅ Dependabot configured for automation surfaces +0
  ✅ Dependency manifests have lockfiles          +0

── Skill Security (15/15) ──
  ✅ Cisco skill scan completed                   +3
  ✅ No elevated Cisco skill findings             +8
  ✅ Skills analyzable                            +4

Findings: critical:0, high:0, medium:0, low:0, info:0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Score: 100/100 (A - Excellent)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Example: HOL Registry Broker Plugin

The HOL Registry Broker Codex Plugin bridges Codex plugins with the HOL Universal Registry, providing agent discovery, trust signals, and verified identity on Hedera.

HOL Registry scores: Trust 80 / Review 83 / Enforce 74

🔗 Plugin Scanner v2.0.0
Scanning: ./registry-broker-codex-plugin

── Manifest Validation (31/31) ──
  ✅ plugin.json exists                           +4
  ✅ Valid JSON                                   +4
  ✅ Required fields present                      +5
  ✅ Version follows semver                       +3
  ✅ Name is kebab-case                           +2
  ✅ Recommended metadata present                 +4
  ✅ Interface metadata complete if declared      +3
  ✅ Interface links and assets valid if declared +3
  ✅ Declared paths are safe                      +3

── Security (24/24) ──
  ✅ SECURITY.md found                            +3
  ✅ LICENSE found                                +3
  ✅ No hardcoded secrets                         +7
  ✅ No dangerous MCP commands                    +3
  ✅ MCP remote transports are hardened           +3
  ✅ No approval bypass defaults                  +5

── Operational Security (20/20) ──
  ✅ Third-party GitHub Actions pinned to SHAs    +5
  ✅ No write-all GitHub Actions permissions      +5
  ✅ No privileged untrusted checkout patterns    +3
  ✅ Dependabot configured for automation surfaces +4
  ✅ Dependency manifests have lockfiles          +3

── Best Practices (15/15) ──
  ✅ README.md found                             +5
  ✅ Skills directory present                    +3
  ✅ SKILL.md frontmatter valid                  +4
  ✅ No committed .env                           +2
  ✅ .codexignore found                          +1

── Marketplace (15/15) ──
  ✅ marketplace.json valid                      +5
  ✅ Policy fields present                       +5
  ✅ Marketplace sources are safe                +5

── Skill Security (15/15) ──
  ✅ Cisco skill scan completed                  +3
  ✅ No elevated Cisco skill findings            +8
  ✅ Skills analyzable                           +4

── Code Quality (10/10) ──
  ✅ No eval or Function constructor             +5
  ✅ No shell injection patterns                 +5

Findings: critical:0, high:0, medium:0, low:0, info:0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Score: 130/130
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Plugins that pass the scanner with a high score are candidates for listing in the HOL Plugin Registry.

</details>

Rule-oriented lint (with optional mechanical fixes)

plugin-scanner lint ./my-plugin --list-rules plugin-scanner lint ./my-plugin --explain README_MISSING plugin-scanner lint ./my-plugin --fix --profile strict-security

Cisco package status

Credit to Cisco AI Defense for open-sourcing the packages below.

If you want both tools in one shell during local development:

pipx install hol-guard
pipx install plugin-scanner

Container-first environments can use the published image instead. The repo-controlled image installs a lock-derived Cisco dependency set on Python 3.13 so the container has full static Cisco coverage by default.

docker run --rm \
  -v "$PWD:/workspace" \
  ghcr.io/hashgraph-online/hol-guard:<version> \
  scan /workspace --format text

Command names by package:

hol-guard start
plugin-scanner verify .

Scan a plugin directory

plugin-scanner scan ./my-plugin

Scan only Claude package surfaces

plugin-scanner scan ./plugins-repo --ecosystem claude

Scan a multi-plugin repo from the marketplace root

plugin-scanner scan . --format json

.plugin-scanner.toml

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

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

Plugin Author Submission Flow

The action can also handle submission intake. A plugin repository can wire the scanner into CI so a passing scan opens or reuses a submission issue in awesome-codex-plugins.

It also emits automation-friendly machine outputs:

• score, grade, grade_label, max_severity, and findings_total as GitHub Action outputs
• a concise markdown summary in the job summary by default
• an optional machine-readable registry payload file for downstream registry, badge, or awesome-list automation

The intended path is:

1. Add the scanner action to plugin CI.
2. Require min_score: 80 and a severity gate such as fail_on_severity: high.
3. Enable submission mode with a token that has issues:write on hashgraph-online/awesome-codex-plugins.
4. When the plugin clears the threshold, the action opens or reuses a submission issue.
5. The issue body includes machine-readable registry payload data, so registry automation can ingest the same submission event.

Example:

permissions:
  contents: read

jobs:
  scan-plugin:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Scan and submit if eligible
        id: scan
        uses: hashgraph-online/ai-plugin-scanner-action@v1
        with:
          plugin_dir: "."
          min_score: 80
          fail_on_severity: high
          submission_enabled: true
          submission_score_threshold: 80
          submission_token: ${{ secrets.AWESOME_CODEX_PLUGINS_TOKEN }}

      - name: Print submission issue
        if: steps.scan.outputs.submission_performed == 'true'
        run: echo "${{ steps.scan.outputs.submission_issue_urls }}"

submission_token is required when submission_enabled: true. This flow is idempotent. If the plugin repository was already submitted, the action reuses the existing open issue instead of opening duplicates by matching an exact hidden plugin URL marker in the existing issue body.

Registry Payload For Plugin Ecosystem Automation

If you want to feed the same scan into a registry, badge pipeline, or another plugin ecosystem automation step, request a registry payload file directly from the action:

permissions:
  contents: read

jobs:
  scan-plugin:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Scan plugin
        id: scan
        uses: hashgraph-online/ai-plugin-scanner-action@v1
        with:
          plugin_dir: "."
          format: sarif
          output: ai-plugin-scanner.sarif
          registry_payload_output: ai-plugin-registry-payload.json

      - name: Show trust signals
        run: |
          echo "Score: ${{ steps.scan.outputs.score }}"
          echo "Grade: ${{ steps.scan.outputs.grade_label }}"
          echo "Max severity: ${{ steps.scan.outputs.max_severity }}"

      - name: Upload registry payload
        uses: actions/upload-artifact@v6
        with:
          name: ai-plugin-registry-payload
          path: ${{ steps.scan.outputs.registry_payload_path }}

The registry payload mirrors the submission data used by HOL ecosystem automation, so one scan can drive code scanning, review summaries, awesome-list intake, and registry trust ingestion.

Repository Workflows

• Matrix CI for Python 3.10 through 3.13
• Package publishing via the publish.yml workflow
• OpenSSF Scorecard automation for repository hardening visibility

Guard: Troubleshooting