Hetzer 🛡️

Local Credential Vault and Leak-Reduction Tools for AI Agents
Regex & entropy scanner • AES-256-GCM Grimoire Vault • Dual Git commit & message guards • Canary tripwires • Agent integration skills.

⚡ Quickstart (Zero-Install via npx)

Hetzer runs instantly on any machine with Node.js installed without requiring global installation:

# 🔥 The 1-Command Speedrun for Vibe Coders: Arms skills, git hook, and vaults .env in 1.5s
npx hetzer protect

# Or perform individual actions:
# 1. Install credential-safety guidance for supported AI agents
npx hetzer skill install

# 2. Install Dual Git Guards (blocks staged tokens/.env via pre-commit, raw secrets in commit-msg)
npx hetzer hook install

# 3. Store credentials & API keys into encrypted Grimoire Vault (AES-256-GCM)
npx hetzer creds set openai-api-key

Permanent Installation Options:

• One-Line Script (Linux & macOS):

  curl -fsSL https://raw.githubusercontent.com/agunggnn/hetzer/main/install.sh | bash
  

• One-Line Script (Windows PowerShell):

  irm https://raw.githubusercontent.com/agunggnn/hetzer/main/install.ps1 | iex
  

• Via GitHub Packages (Direct from this repo):

  npm install -g @agunggnn/hetzer --registry=https://npm.pkg.github.com
  

• Via NPM Registry:

  npm install -g hetzer
  

📑 Modular Documentation

For structured navigation and deep architectural insights, explore the dedicated documentation guides:

⚡ What is Hetzer?

Hetzer is a local-first credential vault and command-line defense layer. It reduces accidental credential exposure in supported workflows; it is not a complete security boundary for an OS user or an AI agent with unrestricted file and process access.

With Hetzer, you get:

1. Secret scanner: Scans explicitly supplied text for supported provider tokens, credentialed database URLs, bounded private-key blocks, and high-entropy candidates.
2. Grimoire Vault (AES-256-GCM): SQLite-backed encrypted credential storage. Configuration can use secretRef:<id> in place of plaintext values.
3. Agent integrations & MCP Virtual Proxy: Installs guidance and MCP configuration for Hermes Agent, Google Antigravity, OpenCode, CommandCode, Cursor, Claude, Cline, Codex, and Gemini. Virtual proxy resolves secretRef:<id> in tool arguments and sanitizes outgoing responses.
4. Dual Git Guards (pre-commit & commit-msg): Inspects staged filenames, diff additions before commit, and validates commit messages against raw credentials.
5. Canary Honey-Tokens & Active Stream Tripwires: Deploys decoy canary tokens (HETZER_CANARY_TOKEN, canary-*). Guarded resolution aborts with exit code 43. Guarded subprocesses (hetzer exec --canary) terminate child processes if canary tokens leak into stdout/stderr.
6. HTTP Credential Broker: Loopback proxy (127.0.0.1) injecting upstream credentials via ephemeral capabilities without exposing raw secrets to child environments.
7. 9Router AI Gateway & Cognee Memory (Optional Full-Stack): Multi-provider model routing with automatic fallback and tri-layer relational/vector/graph persistent memory in ~1.4 GiB RAM.

All built with 0 external npm dependencies (100% Node.js standard library: node:crypto, node:sqlite, node:fs, node:perf_hooks).

Security boundary

🏛️ System Topology

