Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Honmoon is a policy-based firewall gateway designed to secure the boundary between AI agents and production systems. It operates by intercepting an agent's outbound network traffic and applying declarative policies—resulting in allow, deny, or pause (human approval) verdicts—before the traffic reaches its destination. The system unifies egress domain filtering with a protocol-aware policy engine capable of parsing SQL, Kubernetes, and HTTP at the wire level.
The project is structured as a polyglot monorepo, strictly separating responsibilities between a performance-critical Data Plane written in Rust and a Control Plane and Dashboard implemented in TypeScript using the Bun runtime.
Sources: README.md:1-17, wiki/deep-dive/architecture.md:11-16
Dual-Plane Architecture
Honmoon enforces a hard architectural boundary between its data and control planes. This separation ensures that security-critical wire handling is performed in a memory-safe, high-performance environment, while management and observability tools benefit from the agility of the TypeScript ecosystem.
Component Map
| Plane | Module | Technology | Responsibility |
|---|---|---|---|
| Data Plane | honmoon-core | Rust | Policy model, CEL engine, protocol parsers, audit logging. |
| Data Plane | honmoon-proxy | Rust | CONNECT egress proxy, approval hold registry. |
| Data Plane | honmoon-mgmt | Rust | Axum-based Management API, embedded Dashboard assets. |
| Control Plane | @honmoon/policy | TypeScript | Policy types, JSON Schema, runtime decision model. |
| Control Plane | @honmoon/api | TypeScript | Durable audit-query service (JSONL). |
| UI | @honmoon/dashboard | React | SPA for overview, audit logs, and approvals. |
Sources: wiki/deep-dive/architecture.md:20-30, README.md:50-65
Dependency Layers
The system follows a strict downward-only dependency flow. A critical architectural invariant is that honmoon-core is entirely transport-agnostic, containing no networking or tokio dependencies.
The transport-agnostic nature of the core allows the policy engine to be unit-tested with zero I/O.
Sources: ARCHITECTURE.md:26-49, wiki/deep-dive/architecture.md:38-55
Request Lifecycle
The lifecycle of a request involves three distinct crates within the data plane. The proxy manages the physical socket, the parsers in the core extract protocol facts, and the engine determines the final verdict.
Policy Model and Decision Engine
Honmoon utilizes a dual policy model, where the same structure is defined in both Rust and TypeScript. They are kept in sync manually, with JSON Schema serving as the future single source of truth.
Decision Precedence
The decide() function in honmoon-core follows a specific order of operations:
- Protocol Rules: Evaluated in order. Rules use CEL (Common Expression Language) for conditions. The first match wins.
- Egress Lists: If no rules match, it checks domain
denylists, thenallowlists. - Default: If no match is found, it falls back to the
egress.defaultverdict.
Fail-Closed Invariant
The system is designed to fail closed. The default verdict for the egress block is deny. Any error in CEL evaluation or protocol parsing results in a "no-match," ensuring that failures do not lead to unintended access.
Sources: wiki/onboarding/staff-engineer-guide.md:38-53, wiki/deep-dive/architecture.md:103-115
Protocol-Aware Parsing
The "moat" of Honmoon's architecture is its ability to extract facts from wire-level protocols without decryption.
| Parser | Input | Extracted Facts |
|---|---|---|
| SQL | PostgreSQL 'Q' packets / Text | Verb (DROP, SELECT), Table Name. |
| Kubernetes | HTTP Method + Path | Verb (list, delete), Resource, Namespace. |
| HTTP | CONNECT headers | Host/Domain. |
Architectural Invariants
The following principles are non-negotiable and enforced throughout the codebase:
- Data plane stays open source: All traffic-inspecting components in
crates/must remain Apache-2.0 to ensure auditability and trust. - Transport-agnostic core:
honmoon-coremust never depend ontokioor networking libraries. - No decryption surprises: The system extracts only declared protocol facts and does not perform deep packet inspection beyond what is required by policy.
- Fail closed: Absence of a matching rule must never result in an
allowverdict.
Sources: ARCHITECTURE.md:82-100, wiki/deep-dive/architecture.md:117-130
Summary
Honmoon's architecture is centered on a transport-agnostic decision seam. By isolating the decision logic from I/O and transport frameworks, the project achieves high testability and framework optionality. The system is designed to scale from a single-node open-source gateway to a managed enterprise fleet, while maintaining a transparent and auditable data plane.