{ "event": "trust_violation", "agent": "reader", "trust_tier": 1, "action": "http_POST", "detail": "T1 agent cannot use POST. Allowed: ['GET', 'HEAD', 'OPTIONS']", "severity": "high", "chain_hash": "92c189e3..." } ``` The request was rejected, the violation was logged, and the hash chain links this entry to every event before and after it. ---

Why Heddle Instead Of...

| | **Heddle** | **Hand-written FastMCP** | **OpenAPI wrapper gen** | **n8n / workflow tools** | |:--:|:--:|:--:|:--:|:--:| | **New tool** | Write YAML, done | Write Python handler per tool | Generate stubs, then customize | Drag nodes, wire connections | | **Security** | Trust tiers, credential broker, input validation, config signing, anomaly detection — all built in | You build it yourself | None | Platform-level auth only | | **Isolation** | Docker sandboxing: `--cap-drop=ALL`, read-only root, pids limit, image digest pinning, watchdog | Process-level only | None | None | | **AI-generatable** | `heddle generate "wrap the Gitea API"` → valid config in 20s | LLM can write code but can't validate it | Not designed for LLM generation | Visual-only, not scriptable | | **Credentials** | `{{secret:key}}` resolved at runtime, never in config | Hardcoded or env vars | Hardcoded or env vars | Platform credential store | | **Audit trail** | Hash-chained, tamper-evident, anomaly-flagged, every call logged | You build it yourself | None | Platform logs only | | **Composability** | Configs become MCP tools, mesh them together | Manual wiring | Separate services | Workflow-scoped | Heddle is for exposing APIs as MCP tools with real runtime controls — not just connectivity. If you only need one tool with no policy layer, hand-written FastMCP is simpler. If you need a visual workflow builder, use n8n. Heddle sits between those worlds: declarative like a workflow tool, programmable like a framework, secure by default. --- ## How It Works

Heddle runtime pipeline

Current Status

**Latest release:** [v0.2.1 — assurance release](https://github.com/goweft/heddle/releases/tag/v0.2.1). After v0.2.0, the codebase went through two independent AI-assisted security reviews plus a manual pass; every finding is closed, with regression tests pinning each one down — 273 tests total. What Heddle can do today, what is partially implemented, and what is still planned: | Layer | Status | Detail | |:-----:|:------:|:-------| | Config → MCP server | **Shipped** | YAML configs become typed MCP tools with HTTP bridging | | Trust tiers (T1–T4) | **Shipped** | Runtime-enforced, violations blocked and logged | | Credential broker | **Shipped** | Per-config secret policy, `{{secret:key}}` resolution | | Audit logging | **Shipped** | Hash-chained JSON Lines, tamper-evident | | Input validation | **Shipped** | Type checking, injection detection, rate limiting | | Access mode annotations | **Shipped** | read/write on tools, T1 write blocked at load + runtime | | Escalation rules | **Shipped** | Conditional hold-for-review on parameter thresholds | | Config signing | **Shipped** | HMAC-SHA256, tamper detection | | Config quarantine | **Shipped** | AI-generated configs staged for review | | AI config generator | **Shipped** | Natural language → validated YAML via local LLM | | Container sandboxing | **Shipped** | Docker-based isolation with hardening flags, image digest pinning, watchdog | | Anomaly detection | **Shipped** | Novel tool calls, rate-limit breaches, repeated credential denials | | Registry integrity | **Shipped** | Per-row HMAC verification, `heddle reg verify` | | Network isolation | **Partial** | `--network=none` baseline shipped; per-host nftables enforcement planned (v0.3) | ## Core Features ### Declarative Tool Configs Define tools in YAML. Heddle validates the config with Pydantic, generates typed MCP tools, and bridges HTTP with `{{param}}` template rendering. Cross-field validation catches bad configs before they run. ### AI Config Generator Describe what you need in plain English. A local LLM generates valid YAML, Heddle validates it against schema rules, retries on failure, and saves the result. ```bash $ heddle generate "agent that wraps the Gitea API" --model qwen3:14b ✓ Generated gitea-api-bridge.yaml (2 tools) in 20.3s ```

Security Architecture

Heddle's security controls map to the OWASP Top 10 for Agentic Applications (2026), NIST AI RMF, and MAESTRO. See the full [threat model](docs/threat-model.md) and [security controls reference](docs/security-controls.md). | Control | What It Does | Framework | |:-------:|:-------------|:---------:| | **Trust tiers** | 4 levels (observer → privileged), runtime-enforced, violations blocked and logged | OWASP ASI03 | | **Credential broker** | Per-config secret access policy, `{{secret:key}}` resolved at runtime, never stored in YAML | OWASP ASI03 | | **Audit log** | Hash-chained JSON Lines, tamper-evident, 5 event types, secret redaction | OWASP ASI10 | | **Input validation** | Type checking, length limits, injection pattern detection (shell, SQL, LLM prompt) | OWASP ASI01 | | **Config signing** | HMAC-SHA256 on all agent configs, tamper detection | OWASP ASI04 | | **Config quarantine** | AI-generated configs staged for review before promotion | OWASP ASI04 | | **Rate limiting** | Sliding window per-config per-tool | OWASP ASI08 | | **Container sandboxing** | Docker isolation: `--cap-drop=ALL`, `--no-new-privileges`, `--read-only`, pids limit, image digest pinning, watchdog timeout | OWASP ASI05 | | **Anomaly detection** | Flags novel tool calls, rate-limit breaches, repeated credential denials via audit observer | OWASP ASI10 | | **Registry integrity** | Per-row HMAC-SHA256 on agent registry, `heddle reg verify` detects tampering | OWASP ASI04 | | **Escalation rules** | Conditional hold-for-review when parameters match thresholds or patterns | OWASP ASI02 | --- ## Starter Packs Ready-made configs for common services. Copy one into `agents/`, update the base URL or credentials, validate, and run. See [packs/](packs/) for full docs. | Pack | Tools | Trust | Description | |:-----|:------|:------|:------------| | [prometheus](packs/prometheus.yaml) | 5 | T1 read-only | PromQL queries, targets, alerts, metric discovery | | [grafana](packs/grafana.yaml) | 5 | T1 read-only | Dashboards, datasources, alert rules | | [git-forge](packs/git-forge.yaml) | 3 | T1 read-only | Repos, issues (Gitea/GitHub/Forgejo) | | [ollama](packs/ollama.yaml) | 4 | T2 worker | Model listing, text generation, VRAM status | | [sonarr](packs/sonarr.yaml) | 6 | T1 read-only | TV library, download queue, search, calendar, history | | [radarr](packs/radarr.yaml) | 6 | T1 read-only | Movie library, download queue, search, calendar, history | ```bash cp packs/prometheus.yaml agents/ heddle validate agents/prometheus.yaml heddle run agents/prometheus.yaml --port 8200 ``` ## Advanced Examples These show Heddle beyond simple API bridging. ### Tool Mesh Multiple configs share a single MCP connection to Claude Desktop. The mesh launcher loads all configs, merges tools, and serves them through one stdio transport. ### VRAM Orchestrator A higher-trust agent that manages GPU memory across Ollama and a local GGUF model library, including smart loading and automatic eviction when VRAM is constrained. ### Daily Ops Orchestrator An orchestration agent that queries Prometheus, a RAG search API, and Ollama in parallel, then synthesizes a daily operations briefing with a local model. ### Web Dashboard A FastAPI + React dashboard for mesh topology, agent status, live audit stream, credential policy, and config signatures. ---

Quick Start

### Clone and install ```bash git clone https://github.com/goweft/heddle.git cd heddle python -m venv venv source venv/bin/activate pip install -e ".[dev]" ``` ### Validate and run a config ```bash heddle validate agents/prometheus-bridge.yaml heddle run agents/prometheus-bridge.yaml --port 8200 ``` ### Generate a new config ```bash heddle generate "agent that wraps the weather API at localhost:5000" ``` ### Run the full mesh ```bash heddle mesh agents/ ``` ### Security operations ```bash heddle audit show -n 20 heddle audit verify heddle sign all agents/ heddle sign verify agents/ heddle secrets policy heddle sandbox agents/my-agent.yaml ``` ### Audit log lifecycle Heddle's audit log at `~/.heddle/audit/audit.jsonl` is a hash-chained JSONL file: every entry includes the SHA-256 of the previous entry, so a single tampered or missing line invalidates the chain from that point on. `heddle audit verify` walks the chain and exits non-zero on the first break. **Policy: rotate-on-break, not tolerate-and-document.** A hash chain is either whole or it is broken; there is no useful middle ground. If `heddle audit verify` reports a break, the chain is sealed and a fresh one is started — the broken file is preserved as raw event data but is no longer the active chain. We do **not** carry a "known break, please ignore" exception forward, because each such exception weakens what `verify` is claiming and forces every consumer (CI, anomaly detection, future auditors) to special-case it. **When you'd rotate:** - `heddle audit verify` reports a break (most commonly from concurrent writers without file locking — fixed for new entries in v0.2.0 via an exclusive file lock in `_write_entry`, but historical breaks pre-dating that release remain). - The active log has grown unwieldy (hundreds of MB) and you want an archive cut at a known-good boundary. - You're cutting a release and want a clean baseline chain for the next development cycle. **Manual rotation procedure** (until `heddle audit rotate` lands; see below): ```bash # 1. Stop the broker so no writer is active systemctl --user stop heddle-dashboard.service # or just kill heddle-mesh / dashboard # 2. Capture a seal record alongside the file cd ~/.heddle/audit SEAL_DATE=$(date -u +%Y-%m-%dT%H-%M-%SZ) sha256sum audit.jsonl > "audit-archive-${SEAL_DATE}.sha256" wc -l audit.jsonl >> "audit-archive-${SEAL_DATE}.sha256" # 3. Move the broken/old chain aside mv audit.jsonl "audit-archive-${SEAL_DATE}.jsonl" # 4. Restart the broker; the next event creates a fresh audit.jsonl systemctl --user start heddle-dashboard.service # 5. Verify the new chain heddle audit verify # should exit clean immediately ``` Archived chains are kept in the same directory (they're still useful as event history) but are not re-verified by `heddle audit verify` — that command only walks the active chain. To inspect a sealed file directly, `jq -c '. | {ts, event, agent}' audit-archive-.jsonl` reads it as plain JSONL. **Existing 2026-03-29 break:** development machines that ran the dashboard plus the test suite concurrently before the file-lock fix landed have a chain break around that date. There is no recovery path for the contiguous chain; rotating per the procedure above is the supported answer. Production-equivalent deployments (single broker writer, file locking present) should not see new breaks. **Tracked follow-up:** `heddle audit rotate` is planned for v0.3. It will (a) atomically rename the active file to a timestamped archive, (b) write a `.sha256` seal alongside, and (c) seed the fresh chain with a `chain_seal_predecessor` event whose payload references the archive's hash so that an external auditor can chain the archives together. Until then, the manual procedure above is the documented path. ### Claude Desktop Integration To expose a unified Heddle mesh to Claude Desktop (and optionally to [CAS](https://github.com/goweft/cas)): ```json { "mcpServers": { "heddle-mesh": { "command": "/path/to/heddle/venv/bin/heddle-mesh" } } } ```

heddle

Installation