flowchart TB
    subgraph Clients["AI Clients & Developer Interfaces"]
        CLI["Hetzer CLI\n(hetzer up / creds / mcp)"]
        TUI["Terminal Live Monitor\n(hetzer tui)"]
        Claude["Claude Desktop / Code"]
        Cursor["Cursor IDE"]
        Hermes["Hermes Agent"]
        AGY["Google Antigravity (AGY)"]
        OpenCode["OpenCode / CommandCode"]
        GitCommit["Git Commit Guard Hook\n(.git/hooks/pre-commit)"]
    end

    subgraph HostPlane["Hetzer Command Plane (Host Process)"]
        SecretSniffer["Secret Scanner\n(Regex Rules + Entropy Detector)"]
        GrimoireVault[("Grimoire Vault\nSQLite WAL + AES-256-GCM\ndata/hetzer-vault.db")]
        MCPBridge["Universal MCP Bridge\n(stdio & JSON-RPC Protocol)"]
        ModuleResolver["Module & Profile Resolver\n(Docker Compose Merger)"]
        HealthVerifier["Active Healthcheck & Probe Engine"]
    end

    subgraph DockerPlane["Docker Isolated Network (127.0.0.1 Loopback)"]
        subgraph NineRouter["9Router AI Gateway (:20140)"]
            RouterProxy["Multi-Provider Model Router & Fallback"]
        end

        subgraph CogneeSvc["Cognee Memory Engine (:8001)"]
            MCPEndpoint["MCP Server (:8001/mcp)"]
            RelationalDB[("SQLite WAL\nRelational Metadata")]
            VectorDB[("LanceDB\nVector Embeddings")]
            GraphDB[("Kùzu Graph DB\nKnowledge Graph")]
        end
    end

    CLI --> GrimoireVault
    CLI --> ModuleResolver
    CLI --> MCPBridge
    GitCommit --> SecretSniffer
    TUI --> HealthVerifier
    Claude -.->|"stdio MCP"| MCPBridge
    Cursor -.->|"stdio MCP"| MCPBridge
    Hermes -.->|"stdio MCP"| MCPBridge
    AGY -.->|"Native Skill"| GrimoireVault
    OpenCode -.->|"Native Skill"| GrimoireVault

    ModuleResolver -->|"docker compose up\n(Ephemeral Credential Injection)"| DockerPlane
    MCPBridge -->|"Direct Probe & Call"| MCPEndpoint

Credential defense layers

┌─────────────────────────────────────────────────────────────────────────────┐
│                     HETZER SEVEN-LAYER DEFENSE MATRIX                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 1: Explicit Secret Scanner                                            │
│  ► Scans input passed to CLI/MCP scanner, staged Git diffs & commit messages. │
│  ► Redaction reports whether each detected value was successfully vaulted.  │
│  ► Agent prompts outside integrated paths are not intercepted.               │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 2: Real-Time Stream Sanitizer & Ephemeral Scoping (hetzer exec)      │
│  ► Intercepts child process stdout/stderr in memory before terminal emit.   │
│  ► Known injected values are redacted even when split across output chunks. │
│  ► Terminal controls and supported long structured values are filtered.     │
│  ► --strict starts with a minimal environment and injects approved refs.     │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 3: Anti-Reflection Execution Guard                                   │
│  ► Blocks reflection commands ('printenv', 'env', 'export', 'docker inspect'│
│    and inline 'os.environ' scripts) before process spawning.                │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 4: TTY and Process Ancestry Safeguards                               │
│  ► Validates process.stdin.isTTY and sniffs autonomous agent env flags.     │
│  ► Traverses 5 generations of parent processes (PPID) to block autonomous   │
│    recognized agent processes before allowing 'hetzer creds reveal'.         │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 5: Native OS Confirmation                                              │
│  ► Launches native OS modal dialogs (Windows Forms / AppleScript / Zenity). │
│  ► Every plaintext reveal requires a native modal confirmation.              │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 6: Dynamic Canary Honey-Tokens & Active Stream Tripwires             │
│  ► Deploys enticing decoy canary tokens ('HETZER_CANARY_TOKEN') into .env.  │
│  ► Guarded resolution/reveal attempts abort with exit code 43 and log alert.│
│  ► 'hetzer exec --canary' monitors child streams; any detected canary leak   │
│    instantly terminates child process tree (taskkill / SIGKILL) & aborts.   │
├─────────────────────────────────────────────────────────────────────────────┤
│  Layer 7: Master Key Workspace Isolation (~/.hetzer/grimoire.key)           │
│  ► 'hetzer creds isolate-key' relocates master key out of project directory │
│    with 0600 POSIX permissions. Same-user processes may still read it.       │
└─────────────────────────────────────────────────────────────────────────────┘

