HaluGard

Anti-hallucination MCP server for AI agents.

HaluGard is a guardrail layer that sits between an AI agent and its tools. It intercepts agent input and output through four gates, blocking fabricated claims, identity drift, credential leaks, and dangerous commands before they reach the user or the system.

Built in Go (pure, no cgo) with an optional Python semantic layer for embedding-based claim verification.

Why

AI agents hallucinate. They claim to have run tools they never ran, fabricate scan results, invent credentials, and drift from their assigned identity. HaluGard exists to catch these failures in real time, fail-closed, with zero false positives on legitimate output.

Features

• 4-gate dual-stage pipeline
  • G1: input safety (injection, dangerous commands, path validation)
  • G2: claim verification (regex + semantic grounding against tool evidence)
  • G3: reasoning (loop detection, contradiction, cross-turn consistency)
  • G4: output filter (identity drift, credential leak, fabrication markers)
• Shell hooks via Hermes Agent config (pre_tool_call, post_tool_call, transform_llm_output)
• Shadow mode (log only) and enforce mode (block via exit code)
• SQLite WAL persistence with AES-GCM encryption at rest
• Pattern YAML loader — extensible detection patterns (EN + ID)
• Config guard — SHA256 hash, reverts on tamper
• Semantic layer (Phase 2) — Python gRPC server with all-MiniLM-L6-v2 embeddings
• Fail-closed — if the guard crashes, the hook blocks the action

Tech Stack

• Go 1.25 (pure Go, no cgo)
• modernc.org/sqlite v1.53.0 (pure Go SQLite)
• golang.org/x/text (Unicode normalization)
• MCP 2024-11-05 (shell hooks via Hermes config)
• Python 3.11 (semantic layer only)
• sentence-transformers/all-MiniLM-L6-v2 (embedding model)
• Windows 10 primary target

Install

Option 1: Download Binary

Download the latest release from the Releases page. No build tools required.

Option 2: Build from Source

Requires Go 1.25+:

git clone <repo-url>
cd halugard
go build -o halugard-mcp ./cmd/halugard-mcp

Optional: semantic layer (Phase 2)

The semantic layer requires a Python gRPC server running on port 50051.

cd halugard-slow
pip install grpcio grpcio-tools sentence-transformers
python server.py

The Go binary connects automatically when --python-enabled is passed.

Usage

Standalone (regex-only mode)

echo '{"output":"logged in as admin@x.com:pass","tool_results":[],"session_id":"test","turn":1}' | ./halugard-mcp --hook transform_llm_output

Semantic-assisted mode

echo '{"output":"...","tool_results":[...],"session_id":"test","turn":1}' | ./halugard-mcp --hook transform_llm_output --python-enabled

Shadow mode (log only, no blocking)

./halugard-mcp --mode shadow --db ./halugard.db

Enforce mode (block on detection)

./halugard-mcp --mode enforce --db ./halugard.db

Hermes Integration

Copy config.example.yaml to your Hermes config and adjust the paths:

cp config.example.yaml ~/.hermes/config.yaml

Or add manually to your existing ~/.hermes/config.yaml:

hooks:
  pre_tool_call:
    - command: "/path/to/halugard-mcp --hook pre_tool_call --mode enforce --db /path/to/halugard.db"
      timeout: 5000
  post_tool_call:
    - command: "/path/to/halugard-mcp --hook post_tool_call --mode enforce --db /path/to/halugard.db"
      timeout: 5000
  transform_llm_output:
    - command: "/path/to/halugard-mcp --hook transform_llm_output --mode enforce --db /path/to/halugard.db"
      timeout: 10000

For semantic-assisted mode, append --python-enabled to each command and start the semantic server:

cd halugard-slow
pip install -r requirements.txt
python server.py

Benchmark

python eval/run_benchmark.py

Validate dataset format before editing:

python eval/validate_dataset.py

Project Structure

halugard/
  go.mod
  cmd/halugard-mcp/main.go
  internal/
    models.go
    normalize.go
    pipeline.go
    gate1_input_safety.go
    gate2_claim_verify.go
    gate3_reasoning.go
    gate4_output.go
    sqlite.go
    pattern_loader.go
    grpc_client.go
  halugard-slow/
    server.py
    gate2_semantic.py
    embedding.py
    circuit_breaker.py
  patterns/
    en/ (injection, drift, claims)
    id/ (injection, drift, claims)
  eval/
    datasets/*.jsonl
    run_benchmark.py
    validate_dataset.py

Contributing

See CONTRIBUTING.md for how to contribute datasets, patterns, and code.

Phase 3 contribution guide: DATASET_TEMPLATE.md.

License

MIT