convez.ai
MCP ServerSegurançaAvançado
HWyn2020

HiveGuard MCP Wrapper

HWyn2020/hiveguard-mcp-wrapper

Gateway de segurança MCP com invariantes HiveGuard para qualquer agente

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe agentes HiveGuard ou qualquer agente como serviço seguro com primitivas de segurança endurecidas: DNS-pinned URL fetch, scrubbing de saída e redação de PII com validação de dígitos verificadores. Opera em dois modos: wrapping de agentes HiveGuard existentes ou gateway de segurança puro para qualquer framework (OpenClaw, LangChain, Mastra).

Instalação

$npx convez-ai HWyn2020/hiveguard-mcp-wrapper

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Proteger operações arriscadas (fetch URL, hashing, processamento de dados sensíveis) em agentes multi-framework
  • Expor agentes HiveGuard como serviços MCP com enforcement automático de políticas de segurança
  • Implementar redação de PII e scrubbing de saída em tempo real para agentes TS/JS rodando OpenClaw ou LangChain.js

Veredito

Ferramenta de segurança robusta e bem testada (303 testes, 3 camadas de revisão) que resolve um problema real: trazer garantias de segurança HiveGuard para agentes em qualquer linguagem via MCP. Implementação madura e bem documentada com dois modos operacionais flexíveis.

README

A tradução para o português deste README ainda está na fila.

hiveguard-mcp-wrapper

License: MIT Python Tests: 303 green Reviews: 3 layers

Bring HiveGuard-grade security to any agent framework via the Model Context Protocol.

Wrap a Python HiveGuard BaseAgent as an MCP server (Mode A), or run as a pure security gateway exposing primitive tools (Mode B) that any agent — OpenClaw, LangChain, Mastra, Hermes, custom — can call for risky operations like URL fetching, hashing, or output scrubbing.


What this is

The reference MCP wrapper for the HiveGuard security framework. One open-source bridge between HiveGuard's 20-invariant security spec and the world of MCP-compatible AI runtimes (OpenClaw, Claude Desktop, and any other client implementing the MCP standard).

Two operating modes (use either or both):

Mode A — Wrap a HiveGuard agent

You wrote (or installed) a Python agent extending BaseAgent. Mark methods with @expose_as_mcp_tool, hand the agent to HiveGuardMCPServer, and any MCP client can call those methods as tools — with HiveGuard's enforcement decorators still applied inside.

Mode B — Pure security gateway

No HiveGuard agent. The wrapper exposes primitive tools (fetch_url_safe, hash_data, validate_input, scrub_output) that any MCP client can call for risky operations. The gateway enforces HiveGuard invariants (INV-08, INV-11, INV-12, INV-16, INV-19) on those primitives, regardless of which framework the calling agent was built in.

This makes it possible for a TypeScript OpenClaw agent — or LangChain.js, Mastra, Hermes, an in-house TS agent, anything — to get HiveGuard-grade security on its risky operations without porting any code.


Install

pip install hiveguard-mcp-wrapper

Pulls in hiveguard-security-core, the official MCP SDK, pydantic, and uvicorn/starlette for the HTTP transport.


Quick start — Mode A

Wrap a HiveGuard agent:

from framework.agents.base_agent import BaseAgent
from framework.security.enforcement import (
    audit_logged, sanitize_input, rate_limited,
)
from hiveguard_mcp_wrapper import HiveGuardMCPServer, expose_as_mcp_tool


class MyAgent(BaseAgent):
    @expose_as_mcp_tool(name="echo")
    @audit_logged()
    @sanitize_input()
    @rate_limited(max_calls=60, window_seconds=60)
    async def echo(self, message: str) -> dict:
        return {"echo": message}


agent = MyAgent("my-agent", agent_type="custom", port=3201)
server = HiveGuardMCPServer(agent=agent, name="my-agent-mcp")

from hiveguard_mcp_wrapper.transport_http import serve_http
serve_http(server, host="127.0.0.1", port=7301)

Now any MCP client can call echo (plus the default tools health, lifecycle_state, audit_log_recent, invariant_inventory).


Quick start — Mode B (gateway only)

from hiveguard_mcp_wrapper import HiveGuardMCPServer
from hiveguard_mcp_wrapper.gateway import build_gateway_tools
from hiveguard_mcp_wrapper.transport_http import serve_http

server = HiveGuardMCPServer(
    agent=None,
    name="hiveguard-gateway",
    gateway_tools=build_gateway_tools(),
)
serve_http(server, host="127.0.0.1", port=7301)

