@wsl8297: The scariest scenario when using Agents is when they treat dangerous commands as normal steps. That's exactly what HOL Guard is designed to address. GitHub: https://github.com/hashgraph-online/hol-guard… Website: https://hol…

The worst scenario when working with Agents is when it executes dangerous commands as if they were normal steps. HOL Guard is built specifically for this problem. GitHub: https://github.com/hashgraph-online/hol-guard… Official site: https://hol.org It adds a security interception layer for development Agents like Codex, Claude Code, Cursor, Gemini, and OpenCode. It identifies dangerous prompts and intercepts high-risk operations before tool execution, supporting 4 protection levels and a local approval center. Use cases: • Developers who have already allowed Agents into project directories and need protection against accidental deletions or modifications • Teams that are unsure about MCP plugins or Skills and want to scan before running • Security-sensitive projects that need audit records for every Agent operation • Maintainers who want to verify plugin package security in CI environments If you have already started letting Agents execute commands automatically, you should look into this kind of security boundary tool early. — # hashgraph-online/hol-guard Source: https://github.com/hashgraph-online/hol-guard # HOL Guard HOL Guard Version (https://pypi.org/project/hol-guard/) Plugin Scanner Version (https://pypi.org/project/plugin-scanner/) HOL Guard Downloads (https://pypi.org/project/hol-guard/) Plugin Scanner Downloads (https://pypi.org/project/plugin-scanner/) Python 3.10+ CI (https://github.com/hashgraph-online/hol-guard/actions/workflows/ci.yml) Publish (https://github.com/hashgraph-online/hol-guard/actions/workflows/publish.yml) Container Image (https://github.com/hashgraph-online/hol-guard/pkgs/container/hol-guard) OpenSSF Scorecard (https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/hol-guard) License GitHub Stars (https://github.com/hashgraph-online/hol-guard/stargazers) Lint: ruff (https://github.com/astral-sh/ruff) | Hashgraph Online Logo | Protect your harness locally with hol-guard. Use plugin-scanner when you need maintainer and CI checks for plugins, skills, MCP servers, and marketplace packages.PyPI Package (hol-guard) (https://pypi.org/project/hol-guard/)PyPI Package (plugin-scanner) (https://pypi.org/project/plugin-scanner/)HOL Plugin Registry (https://hol.org/registry/plugins)HOL GitHub Organization (https://github.com/hashgraph-online)Report an Issue (https://github.com/hashgraph-online/hol-guard/issues) | | :— | :— | ## Start Here | If you want to… | Install | Start with | | :— | :— | :— | | protect Codex, Claude Code, Copilot CLI, Hermes, Cursor, Gemini, or OpenCode before tools run | hol-guard | hol-guard start | | lint and verify packages in CI before release | plugin-scanner | plugin-scanner verify . | ## Guard Quickstart bash pipx install hol-guard hol-guard init 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: bash 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 [email protected] --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. Guard commands at a glance - 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 Creates the launcher shim for that harness. - hol-guard update Updates the installed hol-guard package in the current environment. - hol-guard run --dry-run Records the current state once before you trust it. - hol-guard run 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. Harness approval strategy - 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. - 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. ## Guard: Protection Levels HOL Guard is antivirus for AI harnesses. It intercepts every tool action before your files change or your network is contacted, then decides in milliseconds whether to allow or block. Choose a protection level with hol-guard settings set security-level : | Level | Who it’s for | What it blocks | | :— | :— | :— | | Gentle | Teams who want minimal friction; experienced users | High-confidence secrets and clear exfil only | | Balanced | Most users (default) | Secrets, shell exfil, prompt injections, supply-chain hooks | | Strict | Security-conscious teams | Everything above plus low-confidence signals and untrusted prompts | | Paranoid | High-security environments | All the above plus any unrecognized MCP server action | If you are unsure, start with Balanced. You can promote to Strict after reviewing your first week of receipts. ## Guard: Troubleshooting ### Why was my command paused? Guard paused a command because one or more detectors fired. To see exactly what triggered: bash hol-guard receipts # review recent decisions hol-guard doctor # run a probe and see which detectors are active hol-guard doctor --perf # include per-detector timing If the block looks like a false positive, you can approve it from the receipts view or from the dashboard at http://localhost:6174. ### How do I clear approvals? From the terminal: bash hol-guard approvals # list pending approvals hol-guard approvals clear # clear all pending approvals (prompts for confirmation) From the dashboard: open http://localhost:6174, go to the Approval Center, and use the Clear all button. You will be asked to confirm before any approvals are removed. ## Guard: Advisory Sync Privacy Guard’s advisory database updates are optional and pull-only. When you run hol-guard advisories sync, Guard fetches a signed advisory list from advisories.hol.org. No local file paths, harness configs, receipt data, or workspace identifiers are sent to any server during sync. Advisory sync requires a HOL Guard Cloud account. If you have not signed in, sync is skipped and Guard continues using the locally bundled advisory database. Run hol-guard login to connect a free account. ## Scanner Quickstart bash pipx install plugin-scanner plugin-scanner lint . plugin-scanner verify . yaml # GitHub Actions PR gate - name: AI plugin quality gate uses: hashgraph-online/ai-plugin-scanner-action@v1 with: plugin_dir: "." fail_on_severity: high min_score: 80 When to add plugin-scanner: - You publish plugins, skills, or marketplace packages - You want a CI gate before release - You need SARIF, verification payloads, or submission artifacts If your repository uses a Codex marketplace root like .agents/plugins/marketplace.json, keep plugin_dir: ".". The scanner will discover local ./plugins/... entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin. ## Need More Detail? - Contributor setup: jump to Development - Local Guard docs: docs/guard/get-started.md - GitHub Action docs: hashgraph-online/ai-plugin-scanner-action (https://github.com/hashgraph-online/ai-plugin-scanner-action) - Registry and trust references: keep reading below Scanner reference: trust scoring, installs, ecosystems, and CLI commands ## How Trust Scoring Works The scanner now emits explicit trust provenance alongside the quality grade: - bundled skills use the published HCS-28 baseline adapter ids, weights, and denominator rules directly - MCP configuration trust uses the same HCS-style adapter, weight, and contribution-mode pattern locally - top-level Codex plugin trust uses the same HCS-style adapter, weight, and contribution-mode pattern locally Current local specs: - Skill Trust Local Draft - MCP Trust Draft - Codex Plugin Trust Draft This keeps the quality grade and the trust score separate. Signals like SECURITY.md remain visible, but their weight is now a named adapter weight rather than an inferred side effect of raw category points. ## Quick Start For Contributors bash git clone https://github.com/hashgraph-online/hol-guard.git cd hol-guard uv sync --extra dev --extra cisco pytest -q Use uv sync --extra dev --python 3.10 when you need the lean baseline path without the Cisco MCP extra. ## Install The Package You Need ### Lean baseline install Guard package: bash pip install hol-guard Scanner package: bash pip install plugin-scanner The lean baseline keeps Python 3.10 support intact and always includes the shipped cisco-ai-skill-scanner integration. ### Full Cisco coverage Install the Cisco extra on Python 3.11+ when you want static MCP coverage in addition to the baseline skill scanner: bash pip install "hol-guard[cisco]" bash pip install "plugin-scanner[cisco]" cisco-ai-mcp-scanner stays in the optional cisco extra because it is Python 3.11+ only and adds a heavier YARA-backed install surface than the lean baseline should require. Cisco currently supports the patched litellm==1.83.10 release across the scanner install surface, so this repository keeps that Cisco-compatible pin for full coverage. On Guard surfaces, the Cisco extra adds optional offline evidence to hol-guard scan, hol-guard preflight, and hol-guard explain . Use --cisco-mode {auto,on,off} to control that consumer-mode evidence path for local artifact scans. hol-guard run and Guard runtime prompt/file-read protection remain native Guard behavior in this pass. Guard inventory snapshots can also carry Cisco MCP and skill-scanner status when a Hermes or OpenClaw inventory run explicitly enables those scanners. The Cloud evidence model records scanner source, status, redacted finding text, duration, mapped artifact ID, and risk component metadata without storing raw local paths or secrets. Guard does not add Cisco AIBOM runtime integration in this pass. If AIBOM support returns later, it should stay on evidence or export surfaces rather than Guard blocking or approval logic. ### Cisco package status Credit to Cisco AI Defense (https://github.com/cisco-ai-defense) for open-sourcing the packages below. | Package | Status in this repo | Notes | | :— | :— | :— | | cisco-ai-skill-scanner | shipped by default | Included in the lean baseline install. | | cisco-ai-mcp-scanner | shipped via [cisco] | Recommended for full Cisco coverage on Python 3.11+, including repo-controlled CI and Docker. | | cisco-ai-a2a-scanner | deferred | Requires live A2A endpoints and is not added in this pass. | | cisco-aibom | deferred | No Guard runtime integration in this pass. Revisit later only for evidence or export workflows. | If you want both tools in one shell during local development: bash 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.12 so the container has full static Cisco coverage by default. bash docker run --rm \ -v "$PWD:/workspace" \ ghcr.io/hashgraph-online/hol-guard: \ scan /workspace --format text Command names by package: bash hol-guard start plugin-scanner verify . ## Ecosystem Support | Ecosystem | Detection Surfaces | | :— | :— | | Codex | .codex-plugin/plugin.json, marketplace.json, .agents/plugins/marketplace.json | | Claude Code | .claude-plugin/plugin.json, .claude-plugin/marketplace.json | | Gemini CLI | gemini-extension.json, commands/**/*.toml | | OpenCode | opencode.json, opencode.jsonc, .opencode/commands, .opencode/plugins | Use --ecosystem auto (default) to scan all detected packages in a repository, or select a single ecosystem explicitly. ## What The Scanner Checks plugin-scanner supports a full quality suite: - scan for full-surface security and release analysis - lint for rule-oriented authoring feedback - verify for runtime and install-surface readiness checks - submit for artifact-backed submission gating - doctor for targeted diagnostics and troubleshooting bundles The scanner evaluates only the surfaces a plugin actually exposes, then normalizes the final score across applicable checks. A plugin is not rewarded or penalized for optional surfaces it does not ship. | Category | Max Points | Coverage | | :— | :— | :— | | Manifest Validation | 31 | plugin.json, required fields, semver, kebab-case, recommended metadata, interface metadata, interface links and assets, safe declared paths | | Security | 36 | SECURITY.md, LICENSE, hardcoded secret detection, dangerous MCP commands, MCP transport hardening, risky approval defaults, Cisco MCP scan status, elevated MCP findings, MCP analyzability | | Operational Security | 20 | SHA-pinned GitHub Actions, write-all, privileged untrusted checkout patterns, Dependabot, dependency lockfiles | | Best Practices | 15 | README.md, skills directory, SKILL.md frontmatter, committed .env, .codexignore | | Marketplace | 15 | .agents/plugins/marketplace.json validity, legacy marketplace.json compatibility, policy fields, safe source paths | | Skill Security | 15 | Cisco integration status, elevated skill findings, analyzability | | Code Quality | 10 | eval, new Function, shell-injection patterns | ## CLI Usage ``bash # Scan a plugin directory plugin-scanner scan ./my-plugin # Auto-det