Performance measurement

Scanner latency varies with input length, candidate count, CPU, Node version, and cold-start effects. The Git hook also starts Git subprocesses, so scanner microbenchmarks must not be presented as end-to-end hook latency. Run node benchmarks/vault-bench.mjs and measure hetzer hook check on the target repository before setting a performance objective.

🏦 Enterprise & Banking Readiness (PCI-DSS, SOC 2, ISO 27001, OJK)

Hetzer can contribute technical evidence to a broader security program, but this repository has not been independently audited or certified against the frameworks below.

🎯 Strategic Enterprise Role: The "Agent Sidecar Armor"

Banks deploying AI coding agents (Claude Code, Cursor, Copilot, Antigravity) face an acute compliance threat: engineers accidentally leaking core-banking API keys, staging database URLs, or customer PII into third-party LLM context windows.

Hetzer acts as a client-side Defense-in-Depth Armor:

• 0 runtime npm dependencies reduces one source of dependency risk. Node.js, Hetzer itself, container images, and installers remain in the supply chain.
• Explicit scanning and guarded execution reduce exposure in the paths that invoke them.
• Git Pre-Commit Guard blocks supported patterns and .env filenames when the hook runs.
• AES-256-GCM encryption protects vault values at rest while the master key remains separate and protected.

📋 Compliance Quick Reference

📖 Read the Complete Technical Whitepaper: For full regulatory analysis, threat vector models, and enterprise deployment blueprints, see Enterprise & Banking Readiness Guide (docs/enterprise-readiness.md).

Universal AI Agent Skills (no Docker required)

Install credential-handling guidance across the supported AI coding agents. The installed files consume disk space and the CLI uses memory when invoked.

# Install to all detected agents on your system:
hetzer skill install

# Or run instantly via npx:
npx hetzer skill install

Supported Platforms:

• Hermes Agent: Installed to ~/.hermes/skills/hetzer/SKILL.md (globalOnly: true) and hooked into ~/.hermes/config.yaml.
• Google Antigravity (AGY): Installed to .agents/skills/hetzer/SKILL.md (workspace), ~/.gemini/config/skills/ (global), and AGENTS.md.
• OpenCode & CommandCode: Installed to .opencode/skills/hetzer/ and .commandcode/skills/hetzer/ with AGENTS.md entry pointers.
• Cursor IDE: Installed to .cursor/rules/hetzer.mdc, .cursor/skills/hetzer/, and .cursorrules.
• Claude Desktop & Code: Configured in claude_desktop_config.json via native stdio MCP and .claude/skills/.
• Cline / Roo Code: Configured in cline_mcp_settings.json and .clinerules.

Check the installation status of all agents on your machine:

hetzer skill status

🔌 MCP Virtual Credential Proxy

Hetzer includes a built-in FastMCP protocol server (cli/mcp/protocol.mjs) compatible with modern (2026-07-28) and legacy (2025-11-25) MCP specifications:

• Zero-Plaintext Tool Payloads: AI agents pass abstract references (e.g. secretRef:openai-api-key) in tool call arguments. The proxy resolves secrets just-in-time in memory before upstream execution.
• Canary Tripwire Guard: Tool calls containing decoy canary references immediately trigger security alerts and abort with exit code 43.
• Response Sanitization: All tool outputs are recursively sanitized through Hetzer's stream redactor before returning to the LLM agent, blocking credential leakage in tool responses.

🛡️ Dual Git Guard Hooks (Pre-Commit & Commit-Msg)

Prevent accidental credential leaks before they ever reach GitHub:

