hashgraph-online/hol-guard
| | 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.Install HOL GuardRead the documentationPyPI Package (hol-guard)Report an Issue | | :--- | :--- |
catalog 简介 / catalog descriptioncatalog description：Open-source antivirus for AI agents: block risky tools, secret access, prompt injection, malicious packages, MCP servers, plugins, and skills at runtime.
安装Install
dsh plugin --profile web add github:hashgraph-online/hol-guard把 hashgraph-online/hol-guard 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
HOL Guard: Open-Source Antivirus for AI Agents
 |
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. Install HOL Guard Read the documentation PyPI Package ( hol-guard)Report an Issue |
|---|
HOL Guard brings antivirus-style runtime protection to AI agents. It evaluates supported agent actions and local artifacts for secret exposure, prompt injection, unsafe commands, malicious packages, and MCP risks. Guard can allow safe work, block known threats, pause ambiguous actions for approval, and record security receipts for later review.
Use HOL Guard locally without a cloud account. Connect Guard Cloud when you want synchronized evidence, team policies, fleet visibility, and shared approval workflows.
Install HOL Guard
pipx install hol-guard
hol-guard init
hol-guard init discovers compatible AI agents, explains each setup change before applying it, and guides you through your first protected action.
Install guide · Supported agents · Local vs. cloud · Security policy
What HOL Guard Protects
| Threat surface | Guard protection |
|---|---|
| Agent tool calls | Evaluates supported shell, file, MCP, prompt, and tool-result events through native hooks, managed proxies, or reversible launch overlays. |
| Secrets and credentials | Detects sensitive file access, credential-shaped output, staged exfiltration, and suspicious outbound commands. |
| AI supply chain | Reviews package installs, plugins, skills, MCP servers, hooks, and agent configuration before trust is granted. |
| Prompt injection | For adapters that expose prompt events, screens prompt and tool intent for instructions that attempt to expose secrets, evade controls, or trigger destructive behavior. |
| Human approval | Routes ambiguous actions to native prompts, the local approval center, or Guard Cloud according to the active policy. |
| Security evidence | Records attributable receipts and inventory changes so decisions can be reviewed, explained, and synchronized. |
Guard prefers the strongest integration each agent exposes. Enforcement depth varies by agent and event type; see the support matrix for the exact current contract.
Supported AI Agents
HOL Guard currently integrates with Codex, Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Hermes, OpenClaw, OpenCode, Antigravity, Kimi Code, Grok, Pi / oh-my-pi, and ZCode.
These developer agents are Guard's deepest integrations today, but the product boundary is broader: the same policy, supply-chain, approval, and evidence layers are designed to protect AI agents and their local tool ecosystems as new adapters are added.
Why HOL Guard
Most security tools see only one part of an AI agent's attack surface. Code scanners run after files change. Sandboxes constrain a process but do not understand agent intent. MCP gateways see MCP traffic but not local shell commands, package installs, skills, hooks, or agent configuration.
HOL Guard combines those signals at the local runtime boundary. It discovers the agent and its tools, evaluates supported actions against one policy, requests human approval only when needed, and records the resulting decision. The goal is practical protection without turning ordinary AI-assisted work into a stream of prompts.
Choose the Right Package
| If you want to... | Install | Start with |
|---|---|---|
| protect AI agents and their local runtime | hol-guard |
hol-guard init |
| lint and verify plugins, skills, MCP servers, and marketplace packages in CI | plugin-scanner |
plugin-scanner verify . |
hol-guard is the end-user antivirus and runtime protection product. plugin-scanner is the maintainer and CI companion for analyzing agent ecosystem packages before release.
Guard Operations
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
pipx run hol-guard command test 'git reset --hard HEAD~1'
pipx run hol-guard command explain 'grep "rm -rf|git clean" README.md'
pipx run hol-guard command extensions
What you get from Guard:
- Detects supported AI agent configuration 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.
Inspect command protection without running it
Command safety extensions make Guard's shell, Git, filesystem, system, Windows, data-protection, container, Kubernetes, encoded-execution, and self-protection behavior inspectable. Required core extensions cannot be mistaken for optional integrations. They are built-in capability boundaries over the same parser used by harness hooks, not downloadable regex bundles.
Each extension publishes stable rule IDs and structured rule metadata. Command inspection also returns a canonical, side-effect-free parse model with wrapper, pipeline, environment-override, provenance, and confidence details so automation can distinguish exact parsing from malformed or unsupported input.
Use command test for a concise classification and command explain for the complete evaluation trace. Both are
side-effect free: they do not execute the command, evaluate final policy, create an approval, or record a receipt.
Use --json for a stable automation contract.
hol-guard command test 'rm -rf ./build'
hol-guard command explain 'grep "rm -rf|git clean" README.md'
hol-guard command extensions command.git --json
Structured core rules preserve every match in a compound command. A Git preview such as git clean -ndx remains
safe, while an unrelated destructive segment still produces review. New structured coverage feeds the same runtime
artifact and policy pipeline as existing command classifications.
Guard commands at a glance
hol-guard startShows the next step for the harnesses Guard found.hol-guard initRuns first-run onboarding as approval checkpoints: local dashboard, harness discovery and install, optional Guard Cloud connect, and desktop notification setup.hol-guard bootstrapDetects the best local harness, starts the approval center, and installs Guard in front of it.hol-guard hermes bootstrapInstalls the Guard-managed Hermes overlay bundle directly.hol-guard statusShows what Guard is watching now.hol-guard install <harness>Creates the launcher shim for that harness.hol-guard uninstall --selfRemoves Guard-managed harness wiring, package shims, local Guard state, and uninstalls the currenthol-guardpackage.hol-guard updateUpdates the installedhol-guardpackage in the current environment.hol-guard run <harness> --dry-runRecords 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 approvalsLists pending approvals or resolves them from the terminal.hol-guard receiptsShows local approval and block history.
Harness approval strategy
claude-codeGuard prefers Claude hooks first, then the local approval center when the shell cannot prompt.copilotGuard can wrap thecopilotCLI, detect~/.copilot/config.json,~/.copilot/mcp-config.json, workspace.vscode/mcp.json, and install Guard-managed Copilot hook wiring for documentedpreToolUseandpostToolUseevents. 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.codexGuard 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 forcodex execor 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 headlesscodex execsessions resume throughcodex exec resumewith 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.cursorGuard respects Cursor’s native tool approval and focuses on artifact trust before launch.opencodeGuard authors package-level policy while OpenCode keeps native once, always, or reject prompts for managed MCP tools.kimiGuard installs managedPreToolUseandUserPromptSubmithooks in~/.kimi-code/config.toml, blocks with exit code2and a JSONpermissionDecision: "deny"response, and fails open on hook crash or timeout.grokGuard installs a catch-all GrokPreToolUsehook plus observe-only prompt and subagent hooks under~/.grok/hooks/, writes permission deny rules and backup hooks in~/.grok/managed_config.toml, blocks tool calls with exit code2and a Grok-native{"decision":"deny"}response, never reads~/.grok/auth, and launches only a trusted absolute Grok executable. Custom install roots can be selected once withhol-guard run grok --grok-executable /absolute/path/to/grok. After upgrading an existing Grok install, runhol-guard apps repair grokso the catch-all hook replaces the older per-tool matcher list.piGuard scans~/.pi/agent/and project.pi/packages, extensions, skills, prompts, and themes; installs a managed Pi extension that reviewsinputandtool_callevents inline; and blocks with a Pi-native{"decision":"deny"}response when Guard policy says no.zcodeGuard detects~/.zcode/cli/config.json, configured MCP servers, enabled plugins, the plugin cache, and plugin manifests; installs managedPreToolUseandUserPromptSubmithooks in the confighookssection without touching usermcporplugins; and blocks with exit code2and apermissionDecision: "deny"response.hermesGuard installs a managed Hermes overlay bundle, routes MCP servers through Guard proxies, and prefers native-or-center delivery for blocked requests.geminiGuard scans extensions and falls back to the local approval center for blocked changes.
Guard: Protection Levels
HOL Guard is antivirus for AI agents. It evaluates supported runtime events and local artifacts, then applies the active policy before execution where the agent provides a pre-action boundary. Other integrations use native approval, managed proxy, launch-time, or post-action evidence surfaces according to the support matrix.
Choose a protection level with hol-guard settings set security-level <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:
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:
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.
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, it replaces password proof and cooldown is disabled, so every protected action requires a current authenticator code. 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. When TOTP is enabled, disabling TOTP or the password gate requires a current authenticator code instead of the password.
Approval proof creates only a 30-second, transaction-local grant for the exact action, scope, subject, and session nonce being processed. The grant is never returned to the browser or reused as a general login session. Guard tracks password and authenticator failures independently and locks the active factor after five failed attempts; rotating either factor revokes outstanding grants and any saved recovery, session, or trusted-device state.
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 connect to connect a free account, or hol-guard connect --headless on SSH/CI hosts.
Scanner Quickstart
pipx install plugin-scanner
plugin-scanner lint .
plugin-scanner verify .
# 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
- 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:
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
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.
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.14 and directly pins LiteLLM 1.93.0 so bare pip and pipx installs cannot drift to an unverified LiteLLM release.
Resolver-safe Cisco extra
Install the Cisco extra on Python 3.11 through 3.14 when you want to explicitly select the Cisco dependency surface in addition to the baseline skill scanner:
pip install "hol-guard[cisco]"
pip install "plugin-scanner[cisco]"
cisco-ai-mcp-scanner stays in the repo-controlled cisco-mcp uv dependency group and now pins Cisco's LiteLLM 1.93.0-compatible release so Docker and CI can install full Cisco coverage natively on Python 3.11.4 through 3.14. The published cisco extra remains resolver-safe for pip users.
On Guard surfaces, the Cisco extra keeps the LiteLLM-dependent Cisco skill-scanner path on a patched resolver-safe version. Repo-controlled Docker and uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13 installs add optional Cisco MCP evidence to hol-guard scan, hol-guard preflight, and hol-guard explain <path>. 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 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 |
repo-controlled CI/Docker only | Installed through the uv cisco-mcp group and Docker requirements with LiteLLM 1.93.0. |
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:
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 .
DevContainer / Codespaces
Add HOL Guard to your devcontainer.json for automatic protection in VS Code Codespaces and remote dev containers:
{
"features": {
"ghcr.io/hashgraph-online/hol-guard/hol-guard:1": {}
}
}
Options:
| Option | Default | Description |
|---|---|---|
version |
latest |
Pin to a specific release (e.g. 2.0.1004) |
initHarness |
auto |
Harness to configure: auto (detect installed), none (skip init), or a specific name (codex, claude-code, cursor, gemini, opencode, pi) — informational, Guard auto-detects regardless |
strictMode |
false |
Enable strict mode on install |
See devcontainer-features/hol-guard/README.md for details.
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 |
| DeepSeek Harness | package.json with dsh.bundle, declared patch file, and Cordis apply(ctx) runtime export |
| Gemini CLI | gemini-extension.json, commands/**/*.toml |
| Kimi Code | kimi.plugin.json, .kimi-plugin/plugin.json, declared skills, agents, commands, prompts, and MCP servers |
| 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:
scanfor full-surface security and release analysislintfor rule-oriented authoring feedbackverifyfor runtime and install-surface readiness checkssubmitfor artifact-backed submission gatingdoctorfor 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
# Scan a plugin directory
plugin-scanner scan ./my-plugin
# Auto-detect all supported ecosystems inside a repo (default)
plugin-scanner scan ./plugins-repo --ecosystem auto
# Scan only Claude package surfaces
plugin-scanner scan ./plugins-repo --ecosystem claude
# Scan only native Kimi Code plugin surfaces
plugin-scanner scan ./plugins-repo --ecosystem kimi
# Scan a native DeepSeek Harness (DSH/Cordis) package
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
# List supported ecosystems
plugin-scanner --list-ecosystems
# Output JSON
plugin-scanner scan ./my-plugin --format json
# Write a SARIF report for GitHub code scanning
plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
# Fail CI on findings at or above high severity
plugin-scanner scan ./my-plugin --fail-on-severity high
# 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.
| Need | Command | Output contract |
|---|---|---|
| Human release summary | plugin-scanner scan ./my-plugin |
terminal summary first, optional JSON/Markdown/SARIF with --format |
| Rule-level authoring feedback | plugin-scanner lint ./my-plugin |
human findings by default, JSON with --format json |
| Runtime readiness details | plugin-scanner verify ./my-plugin |
human pass/fail by default, JSON with --format json |
| Publishable quality artifact | plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json |
writes one artifact for one plugin directory |
| Troubleshooting bundle | plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip |
diagnostic JSON and bundle artifacts |
Quality Suite Commands
# Summary scan (legacy form still works)
plugin-scanner scan ./my-plugin --format json --profile public-marketplace
# Scan a multi-plugin repo from the marketplace root
plugin-scanner scan . --format json
# 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
# Runtime readiness verification
plugin-scanner verify ./my-plugin --format json
plugin-scanner verify . --format json
plugin-scanner verify ./my-plugin --online --format text
# Artifact-backed submission gate
plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json
# Diagnostic bundle
plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip
Advanced reference: specs, action publishing, automation, and examples
Codex Spec Alignment
The scanner follows the current Codex plugin packaging conventions more closely:
- local manifest paths should use
./prefixes .agents/plugins/marketplace.jsonis the preferred marketplace manifest location- root
marketplace.jsonis still supported in compatibility mode interfacemetadata no longer requires an undocumentedtypefieldverifyperforms an MCP initialize handshake before probing declared capabilities
lint --fix preserves or adds the documented ./ prefixes instead of stripping them away.
For repo-scoped marketplaces, scan, lint, verify, and doctor can target the repository root directly. submit remains intentionally single-plugin so the emitted artifact points at one concrete plugin package.
Config + Baseline Example
# .plugin-scanner.toml
[scanner]
profile = "public-marketplace"
baseline_file = "baseline.txt"
ignore_paths = ["tests/*", "fixtures/*"]
[rules]
disabled = ["README_MISSING"]
severity_overrides = { CODEXIGNORE_MISSING = "low" }
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)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Report Formats
| Format | Use Case |
|---|---|
text |
Human-readable terminal summary with category totals and findings |
json |
Structured integrations and findings for tooling and dashboards |
markdown |
Pull request, issue, or review-ready summaries |
sarif |
GitHub code scanning uploads and security automation |
Scanner Signals
The scanner currently detects or validates:
- Hardcoded secrets such as AWS keys, GitHub tokens, OpenAI keys, Slack tokens, GitLab tokens, and generic password or token patterns
- Dangerous MCP command patterns such as
rm -rf,sudo,curl|sh,wget|sh,eval,exec, and PowerShell orcmd /cshells - Insecure MCP remotes, including non-HTTPS endpoints and non-loopback HTTP transports
- Risky Codex defaults such as approval bypass and unrestricted sandbox defaults inside shipped plugin config or docs
- Publishability issues in
interfacemetadata, HTTPS links, and declared asset paths - Workflow hardening gaps including unpinned third-party actions,
write-all, privileged checkout patterns, missing Dependabot, and missing lockfiles - Skill-level issues surfaced by Cisco
skill-scannerwhen the optional integration is installed - Static MCP findings surfaced by Cisco
mcp-scannerwhen the repo-controlled Docker image orcisco-mcpuv group is installed
CI And Automation
Add the scanner to a plugin repository CI job:
permissions:
contents: read
security-events: write
jobs:
scan-plugin:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: hashgraph-online/ai-plugin-scanner-action@v1
with:
plugin_dir: "."
mode: scan
profile: public-marketplace
min_score: 80
fail_on_severity: high
format: sarif
upload_sarif: true
For a multi-plugin repo, the same workflow can stay pointed at plugin_dir: "." as long as the repository has .agents/plugins/marketplace.json with local ./plugins/... entries.
For repo-controlled validation in this repository, Linux jobs that target full coverage install the cisco extra on Python 3.12, while the baseline matrix keeps Python 3.10 compatibility explicit.
Local pre-commit style hook:
repos:
- repo: local
hooks:
- id: plugin-scanner
name: Plugin Scanner
entry: plugin-scanner
language: system
types: [directory]
pass_filenames: false
args: ["./"]
GitHub Action
The Marketplace action lives in the dedicated repository hashgraph-online/ai-plugin-scanner-action.
The Marketplace action bundle is maintained in action/ and published automatically to hashgraph-online/ai-plugin-scanner-action by .github/workflows/publish-action-repo.yml after each PyPI release. The legacy alias hashgraph-online/hol-codex-plugin-scanner-action remains available for existing workflows.
When you run the scanner in your own job instead of the packaged action, install plugin-scanner[cisco] on Python 3.11 through 3.14 for the resolver-safe Cisco skill-scanner path. Use the repo-controlled Docker image or uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13 when you also need Cisco MCP coverage with CISCO_MCP_SCAN=auto or CISCO_MCP_SCAN=on.
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, andfindings_totalas 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:
- Add the scanner action to plugin CI.
- Require
min_score: 80and a severity gate such asfail_on_severity: high. - Enable submission mode with a token that has
issues:writeonhashgraph-online/awesome-codex-plugins. - When the plugin clears the threshold, the action opens or reuses a submission issue.
- 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.
Development
pip install -e ".[dev,cisco]"
ruff check src tests
ruff format --check src
pytest -q
python -m build
Use pip install -e ".[dev]" or uv sync --extra dev --python 3.10 when you need the lean baseline path without the Cisco MCP extra.
Repository Workflows
- Matrix CI for Python
3.10through3.13 - Package publishing via the
publish.ymlworkflow - OpenSSF Scorecard automation for repository hardening visibility
Security
For disclosure and response policy, see SECURITY.md.
Contributing
Contribution guidance lives in CONTRIBUTING.md.
Maintainers
Maintained by HOL.
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.
Resources
- HOL Plugin Registry
- HOL Plugin Security dataset on Hugging Face
- HOL Standards Documentation
- OpenAI Codex Plugin Documentation
- Model Context Protocol Documentation
- Cisco AI Skill Scanner
- Cisco AI MCP Scanner
- HOL GitHub Organization
A scan is not a safety guarantee. Runtime benchmark fixtures in the dataset are modeled, not live attacks. The dataset's ~205 scored plugins are the plugin catalog, not the Registry Broker agent catalog. Hashgraph Online's org-wide GitHub star total is not a star count for this repository.
License
Apache-2.0
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …