Local-first AI agent security evidence and approval workflows through HOL Guard's stdio MCP server.
io.github.hashgraph-online/hol-guard MCP Server
This MCP server provides local-first AI agent security evidence and approval workflows through HOL Guard’s stdio MCP server. It is aimed at devsecops-style controls for AI agents, including runtime and prompt-injection related security, secrets detection, and supply-chain security.
🛠️ Key Features
Local-first AI agent security evidence
Approval workflows
HOL Guard stdio MCP server
🚀 Use Cases
Agent-security checks before approving actions
Detecting secrets and runtime security issues
Mitigating prompt-injection risks
Supporting supply-chain security concerns
⚡ Developer Benefits
Security evidence collection for AI agents
Workflow-based approvals for agent operations
Alignment with MCP security workflows
⚠️ Limitations
Limited description available: tooling capabilities beyond “evidence and approval workflows” are not specified in the provided data.
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.
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.
Run it locally without an account. Use the CLI and local dashboard to manage protection, resolve approvals, and inspect decision history. Optional Guard Cloud adds shared history, team policy, and fleet management.
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.
Evaluates supported package-manager operations against supply-chain intelligence before installation.
Plugins, skills, and agent configuration
Inventories local artifacts and reviews new or changed tools before launch.
MCP servers and tools
Inspects server configuration and reviews tool calls through supported hooks and managed proxies.
Prompts and tool results
Screens supported events for prompt injection and sensitive content.
Approvals and evidence
Routes decisions to native prompts or the approval center, and records local receipts for review.
Guard connects through native agent hooks, managed MCP proxies, and launch integrations. Coverage depends on the events each agent exposes; the support matrix documents enforcement, approval delivery, and failure behavior per integration.
Supported AI Agents
Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, Grok, Hermes, Kimi Code, Pi, oh-my-pi, OpenClaw, OpenCode, Antigravity, and ZCode. Paseo is supported through these native provider integrations, with per-provider coverage.
For example, to set up Codex explicitly:
bash
hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
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.
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.
The Extension directory lists command coverage generated from the runtime registry. External contributions require explicit opt-in; required core protections remain enabled. To add coverage, follow the Extension contribution guide.
The package verdict includes the available advisory evidence and ecosystem coverage. See the get-started guide for package-manager interception and the remediation guide for handling false positives.
Plugin Scanner
This repository also ships plugin-scanner, a CLI for maintainers who want security and quality checks before publishing agent plugins, skills, and MCP integrations.
Security findings and a quality report across detected package surfaces.
lint
Rule-level authoring feedback.
verify
Install-surface and runtime readiness checks.
submit
A submission artifact for one plugin package.
doctor
Component diagnostics and troubleshooting bundles.
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.
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.
Quality grades use the checks applicable to each package. Trust scoring has separate provenance and weights; see the skill, MCP, and plugin scoring references.
See the action documentation for SARIF uploads, submission workflows, and machine-readable outputs. The action source is maintained in action/.
Optional Cisco analysis
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:
bash
pipx install 'plugin-scanner[cisco]'
For Cisco MCP analysis, use the repository's Docker image or the cisco-mcp dependency group:
bash
uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13
uv run plugin-scanner scan . --cisco-skill-scan on --cisco-mcp-scan on
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.
Use --ecosystem auto to detect supported packages in a repository, or select an ecosystem explicitly:
bash
plugin-scanner scan ./plugins-repo --ecosystem claude
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
What The Scanner Checks
Category
Coverage
Manifest validation
Required fields, versions, declared paths, interface metadata, links, and assets.
Security
Hardcoded secrets, unsafe MCP commands and transports, and risky approval defaults.
Operational security
GitHub Actions permissions and pinned dependencies, privileged checkout patterns, Dependabot, and lockfiles.
Plugin packaging
README and license files, skill frontmatter, ignore rules, and accidentally committed environment files.
Marketplace
Manifest validity, local package discovery, and safe source paths.
Skill and MCP analysis
Analyzer availability, findings, and analyzability from optional Cisco integrations.
Code quality
Dynamic code execution and shell-injection patterns.
How Trust Scoring Works
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.
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:
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.
Report Formats
Format
Use
text
Terminal summaries with category totals and findings.
json
Structured reports for scripts and integrations.
markdown
Review-ready reports for pull requests and issues.
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.
See the action's input reference for submission_score_threshold, submission_token, and the target repository options.
Registry Payload For Plugin Ecosystem Automation
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.
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.
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.
Frequently Asked Questions
What is HOL Guard?
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.
Does HOL Guard work without a cloud account?
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 for the feature boundary.
Which AI agents does HOL Guard support?
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, and ZCode. Paseo is supported through these native provider integrations, with per-provider coverage. The support matrix explains which events and enforcement paths each adapter supports.
What is the difference between HOL Guard and Plugin Scanner?
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.
How does HOL Guard protect MCP servers?
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.
Why did Guard pause my command?
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.
Use the Extension Builder CLI to turn exported command metadata or an MCP tool inventory into contribution files and tests. It works offline: it reads the export without importing or running the target tool.
1. Propose the coverage. Check the Extension directory for existing coverage. For a new capability, open an Extension proposal with the proposed command.<name> ID, supported operations, destructive examples, safe counterparts, and upstream references. Extend an existing extension when it already owns the operation.
Follow the development setup, then run the examples below from your HOL Guard checkout. uv run --no-sync uses that checkout's installed development version.
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.
The output directory must be new, with an existing parent directory. The kit includes discovery.json, review.json, report.json, contribution metadata, a native detector, generated tests, and a file manifest.
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.
For MCP contributions, the generator uses --launcher and --package instead of --executable. See the MCP kit example for a complete command and pagination requirements.
3. Review the operations and regenerate. Read report.json and compare the discovered operations with the upstream implementation. Copy the review file before editing:
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 includes a complete entry example.
Recompile from the saved snapshot rather than editing generated detectors or manifests:
The write applies the reviewed plan to contribution files, the external trust map, catalog registration, packaging, and authoring ownership records. Existing IDs or conflicting files stop integration for review.
5. Test and submit a pull request. For the samplectl example:
bash
uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
uv run --no-sync pytest -q tests/test_generated_cli_samplectl_extension.py
uv run --no-sync pytest -q \
tests/test_guard_extension_contribution.py \
tests/test_guard_extension_trust.py \
tests/test_guard_command_extension_registry.py
uv run --no-sync python scripts/render_command_extension_directory.py
uv run --no-sync python scripts/render_command_extension_directory.py --check
git diff --check
Use your generated test filename for a different slug. Add cases for destructive operations, safe previews, aliases, reordered flags, quoting, malformed input, and compound commands. Run lint and formatting checks on changed Python files. Inspect the final diff, commit the integration and regenerated directory, and open a PR against main linking the proposal and test results. Include the generated authoring records; keep scratch kit directories and raw upstream exports out of the PR.
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 detector cannot weaken Guard's required protections.
Clone the repository and install the development dependencies with uv:
bash
git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --extra dev
uv run ruff check src tests
uv run ruff format --check src tests
uv run pytest --tb=short
uv build
For optional Cisco coverage, use the dependency group command above. See CONTRIBUTING.md for contribution requirements and the testing matrix for integration tests.