# Install both hooks to .git/hooks/ (pre-commit and commit-msg)
hetzer hook install

# Check staged diff manually
hetzer hook check

# Validate a commit message manually
hetzer hook check-msg .git/COMMIT_EDITMSG

# Uninstall both hooks if no longer needed
hetzer hook uninstall

When installed, Hetzer provides dual-phase protection:

1. Pre-Commit Guard: Inspects staged files and diff additions for supported credential patterns and .env files. Test fixtures (*.test.*, test/, fixtures/) and agent call IDs are safely exempted.
2. Commit-Msg Guard: Verifies commit message text (COMMIT_EDITMSG), blocking commits that accidentally embed tokens, passwords, or API keys in the commit summary or description.

Example of a blocked commit:

================================================================================
  🛑 HETZER ARMOR: GIT COMMIT BLOCKED (TOKEN LEAK DETECTED!)
================================================================================
  Scan Latency : 183.00 ms
  Violations   : Detected 1 raw credential in staged changes:

  * src/config.js:14 -> [OPENAI_API_KEY] OpenAI secret key

  HOW TO FIX:
  1. Save credential to Vault : hetzer creds set openai-api-key
  2. Replace in your code with: secretRef:openai-api-key
================================================================================

🪤 Canary Honey-Tokens & Active Stream Tripwires

Detect unauthorized credential harvesting and prompt injection attempts targeting AI agents:

# Deploy decoy canary honey-token into .env
hetzer canary setup

# Execute child process with active stream canary monitoring
hetzer exec --canary -- npm test

Tripwire Mechanisms:

• Decoy Honey-Tokens: hetzer canary setup binds HETZER_CANARY_TOKEN=secretRef:canary-token in .env. Attempting to resolve, inspect, or reveal canary credentials (canary-token, canary-*, decoy-*) triggers ERR_CANARY_TRIPWIRE_TRIGGERED (exitCode 43) and records an incident to data/hetzer-incidents.log.
• Subprocess Stream Kill: When running commands with hetzer exec --canary, dynamic decoy tokens (canary_trap_<hex>) are injected into the child environment. Hetzer continuously buffers and scans stdout and stderr streams; if the decoy token leaks into output, Hetzer instantly terminates the entire child process tree (taskkill /PID /T /F on Windows, SIGKILL/SIGTERM on POSIX), halts output forwarding, and aborts with exit code 43.

🛠️ CLI Command Cheat Sheet

All Hetzer commands are executed via the hetzer CLI:

❓ Frequently Asked Questions (FAQ)

1. Can I reveal and inspect credentials stored in the Vault?

Yes, absolutely. As the machine owner and terminal administrator, you have full authority to inspect and decrypt your secrets anytime:

# List all stored credential IDs and status
hetzer creds list

# Decrypt and reveal the actual secret value (AES-256-GCM)
hetzer creds reveal npm-token
hetzer creds reveal nine-router-initial-password

2. Can AI Agents (Claude, Cursor, Cline, GPT) see these credentials?

Hetzer keeps plaintext out of MCP vault-list and vault-existence responses, resolves references just-in-time via its MCP virtual proxy, and hetzer exec injects approved values directly into child processes. This reduces leakage while maintaining operational reality:

• The MCP tools exposed to AI (hetzer_vault_has and hetzer_vault_list) only return metadata and abstract reference strings (secretRef:<id>).
• No reveal tool is exposed by Hetzer's MCP server.
• MCP Virtual Credential Proxy: When an agent invokes an MCP tool, it passes references like secretRef:<id>. Hetzer resolves this just-in-time for upstream execution, checks for honeytokens, and recursively sanitizes outgoing tool responses before context delivery.
• Canary Tripwires: Any attempt by an autonomous agent or injected prompt to access canary credentials (canary-token, canary-*, decoy-*) triggers a critical security incident and aborts with exitCode 43.
• Credentials injected into a child exist in that process environment and memory. hetzer exec blocks common reflection commands, sanitizes supported output, and terminates processes if canary tokens leak (--canary). These are application safeguards rather than full OS sandboxing.
• Agent instructions do not intercept arbitrary prompts, files, debuggers, alternate processes, or tools. Use OS account separation and a centrally managed secret system for hostile-code boundaries.