Now any MCP client can call fetch_url_safe, hash_data, validate_input, scrub_output — all enforcing HiveGuard invariants.


OpenClaw integration

Add to your OpenClaw MCP Registry config:

{
  "mcps": {
    "hiveguard": {
      "url": "http://127.0.0.1:7301/mcp",
      "transport": "http"
    }
  }
}

Restart OpenClaw. The HiveGuard tools are now first-class tools in OpenClaw. Use them like any other tool. Same pattern works for LangChain.js, Mastra, Hermes, and any other MCP-compatible host.


CLI

The hiveguard-mcp-serve command starts the wrapper without writing any code:

# Mode A — wrap an agent
hiveguard-mcp-serve --agent my_pkg.agents:MyAgent --port 7301

# Mode B — gateway only
hiveguard-mcp-serve --gateway-only --port 7301

# Both modes on the same server
hiveguard-mcp-serve --agent my_pkg.agents:MyAgent --with-gateway --port 7301

# Network exposure (auto-requires HIVEGUARD_MCP_TOKEN env var)
HIVEGUARD_MCP_TOKEN=$(openssl rand -hex 32) \
  hiveguard-mcp-serve --gateway-only --bind 0.0.0.0 --port 7301

What gets enforced (the security model)

The wrapper applies multiple layers of defense for every request:

  1. Header validation — rejects request smuggling (CL+TE conflicts), unknown content types, malformed transfer-encoding
  2. Body size cap — 256 KiB default at server layer, 4 MiB at HTTP transport layer (configurable via env)
  3. Bearer auth — required on non-loopback bind. Token compared in constant time. After 5 failed attempts in 60s, source blocked for 5 minutes.
  4. Strict JSON parsing — capped at 24 levels of nesting, 100k keys per object/array. Malformed UTF-8 rejected.
  5. Concurrency cap — 8 in-flight tool calls per identity by default
  6. Tool timeout — 30s wall-clock per tool call (configurable, per-tool override)
  7. Lifecycle gate — calls to agents in FROZEN / ESCALATED / DECOMMISSIONED state rejected with structured error
  8. Output scrubbing — recursive scan for sensitive substrings (api_key, password, secret, token, credential, private_key, session_id, authorization, bearer, cookie, csrf, x-auth, aws_*). Belt-and-braces over INV-08.
  9. Error scrubbing — exception messages NEVER leak to the client. Stack traces NEVER leak. Internal-error responses are generic.
  10. Audit log — every auth failure, every invariant block, every tool call logged in structured JSON with PII scrubbed.

See SECURITY.md for the full threat model + hardening checklist.


How the tests stay honest

The test suite is split into:

  • Unit tests for each module (decorator, hardening primitives, error mapping)
  • Integration tests for the full request pipeline
  • Red-team tests that simulate adversarial inputs across 6 attack directions: external observer (T1), auth bypass (T2), input poisoning (T3), output exfiltration (T4), resource exhaustion (T5), privilege escalation (T6)

All 113 tests pass on every commit. If you find a way around the wrapper's defenses, please report it via security@ubava.ee — we'll add a regression test, fix it, and credit you.

# Run the test suite
pytest -v

# With coverage
pytest --cov=hiveguard_mcp_wrapper --cov-report=html

Configuration via environment

VariableDefaultPurpose
HIVEGUARD_MCP_TOKEN(unset)Bearer auth token. Required for non-loopback bind.
HIVEGUARD_MCP_MAX_BODY_BYTES262144Max request body size at server layer
HIVEGUARD_MCP_TOOL_TIMEOUT_S30.0Max wall-clock per tool call
HIVEGUARD_MCP_MAX_CONCURRENT_PER_TOKEN8In-flight cap per identity

Relationship to the HiveGuard family

hiveguard-security-core   ← The 20-invariant spec + 12 enforced decorators
                              + BaseAgent + lifecycle. Open-source MIT.

hiveguard-mcp-wrapper     ← THIS repo. Bridges security-core agents to
                              MCP-compatible runtimes. Open-source MIT.

hiveguard-agents          ← Commercial. Pre-built agents (Scout, Analyst,
                              Fixer, WebScout). Tumbler Vaults, BDP,
                              JurisdictionEngine. Sold as managed service
                              via ubava.ee.

For commercial use of the pre-built agents (Scout/Analyst/Fixer/WebScout) and for EU AI Act + GDPR compliance via UBava's relay, see ubava.ee and hiveguard.ee.


License

MIT. Use commercially. Attribute via the copyright notice.


Built by

UBava OÜ — Privacy-First Relay, Built for Europe.

Ver o original no GitHub

Bom para

Relacionados