From 02abae8c257c788059f58e7ce82166fd21d9ef89 Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Mon, 24 Aug 2026 17:42:55 -0400 Subject: [PATCH] feat: add HOL Guard security skill --- README.md | 5 +- marketplaces/openhands-extensions.json | 13 +++ skills/hol-guard/.claude-plugin | 1 + skills/hol-guard/.codex-plugin | 1 + skills/hol-guard/.plugin/plugin.json | 19 +++++ skills/hol-guard/README.md | 34 ++++++++ skills/hol-guard/SKILL.md | 108 +++++++++++++++++++++++++ 7 files changed, 179 insertions(+), 2 deletions(-) create mode 120000 skills/hol-guard/.claude-plugin create mode 120000 skills/hol-guard/.codex-plugin create mode 100644 skills/hol-guard/.plugin/plugin.json create mode 100644 skills/hol-guard/README.md create mode 100644 skills/hol-guard/SKILL.md diff --git a/README.md b/README.md index 2b883705..cceb08e2 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded ## Extensions Catalog -This repository contains **2 marketplace(s)** with **68 extensions** (58 skills, 10 plugins). +This repository contains **2 marketplace(s)** with **69 extensions** (59 skills, 10 plugins). ### large-codebase @@ -115,7 +115,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases Official skills and plugins for OpenHands — the open-source AI software engineer. -**64 extensions** (56 skills, 8 plugins) +**65 extensions** (57 skills, 8 plugins) | Name | Type | Description | Commands | |------|------|-------------|----------| @@ -146,6 +146,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine | github-pr-reviewer | skill | Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed fi... | `/pr-reviewer:setup` | | github-repo-monitor | skill | Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger p... | `/github-monitor:poll` | | gitlab | skill | Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when wor... | — | +| hol-guard | skill | Use HOL Guard to protect supported local AI harnesses, review Guard approvals and receipts, and scan agent plugins, s... | — | | incident-retrospective | skill | Create an automation that drafts incident retrospectives by gathering incident-channel messages from Slack, collectin... | `/incident-retro:setup` | | iterate | skill | Iterate on a GitHub pull request — drive it through CI, code review, and QA until merge-ready. Monitors state, fixes ... | `/iterate`, `/verify`, `/babysit` | | jira-issue-to-pr | skill | Deploy a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable lab... | — | diff --git a/marketplaces/openhands-extensions.json b/marketplaces/openhands-extensions.json index afa26ff8..f09f4510 100644 --- a/marketplaces/openhands-extensions.json +++ b/marketplaces/openhands-extensions.json @@ -527,6 +527,19 @@ "semver" ] }, + { + "name": "hol-guard", + "source": "./skills/hol-guard", + "description": "Use HOL Guard to protect supported local AI harnesses, review Guard approvals and receipts, and scan agent plugins, skills, MCP servers, and marketplace packages before use.", + "category": "code-quality", + "keywords": [ + "hol-guard", + "security", + "ai-agents", + "plugin-scanner", + "approvals" + ] + }, { "name": "security", "source": "./skills/security", diff --git a/skills/hol-guard/.claude-plugin b/skills/hol-guard/.claude-plugin new file mode 120000 index 00000000..665797f0 --- /dev/null +++ b/skills/hol-guard/.claude-plugin @@ -0,0 +1 @@ +.plugin \ No newline at end of file diff --git a/skills/hol-guard/.codex-plugin b/skills/hol-guard/.codex-plugin new file mode 120000 index 00000000..665797f0 --- /dev/null +++ b/skills/hol-guard/.codex-plugin @@ -0,0 +1 @@ +.plugin \ No newline at end of file diff --git a/skills/hol-guard/.plugin/plugin.json b/skills/hol-guard/.plugin/plugin.json new file mode 100644 index 00000000..22fc8338 --- /dev/null +++ b/skills/hol-guard/.plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "hol-guard", + "version": "1.0.0", + "description": "Use HOL Guard to protect supported local AI harnesses, review Guard approvals and receipts, and scan agent plugins, skills, MCP servers, and marketplace packages before use.", + "author": { + "name": "OpenHands", + "email": "contact@all-hands.dev" + }, + "homepage": "https://hol.org/guard", + "repository": "https://github.com/hashgraph-online/hol-guard-plugin", + "license": "Apache-2.0", + "keywords": [ + "hol-guard", + "security", + "ai-agents", + "plugin-scanner", + "approvals" + ] +} diff --git a/skills/hol-guard/README.md b/skills/hol-guard/README.md new file mode 100644 index 00000000..14f61640 --- /dev/null +++ b/skills/hol-guard/README.md @@ -0,0 +1,34 @@ +# HOL Guard + +This OpenHands skill provides operational guidance for the real HOL Guard security CLI and its separate plugin scanner. + +Use it to: + +- install and verify `hol-guard`; +- protect a local AI harness that HOL Guard currently supports; +- review Guard approvals, receipts, and evidence; +- scan agent skills, plugins, MCP server packages, marketplace packages, or mixed workspaces with `plugin-scanner`. + +It intentionally does not claim a native OpenHands pre-tool interception hook. For OpenHands workspaces, the skill can run Guard and scanner workflows from the agent environment, while harness protection is limited to targets explicitly supported by HOL Guard. + +## Quick start + +```bash +pipx install hol-guard +hol-guard status +hol-guard detect --json +``` + +For package scanning: + +```bash +pipx install plugin-scanner +plugin-scanner lint . +plugin-scanner verify . +``` + +## Sources + +- Product: https://hol.org/guard +- Plugin and Agent Skill: https://github.com/hashgraph-online/hol-guard-plugin +- Runtime: https://github.com/hashgraph-online/hol-guard diff --git a/skills/hol-guard/SKILL.md b/skills/hol-guard/SKILL.md new file mode 100644 index 00000000..df739868 --- /dev/null +++ b/skills/hol-guard/SKILL.md @@ -0,0 +1,108 @@ +--- +name: hol-guard +description: Use HOL Guard to protect supported local AI harnesses, review Guard approvals and receipts, and scan agent plugins, skills, MCP servers, and marketplace packages before use. +triggers: +- hol guard +- hol-guard +- plugin scanner +- plugin-scanner +- ai security +--- + +# HOL Guard + +HOL Guard is a local security layer for AI tooling. In OpenHands, use this skill to install and operate the actual `hol-guard` and `plugin-scanner` CLIs. This skill does not add an OpenHands pre-tool interception hook. Do not claim OpenHands itself is protected unless HOL Guard explicitly supports that harness and a Guard command proves the protection state. + +## Safety rules + +- Never read `.env` files. +- Never bypass a HOL Guard approval or silently convert a review decision into an allow. +- Prefer Guard-owned setup and inspection commands over manual edits to another harness's configuration. +- Treat scanner errors as failures until they are inspected. +- Preserve existing user changes and inspect `git status --short` before editing a repository. +- Do not claim protection, approval, or release readiness without command output proving it. + +## Install and verify + +Install the runtime in an isolated environment when possible: + +```bash +pipx install hol-guard +hol-guard status +hol-guard detect --json +``` + +The scanner is a separate distribution. Install it only when scanning is requested: + +```bash +pipx install plugin-scanner +plugin-scanner verify . --json +``` + +If `pipx` is unavailable, explain that an isolated CLI install is preferred instead of silently modifying the user's Python environment. + +## Protect a supported local harness + +HOL Guard currently supports these harness identifiers: `codex`, `claude-code`, `copilot`, `cursor`, `gemini`, `hermes`, `openclaw`, `opencode`, and `antigravity`. + +For a supported target: + +```bash +hol-guard bootstrap +hol-guard install +hol-guard run --dry-run +hol-guard run +hol-guard status +``` + +Do not substitute `openhands` for ``. OpenHands is not currently a documented HOL Guard harness target. This registry skill makes the Guard CLI available as an operational security workflow; it does not create a native OpenHands execution gate. + +## Review approvals and evidence + +When Guard queues work for review, inspect the request before any decision: + +```bash +hol-guard approvals +hol-guard approvals open +hol-guard receipts +hol-guard diff +``` + +Only approve or deny when the user has explicitly asked for that action after the risk and requested scope are understood. + +For audit or handoff evidence: + +```bash +hol-guard inventory +hol-guard abom --format json +hol-guard events +hol-guard explain +``` + +## Scan an agent package or workspace + +Use `plugin-scanner` for skills, plugins, MCP server packages, marketplace packages, and mixed agent workspaces: + +```bash +plugin-scanner lint . +plugin-scanner verify . +``` + +For a specific package: + +```bash +plugin-scanner lint +plugin-scanner verify +``` + +Scan the repository or package root that contains the relevant `SKILL.md`, MCP configuration, plugin manifest, or marketplace metadata. Scanning is inspection, not proof that a runtime harness is protected. + +## Report results + +Summarize the exact command that ran, what Guard or the scanner found, what remains blocked or risky, and the next user action if one is required. Keep product claims tied to observed command output. + +Upstream sources: + +- HOL Guard product: https://hol.org/guard +- HOL Guard plugin and skill: https://github.com/hashgraph-online/hol-guard-plugin +- HOL Guard runtime: https://github.com/hashgraph-online/hol-guard