3. What credential scenarios does Hetzer support?

Grimoire Vault can store arbitrary values up to its configured size limit. Automatic scanning recognizes a narrower set:

• Provider tokens: OpenAI, Anthropic, Google Gemini, npm, GitHub, Slack, AWS access-key IDs, and JWT-shaped strings.
• Service & Database Passwords: 9Router admin passwords, PostgreSQL, Redis, MySQL credentials.
• Private keys: PKCS#8 and algorithm-prefixed PEM private-key blocks up to 16 KiB.
• Database Connection URIs: postgresql://user:pass@host:5432/db, mongodb+srv://..., redis://....
• High-entropy candidates: 24–512 character candidate strings above the entropy threshold. Review false positives and false negatives.

4. Who does Hetzer protect you from?

• Third-party AI vendors: References reduce exposure when users and agents follow the installed guidance and use the integrated scanner paths.
• Accidental Git exposure: Dual Git guards catch supported candidates and staged .env filenames (pre-commit), and block secrets in commit messages (commit-msg) unless hooks are bypassed.
• Other OS accounts: POSIX mode 0600 restricts ordinary cross-account access. Administrators, the same account, backups, and platform-specific ACL behavior remain in scope.

5. How do I achieve maximum security on production servers?

If you prefer not to store HETZER_GRIMOIRE_KEY on disk, omit it from .env and provide it strictly via the in-memory terminal environment:

export HETZER_GRIMOIRE_KEY="your-private-master-key"

Under this model, zero decryption keys exist on disk. Anyone copying the database cannot decrypt its contents without your in-memory master key.

🗑️ Complete Uninstallation & Teardown

To cleanly remove Hetzer from your machine:

# 1. Stop containers and remove persistent volumes (if using Docker services)
hetzer down -v

# 2. Uninstall global CLI binary
npm uninstall -g hetzer

# 3. Clean up project files
cd .. && rm -rf hetzer

🙏 Acknowledgements & Inspirations

Hetzer stands on the shoulders of giants. We express our deepest gratitude and respect to the pioneering tools, architectures, and open-source communities that inspired Hetzer's design:

• 🏛️ HashiCorp Vault (HashiCorp / Mitchell Hashimoto): The gold standard in secret management, transit encryption, and decoupled credential architecture that inspired the Grimoire Vault and secretRef: design.
• ⚡ 1Password CLI (op run) & Doppler: Pioneers of out-of-band ephemeral secret injection into child processes without ever storing secrets in plaintext files.
• 🔍 TruffleHog (Truffle Security) & Gitleaks (Zachary Rice): High-speed regex and Shannon entropy scanners that defined modern Git credential leakage prevention.
• 🌐 Model Context Protocol (MCP) (Anthropic): The open standard that enables autonomous AI clients to seamlessly and safely consume local tools and defense boundaries.
• 🚦 9Router (Decolua): High-performance multi-provider local AI model router, fallback balancer, and reverse proxy.
• 🧠 Cognee (Topoteretes): Advanced tri-layer relational, vector, and knowledge graph persistent memory engine for autonomous agents.
• 🛡️ LLM-Guard (Protect AI): Pioneered real-time LLM input/output scanning and token redaction before context transmission.
• 🤖 Autonomous AI Agent Ecosystems:
  • Hermes Agent (NousResearch)
  • Google Antigravity (AGY)
  • Cursor IDE
  • Cline (Roo Code)
  • OpenCode & CommandCode
    Their work on agentic developer workflows highlighted the need for practical client-side credential safeguards.

📄 License

Distributed under the Apache-2.0 License. See LICENSE and NOTICE for complete legal details.