Skip to content
Back to search

hol-guard

Open-source antivirus for AI agents: block risky tools, secret access, prompt injection, malicious packages, MCP servers, plugins, and skills at runtime.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hashgraph-online/hol-guard with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hashgraph-online/hol-guard'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hashgraph-online--hol-guard/badge.svg)](/listings/hashgraph-online--hol-guard)

HTML

<a href="/listings/hashgraph-online--hol-guard"><img src="/api/listings/hashgraph-online--hol-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.10 or newer and [pipx](https://pipx.pypa.io/stable/installation/).

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](docs/guard/get-started.md). Annotated release notes with upgrade context live at [hol.org/guard/releases](https://hol.org/guard/releases); raw releases and prereleases are on the [GitHub releases page](https://github.com/hashgraph-online/hol-guard/releases).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 567 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # HOL Guard: Open-Source Antivirus for AI Agents
  2. <!-- mcp-name: io.github.hashgraph-online/hol-guard -->
  3. [![HOL Guard Version](https://img.shields.io/pypi/v/hol-guard.svg?logo=pypi&logoColor=white&cacheSeconds=300)](https://pypi.org/project/hol-guard/)
  4. [![Plugin Scanner Version](https://img.shields.io/pypi/v/plugin-scanner.svg?logo=pypi&logoColor=white&cacheSeconds=300)](https://pypi.org/project/plugin-scanner/)
  5. [![HOL Guard Downloads](https://img.shields.io/pypi/dm/hol-guard?logo=pypi&logoColor=white)](https://pypi.org/project/hol-guard/)
  6. [![Plugin Scanner Downloads](https://img.shields.io/pypi/dm/plugin-scanner?logo=pypi&logoColor=white)](https://pypi.org/project/plugin-scanner/)
  7. [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](#install-hol-guard)
  8. [![CI](https://img.shields.io/github/actions/workflow/status/hashgraph-online/hol-guard/ci.yml?branch=main&label=CI&logo=githubactions&logoColor=white)](https://github.com/hashgraph-online/hol-guard/actions/workflows/ci.yml)
  9. [![Publish](https://img.shields.io/github/actions/workflow/status/hashgraph-online/hol-guard/publish.yml?branch=main&label=Publish&logo=githubactions&logoColor=white)](https://github.com/hashgraph-online/hol-guard/actions/workflows/publish.yml)
  10. [![Container Image](https://img.shields.io/badge/ghcr-hol--guard-2496ED?logo=docker&logoColor=white)](https://github.com/hashgraph-online/hol-guard/pkgs/container/hol-guard)
  11. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hashgraph-online/hol-guard/badge)](https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/hol-guard)
  12. [![Vercel OSS Program](https://vercel.com/oss/program-badge.svg)](https://vercel.com/oss)
  13. [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
  14. [![GitHub Stars](https://img.shields.io/github/stars/hashgraph-online/hol-guard?style=social)](https://github.com/hashgraph-online/hol-guard/stargazers)
  15. [![Lint: ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg)](https://github.com/astral-sh/ruff)
  16. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/hashgraph-online/hol-guard)
  17. | ![HOL whole dark logo](https://hol.org/brand/Logo_Whole_Dark.png) | **Stop risky AI actions before they compromise your machine.** HOL Guard is a local-first security layer for AI agents, tools, plugins, skills, MCP servers, and package installs.<br><br>[Install HOL Guard](https://hol.org/guard/activate)<br>[Read the documentation](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/get-started.md)<br>[PyPI Package (`hol-guard`)](https://pypi.org/project/hol-guard/)<br>[Report an Issue](https://github.com/hashgraph-online/hol-guard/issues) |
  18. | :--- | :--- |
  19. HOL Guard reviews agent actions before they run: shell commands, file access, package installs, and MCP tool calls. It detects secret exposure, destructive operations, prompt injection, and supply-chain risks, then allows, blocks, or requests approval according to your policy.
  20. Run it locally without an account. Use the CLI and local dashboard to manage protection, resolve approvals, and inspect decision history. Optional [Guard Cloud](docs/guard/local-vs-cloud.md) adds shared history, team policy, and fleet management.
  21. [Get started](#install-hol-guard) · [Supported agents](#supported-ai-agents) · [Plugin scanner](#plugin-scanner) · [Documentation](#documentation) · [Contribute an extension](#contribute-a-new-extension) · [Contribute an adapter](docs/guard/adapter-contributions.md) · [Development](#development)
  22. <!-- hol-sponsors:start -->
  23. <!-- hol-sponsors:end -->
  24. ## Install HOL Guard
  25. Requires Python 3.10 or newer, [pipx](https://pipx.pypa.io/stable/installation/), and a matching native runtime. Check the [platform support and Windows ARM64 setup notes](docs/guard/get-started.md#platform-support) before installing.
  26. ```bash
  27. pipx install hol-guard
  28. hol-guard init
  29. ```
  30. 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.
  31. Check your installation:
  32. ```bash
  33. hol-guard --version
  34. hol-guard status
  35. ```
  36. To update an existing installation:
  37. ```bash
  38. hol-guard update
  39. ```
  40. For manual setup, see the [installation guide](docs/guard/get-started.md). Annotated release notes with upgrade context live at [hol.org/guard/releases](https://hol.org/guard/releases); raw releases and prereleases are on the [GitHub releases page](https://github.com/hashgraph-online/hol-guard/releases).
  41. ## What HOL Guard Protects
  42. | Surface | Protection |
  43. | :--- | :--- |
  44. | **Shell commands and file access** | Reviews destructive operations, sensitive file access, credential exposure, and suspicious outbound commands. |
  45. | **Package installs** | Evaluates supported package-manager operations against supply-chain intelligence before installation. |
  46. | **Plugins, skills, and agent configuration** | Inventories local artifacts and reviews new or changed tools before launch. |
  47. | **MCP servers and tools** | Inspects server configuration and reviews tool calls through supported hooks and managed proxies. |
  48. | **Prompts and tool results** | Screens supported events for prompt injection and sensitive content. |
  49. | **Approvals and evidence** | Routes decisions to native prompts or the approval center, and records local receipts for review. |
  50. Guard connects through native agent hooks, managed MCP proxies, and launch integrations. Coverage depends on the events each agent exposes; the [support matrix](docs/guard/harness-support.md) documents enforcement, approval delivery, and failure behavior per integration.
  51. ## Supported AI Agents
  52. Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, Grok, Hermes, Kimi Code, Pi, oh-my-pi, OpenClaw, OpenCode, Antigravity, ZCode, and Devin. [Paseo](docs/guard/paseo.md) is supported through these native provider integrations, with per-provider coverage.
  53. For example, to set up Codex explicitly:
  54. ```bash
  55. hol-guard install codex
  56. hol-guard run codex --dry-run
  57. hol-guard run codex
  58. ```
  59. The dry run records the current artifact state before launch. For Codex, Guard installs native pre-tool hooks and refuses a managed launch if those hooks are missing or disabled.
  60. [Agent support matrix](docs/guard/harness-support.md) · [Troubleshooting](docs/guard/troubleshooting.md)
  61. <a id="guard-operations"></a>
  62. ## Everyday Use
  63. | Task | Command |
  64. | :--- | :--- |
  65. | Check protection status | `hol-guard status` |
  66. | Diagnose an agent integration | `hol-guard doctor codex` |
  67. | Inspect changes before launch | `hol-guard diff codex` |
  68. | Review pending approvals | `hol-guard approvals` |
  69. | Approve or deny a request | `hol-guard approvals approve <request-id>` / `hol-guard approvals deny <request-id>` |
  70. | Read decision history | `hol-guard receipts` |
  71. | List tracked artifacts | `hol-guard inventory` |
  72. | Export an AI bill of materials | `hol-guard abom --format json` |
  73. | Scan workspace dependencies | `hol-guard supply-chain scan` |
  74. | Connect optional cloud sync | `hol-guard connect` |
  75. <a id="guard-troubleshooting"></a>
  76. <a id="inspect-command-protection-without-running-it"></a>
  77. ### Understand a paused command
  78. Inspect the command's classification and matching rules:
  79. ```bash
  80. hol-guard command test 'rm -rf ./build'
  81. hol-guard command explain 'git clean -ndx'
  82. hol-guard command extensions command.git --json
  83. ```
  84. `command test` and `command explain` inspect the command without executing it or creating an approval. Use `hol-guard approvals` to resolve a pending request and `hol-guard receipts` to review the recorded decision.
  85. The [Extension directory](docs/guard/extensions/README.md) lists command coverage generated from the Rust-compiled catalog. External contributions require explicit opt-in; required core protections remain enabled. To add coverage, follow the [Extension contribution guide](docs/guard/extensions/contributing.md).
  86. ### Check a package
  87. ```bash
  88. hol-guard supply-chain sync
  89. hol-guard supply-chain scan
  90. hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm
  91. ```
  92. The package verdict includes the available advisory evidence and ecosystem coverage. See the [get-started guide](docs/guard/get-started.md) for package-manager interception and the [remediation guide](docs/guard/remediation.md) for handling false positives.
  93. <a id="scanner-quickstart"></a>
  94. <a id="choose-the-right-package"></a>
  95. ## Plugin Scanner
  96. This repository also ships `plugin-scanner`, a CLI for maintainers who want security and quality checks before publishing agent plugins, skills, and MCP integrations.
  97. ```bash
  98. pipx install plugin-scanner
  99. plugin-scanner scan .
  100. plugin-scanner lint .
  101. plugin-scanner verify .
  102. ```
  103. | Command | Purpose |
  104. | :--- | :--- |
  105. | `scan` | Security findings and a quality report across detected package surfaces. |
  106. | `lint` | Rule-level authoring feedback. |
  107. | `verify` | Install-surface and runtime readiness checks. |
  108. | `submit` | A submission artifact for one plugin package. |
  109. | `doctor` | Component diagnostics and troubleshooting bundles. |
  110. 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.
  111. 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.
  112. ```bash
  113. plugin-scanner scan . --format sarif --output plugin-scanner.sarif
  114. plugin-scanner scan . --fail-on-severity high
  115. ```
  116. Quality grades use the checks applicable to each package. Trust scoring has separate provenance and weights; see the [skill](docs/trust/skill-trust-local.md), [MCP](docs/trust/mcp-trust-draft.md), and [plugin](docs/trust/plugin-trust-draft.md) scoring references.
  117. <a id="ci-and-automation"></a>
  118. ### Package a plugin for every runtime
  119. `hol-guard plugin` is the Plugin Kit. Point it at one plugin source, such as a Claude Code plugin, Codex plugin, Gemini CLI extension, MCP Registry `server.json` or a folder of skills, and it checks the source and writes a ready-to-load copy for each agent runtime that can use it. It runs locally, reads only the folder you name and makes no network calls.
  120. ```bash
  121. hol-guard plugin check # what marketplaces and runtime loaders would reject
  122. hol-guard plugin package # writes dist/hol-plugin/<runtime>/ for each runtime
  123. hol-guard plugin convert --to agent-plugins # Agent Plugins 1.0 package, checked against the spec
  124. hol-guard plugin links # install commands per runtime, plus listing links
  125. hol-guard plugin card # draft .well-known plugin card as JSON
  126. hol-guard plugin init --name my-plugin # scaffold a new plugin in an empty folder
  127. ```
  128. Runtimes: `claude-code`, `codex`, `gemini-cli`, `cursor`, `vscode`, `opencode`, `mcp-registry`, `agent-skills` and `agent-plugins`. See [the Plugin Kit guide](docs/guard/plugin-kit.md).
  129. ### GitHub Actions
  130. Add the scanner to a plugin repository:
  131. ```yaml
  132. name: Plugin security
  133. on: [push, pull_request]
  134. permissions:
  135. contents: read
  136. jobs:
  137. scan:
  138. runs-on: ubuntu-latest
  139. steps:
  140. - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
  141. - uses: hashgraph-online/ai-plugin-scanner-action@fdb49f9d85321a2ced2933301b395dd3c1ce9c8f # v1.2.631
  142. with:
  143. plugin_dir: "."
  144. min_score: 80
  145. fail_on_severity: high
  146. ```
  147. See the [action documentation](https://github.com/hashgraph-online/ai-plugin-scanner-action) for SARIF uploads, submission workflows, and machine-readable outputs. The action source is maintained in [`action/`](action/).
  148. <a id="install-the-package-you-need"></a>
  149. <a id="resolver-safe-cisco-extra"></a>
  150. ### Optional Cisco analysis
  151. 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:
  152. ```bash
  153. pipx install 'plugin-scanner[cisco]'
  154. ```
  155. For Cisco MCP analysis, use the repository's [Docker image](Dockerfile) or the `cisco-mcp` dependency group:
  156. ```bash
  157. uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13
  158. uv run plugin-scanner scan . --cisco-skill-scan on --cisco-mcp-scan on
  159. ```
  160. 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`](pyproject.toml).
  161. ## Ecosystem Support
  162. | Ecosystem | Detection surfaces |
  163. | :--- | :--- |
  164. | Codex | `.codex-plugin/plugin.json`, `marketplace.json`, `.agents/plugins/marketplace.json` |
  165. | Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` |
  166. | DeepSeek Harness | `package.json` with `dsh.bundle`, declared patches, and Cordis `apply(ctx)` exports, or `dsh.bundle.mode` set to `"patch"` for patch-only bundles |
  167. | Gemini CLI | `gemini-extension.json`, `commands/**/*.toml` |
  168. | Kimi Code | `kimi.plugin.json`, `.kimi-plugin/plugin.json`, declared skills, agents, commands, prompts, and MCP servers |
  169. | OpenCode | `opencode.json`, `opencode.jsonc`, `.opencode/commands`, `.opencode/plugins` |
  170. Use `--ecosystem auto` to detect supported packages in a repository, or select an ecosystem explicitly:
  171. ```bash
  172. plugin-scanner scan ./plugins-repo --ecosystem claude
  173. plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
  174. ```
  175. ## What The Scanner Checks
  176. | Category | Coverage |
  177. | :--- | :--- |
  178. | Manifest validation | Required fields, versions, declared paths, interface metadata, links, and assets. |
  179. | Security | Hardcoded secrets, unsafe MCP commands and transports, and risky approval defaults. |
  180. | Operational security | GitHub Actions permissions and pinned dependencies, privileged checkout patterns, Dependabot, and lockfiles. |
  181. | Plugin packaging | README and license files, skill frontmatter, ignore rules, and accidentally committed environment files. |
  182. | Marketplace | Manifest validity, local package discovery, and safe source paths. |
  183. | Skill and MCP analysis | Analyzer availability, findings, and analyzability from optional Cisco integrations. |
  184. | Code quality | Dynamic code execution and shell-injection patterns. |
  185. ## How Trust Scoring Works
  186. Plugin Scanner reports a quality grade alongside trust provenance. Quality scores are normalized across applicable checks, so optional surfaces do not inflate a package's grade.
  187. Skill trust uses the HCS-28 baseline adapter IDs, weights, and denominator rules. MCP and Codex plugin trust use explicit adapters, weights, and contribution modes documented in the local specifications:
  188. - [Skill Trust Local Draft](docs/trust/skill-trust-local.md)
  189. - [MCP Trust Draft](docs/trust/mcp-trust-draft.md)
  190. - [Codex Plugin Trust Draft](docs/trust/plugin-trust-draft.md)
  191. <a id="quality-suite-commands"></a>
  192. ## CLI Usage
  193. ```bash
  194. # Structured security report
  195. plugin-scanner scan ./my-plugin --format json --profile public-marketplace
  196. # Inspect authoring rules
  197. plugin-scanner lint ./my-plugin --list-rules
  198. plugin-scanner lint ./my-plugin --explain README_MISSING
  199. # Apply supported mechanical fixes
  200. plugin-scanner lint ./my-plugin --fix --profile strict-security
  201. # Verify package readiness; --online permits live probes
  202. plugin-scanner verify ./my-plugin --format json
  203. plugin-scanner verify ./my-plugin --online --format text
  204. # Generate a submission artifact for one plugin
  205. plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json
  206. # Collect component diagnostics
  207. plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip
  208. ```
  209. For a repository marketplace, `scan`, `lint`, `verify`, and `doctor` can target the root. `submit` targets one plugin package.
  210. ## Codex Spec Alignment
  211. The scanner recognizes Codex plugin manifests, interface metadata, declared assets, and marketplace packages:
  212. - Local manifest paths use `./` prefixes; `lint --fix` preserves or adds them.
  213. - `.agents/plugins/marketplace.json` is the preferred marketplace location, with root `marketplace.json` supported for compatibility.
  214. - Interface validation checks declared links and assets without requiring an undocumented `type` field.
  215. - `verify --online` checks HTTP remote reachability. Stdio server execution is skipped for manual review.
  216. See the [Codex plugin documentation](https://developers.openai.com/codex/plugins) and [Model Context Protocol specification](https://modelcontextprotocol.io) for upstream formats.
  217. ## Config + Baseline Example
  218. Configure the scanner in `.plugin-scanner.toml`:
  219. ```toml
  220. [scanner]
  221. profile = "public-marketplace"
  222. baseline_file = "baseline.txt"
  223. ignore_paths = ["tests/*", "fixtures/*"]
  224. [rules]
  225. disabled = ["README_MISSING"]
  226. severity_overrides = { CODEXIGNORE_MISSING = "low" }
  227. ```
  228. 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.
  229. ## Report Formats
  230. | Format | Use |
  231. | :--- | :--- |
  232. | `text` | Terminal summaries with category totals and findings. |
  233. | `json` | Structured reports for scripts and integrations. |
  234. | `markdown` | Review-ready reports for pull requests and issues. |
  235. | `sarif` | GitHub code scanning and security automation. |
  236. ## GitHub Action
  237. The [AI Plugin Scanner Action](https://github.com/hashgraph-online/ai-plugin-scanner-action) supports security gates, SARIF uploads, submission intake, and registry payloads. Its source lives in [`action/`](action/), and the [publication workflow](.github/workflows/publish-action-repo.yml) distributes the action bundle.
  238. The legacy [HOL Codex Plugin Scanner Action](https://github.com/hashgraph-online/hol-codex-plugin-scanner-action) remains available for existing workflows.
  239. ### Plugin Author Submission Flow
  240. 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.
  241. See the [action's input reference](action/action.yml) for `submission_score_threshold`, `submission_token`, and the target repository options.
  242. ### Registry Payload For Plugin Ecosystem Automation
  243. 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.
  244. The [HOL Registry Broker plugin](https://github.com/hashgraph-online/registry-broker-codex-plugin) is an example of an agent plugin in the [HOL Plugin Registry](https://hol.org/registry/plugins). Its [registry listing](https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin) provides current trust information.
  245. ## Why HOL Guard
  246. AI agents can run commands, install dependencies, read files, and call external tools within one session. HOL Guard reviews those actions at supported execution points and keeps the policy decision, approval request, and receipt together.
  247. Use it for AI agent security on a developer machine, MCP security around connected tools, and supply-chain checks for packages and plugins. Teams can add Guard Cloud for shared approvals and policy management while retaining local protection.
  248. ## Frequently Asked Questions
  249. ### What is HOL Guard?
  250. HOL Guard is open-source antivirus and runtime protection for AI agents. It reviews supported tool calls, shell commands, file access, and package operations for risks such as secret exposure, prompt injection, destructive actions, and malicious dependencies.
  251. ### Does HOL Guard work without a cloud account?
  252. Yes. Local protection, CLI commands, approvals, and receipts work without signing in. Guard Cloud is optional and adds synchronized evidence, team controls, and fleet visibility. See [Local Guard vs. Guard Cloud](docs/guard/local-vs-cloud.md) for the feature boundary.
  253. ### Which AI agents does HOL Guard support?
  254. Guard includes adapters for Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, Grok, Hermes, Kimi Code, Pi, oh-my-pi, OpenClaw, OpenCode, Antigravity, ZCode, and Devin. [Paseo](docs/guard/paseo.md) is supported through these native provider integrations, with per-provider coverage. The [support matrix](docs/guard/harness-support.md) explains which events and enforcement paths each adapter supports.
  255. ### What is the difference between HOL Guard and Plugin Scanner?
  256. 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.
  257. ### How does HOL Guard protect MCP servers?
  258. Guard inspects MCP server configuration and reviews supported MCP tool calls through agent hooks and managed proxies. Plugin Scanner checks MCP configuration and HTTP remote reachability; optional Cisco MCP analysis adds static security findings.
  259. ### Why did Guard pause my command?
  260. The action may need approval under your active policy, or its tools or artifacts may have changed. Start with `hol-guard approvals`, inspect the command with `hol-guard command explain '<command>'`, and use `hol-guard receipts` to review the recorded decision.
  261. ## Documentation
  262. For enrollment or stale native authority errors, see [extension-control recovery](docs/guard/extension-control-recovery.md).
  263. | Guide | Contents |
  264. | :--- | :--- |
  265. | [Get started](docs/guard/get-started.md) | Installation, manual setup, package protection, and common commands. |
  266. | [Agent support](docs/guard/harness-support.md) | Integration coverage and approval behavior. |
  267. | [Architecture](docs/guard/architecture.md) | Runtime components and decision flow. |
  268. | [Policy specification](spec/guard-policy/v1alpha1/README.md) | GuardPolicy document format. |
  269. | [Policy recipes](docs/guard/policy-recipes.md) | Configuration examples for common workflows. |
  270. | [Extensions](docs/guard/extensions/README.md) | Built-in command rules and contribution guidance. |
  271. | [Native extension authoring](docs/guard/extension-builder/README.md) | Canonical JSON sources, the Rust compiler, portable fixtures, and review kits. |
  272. | [Contribute an extension](#contribute-a-new-extension) | Generate, review, integrate, and test a new extension with the CLI. |
  273. | [Local vs. cloud](docs/guard/local-vs-cloud.md) | Local capabilities and optional cloud services. |
  274. | [Troubleshooting](docs/guard/troubleshooting.md) | Diagnosis and recovery. |
  275. | [Security](SECURITY.md) | Vulnerability reporting and disclosure policy. |
  276. ## Contribute a New Extension
  277. To integrate a new AI coding agent or IDE, use the separate [harness adapter contribution guide](docs/guard/adapter-contributions.md). Harness adapters provide discovery, managed setup, and event integration. The command extensions below add policy coverage for CLI tools and do not install agent hooks.
  278. Command extensions are authored as **declarative JSON compiled and evaluated by Rust**. Add metadata, permissions, matcher trees, and safe variants in `contributions/command-sources/command.<name>.json`, then verify behavior with portable JSON fixtures. Most extensions compose existing native operations; a new Rust operation is needed only when the existing matcher contracts cannot express the behavior.
  279. | Contribution | Authoring input | Verification |
  280. | :--- | :--- | :--- |
  281. | Command coverage | `contributions/command-sources/command.<name>.json` | Portable fixtures evaluated by `guard-command-source test`. |
  282. | MCP server knowledge | `contributions/mcp-servers/<id>.json` | MCP contribution tests and native catalog validation. |
  283. | New matcher semantics | Reviewed Rust changes in `rust/crates/guard-command/` | Native contract, admission, evaluation, and regression tests. |
  284. The Rust compiler generates command descriptors, the catalog, and the native matcher program. Python remains part of the CLI, build orchestration, and tests; new command coverage does not require a Python detector or registry registration. See the [authoring guide](docs/guard/extension-builder/README.md) for direct source authoring and the [architecture](docs/guard/command-extension-architecture.md) for the runtime boundary.
  285. The **Extension Builder CLI** can create those command sources and portable fixtures from exported command metadata. It also supports MCP inventories. It works offline and reads the export without importing or running the target tool.
  286. Use the Builder's plan-and-apply flow to create the canonical source and fixture. Open a draft
  287. PR early for scope review. Before marking that PR ready for review, run
  288. `scripts/prepare_extension_contribution.py --source ... --fixture ...` to synchronize deterministic
  289. projections, then run `hol-guard extensions handoff --repo . --source ... --fixture ...`. The handoff
  290. check catches missing generated descriptors, catalog entries, and source bindings before final review.
  291. **1. Define the coverage in the PR.** Check the [Extension directory](docs/guard/extensions/README.md) and current [open pull requests](https://github.com/hashgraph-online/hol-guard/pulls) for existing or overlapping coverage. For a new capability, open a draft PR with the **Command extension** template and include the proposed `command.<name>` ID, supported operations, destructive examples, safe counterparts, and upstream references. Scope review happens on the PR; a separate issue is not required. Extend an existing extension when it already owns the operation.
  292. Follow the [development setup](#development), then run the examples below from your HOL Guard checkout. `uv run --no-sync` uses that checkout's installed development version.
  293. **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.
  294. ```bash
  295. uv run --no-sync hol-guard extensions generate --from cli \
  296. --input docs/guard/extension-builder/examples/cli-surface.json \
  297. --slug samplectl --executable samplectl --name 'Sample CLI' \
  298. --publisher community.example --publisher-name 'Example Maintainer' \
  299. --homepage https://example.test/samplectl \
  300. --upstream-version 1.0.0 --output samplectl-kit
  301. uv run --no-sync hol-guard extensions validate samplectl-kit
  302. ```
  303. The output directory must be new, with an existing parent directory. A command kit includes `discovery.json`, `review.json`, `report.json`, the canonical JSON source, a portable native fixture, a generated descriptor, and a file manifest. MCP kits contain their contribution metadata and generated Python tests.
  304. 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.
  305. For MCP contributions, the generator uses `--launcher` and `--package` instead of `--executable`. See the [MCP kit example](docs/guard/extension-builder/README.md#generate-an-mcp-kit) for a complete command and pagination requirements.
  306. **3. Review the operations and regenerate.** Read `report.json` and compare the discovered operations with the upstream implementation. Copy the review file before editing:
  307. ```bash
  308. cp samplectl-kit/review.json samplectl-review.json
  309. ```
  310. 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](docs/guard/extension-builder/README.md#review-and-recompile) includes a complete entry example.
  311. Recompile the saved snapshot after reviewing it:
  312. ```bash
  313. uv run --no-sync hol-guard extensions generate --from snapshot \
  314. --input samplectl-kit/discovery.json \
  315. --review samplectl-review.json --output samplectl-reviewed
  316. uv run --no-sync hol-guard extensions validate samplectl-reviewed
  317. uv run --no-sync hol-guard extensions diff samplectl-kit samplectl-reviewed
  318. "$HOL_GUARD_NATIVE_SOURCE_COMPILER" test \
  319. < samplectl-reviewed/artifacts/tests/fixtures/command-source-samplectl.v1.json
  320. ```
  321. `diff` exits `0` for equal kits and `1` when valid kits differ. The Rust fixture runner evaluates command text without executing it. If the upstream export changes, generate and review a new snapshot.
  322. **4. Preview and apply the integration.** On your contribution branch, preview the changes to the current checkout:
  323. ```bash
  324. uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .
  325. ```
  326. Inspect the listed paths and generated files. Copy the printed plan digest into the following command before running it:
  327. ```bash
  328. uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo . \
  329. --expected-plan THE_PRINTED_PLAN_DIGEST \
  330. --write
  331. ```
  332. The write integrates the canonical source, fixture, generated contribution descriptor, external trust map, packaging, and authoring ownership records. Regenerate the complete program and catalog in the next step. Existing IDs or conflicting files stop integration for review.
  333. **5. Test and submit a pull request.** Follow the [native validation sequence](docs/guard/extension-builder/VALIDATION.md) to regenerate the complete catalog, rebuild the compiler and runtime against that program, and run the contribution's fixtures against the integrated sources. This also covers updating an existing extension, where an addition to the packaged baseline would conflict with the existing ID. Then run the contribution checks and regenerate the public directory:
  334. ```bash
  335. uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
  336. uv run --no-sync pytest -q \
  337. tests/test_guard_extension_contribution.py \
  338. tests/test_guard_extension_trust.py \
  339. tests/test_native_source_program.py \
  340. tests/test_guard_command_extension_registry.py
  341. uv run --no-sync python scripts/export_extension_directory.py
  342. uv run --no-sync python scripts/export_extension_directory.py --check
  343. uv run --no-sync python scripts/render_command_extension_directory.py
  344. uv run --no-sync python scripts/render_command_extension_directory.py --check
  345. git diff --check
  346. ```
  347. Add fixture cases for destructive operations, safe previews, aliases, reordered flags, quoting, malformed input, and compound commands. Run the Rust checks when changing native semantics and the relevant Python checks when changing tooling. Inspect the final diff, commit the canonical inputs, generated projections, fixtures, and authoring records, and update the existing draft PR against `main` with the test results. Mark it ready for review after the handoff check passes. Keep scratch kit directories and raw upstream exports out of the PR.
  348. **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 rules cannot weaken Guard's required protections.
  349. [Full builder reference](docs/guard/extension-builder/README.md) · [Contribution review requirements](docs/guard/extensions/contributing.md) · [External extension contract](docs/guard/extension-contributions.md) · [Builder validation](docs/guard/extension-builder/VALIDATION.md)
  350. <a id="quick-start-for-contributors"></a>
  351. ## Development
  352. The development toolchain includes Python 3.10 or newer, [uv](https://docs.astral.sh/uv/), and Rust 1.88.0, pinned in [`rust/rust-toolchain.toml`](rust/rust-toolchain.toml). Rust builds the native runtime and extension compiler; Python supplies the CLI and development tooling. The commands below use a POSIX shell from the repository root. See [CONTRIBUTING.md](CONTRIBUTING.md) for Windows setup and the checks for each kind of change.
  353. ```bash
  354. git clone https://github.com/hashgraph-online/hol-guard.git
  355. cd hol-guard
  356. uv sync --frozen --extra dev
  357. rustup toolchain install 1.88.0 --profile minimal --component rustfmt --component clippy
  358. cargo +1.88.0 build --locked --release --manifest-path rust/Cargo.toml \
  359. -p guard-command --bin guard-command-source
  360. cargo +1.88.0 build --locked --release --manifest-path rust/Cargo.toml \
  361. -p hol-guard-runtime
  362. export HOL_GUARD_NATIVE_SOURCE_COMPILER="$PWD/rust/target/release/guard-command-source"
  363. export HOL_GUARD_NATIVE_TEST_SOURCE_COMPILER="$HOL_GUARD_NATIVE_SOURCE_COMPILER"
  364. export HOL_GUARD_NATIVE_BINARY="$PWD/rust/target/release/hol-guard-runtime"
  365. uv run --no-sync python scripts/build_native_command_program.py \
  366. --compiler "$HOL_GUARD_NATIVE_SOURCE_COMPILER" --check
  367. uv run --no-sync pytest tests/test_guard_extension_builder_public_docs.py \
  368. tests/test_native_source_program.py --tb=short
  369. ```
  370. Those compiler overrides are for an editable checkout. Installed native wheels use their bundled compiler and verify its manifest. After changing canonical sources or Rust semantics, regenerate the projections and rebuild as described in the [validation guide](docs/guard/extension-builder/VALIDATION.md).
  371. For Python tooling and package changes:
  372. ```bash
  373. uv run --no-sync ruff check src tests
  374. uv run --no-sync ruff format --check src tests
  375. uv build
  376. ```
  377. For optional Cisco coverage, use the dependency group command above. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution requirements and the [testing matrix](docs/guard/testing-matrix.md) for integration tests.
  378. ## Resources
  379. - [HOL Plugin Registry](https://hol.org/registry/plugins)
  380. - [HOL Plugin Security dataset on Hugging Face](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)
  381. - [HOL Standards Documentation](https://hol.org/docs/standards)
  382. - [OpenAI Codex Plugin Documentation](https://developers.openai.com/codex/plugins)
  383. - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
  384. - [Cisco AI Skill Scanner](https://pypi.org/project/cisco-ai-skill-scanner/)
  385. - [Cisco AI MCP Scanner](https://pypi.org/project/cisco-ai-mcp-scanner/)
  386. - [HOL GitHub Organization](https://github.com/hashgraph-online)
  387. ## Community
  388. Maintained by [HOL](https://github.com/hashgraph-online).
  389. - [Report a bug or request a feature](https://github.com/hashgraph-online/hol-guard/issues)
  390. - [Browse release notes](https://hol.org/guard/releases)
  391. - [See who builds Guard](https://hol.org/guard/contributors)
  392. - [Browse raw GitHub releases](https://github.com/hashgraph-online/hol-guard/releases)
  393. - [Explore the plugin security dataset](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)
  394. ## License
  395. Licensed under [Apache-2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.