Introduction to Honmoon
Relevant source files
The following files were used as context for generating this wiki page:
Honmoon (혼문, 魂門) is a policy-based firewall gateway designed to guard the boundary between AI agents and production systems. It intercepts an agent's outbound network traffic—such as calls to APIs, databases, or Kubernetes clusters—and applies declarative security policies. These policies result in one of three verdicts: allow, deny, or pause (hold for human approval), ensuring that security logic is applied before a request reaches its destination.
Sources: README.md:9-12, wiki/getting-started/overview.md:8-12
The system unifies egress domain filtering (similar to Squid-based approaches) with a protocol-aware policy engine that uses Common Expression Language (CEL) to evaluate fine-grained rules. By parsing protocols like SQL and Kubernetes at the wire level, Honmoon can distinguish between safe operations and destructive ones, such as a DROP TABLE command or unauthorized secret deletion.
Sources: README.md:14-17, wiki/getting-started/overview.md:46-51
Core Architecture and Planes
Honmoon is built as a polyglot monorepo, strictly separating responsibilities between a high-performance data plane and a management-focused control plane.
Sources: wiki/deep-dive/architecture.md:8-10, wiki/getting-started/overview.md:57-60
The Dual-Plane Design
The project enforces a hard architectural boundary between its components:
- Data Plane (Rust): Responsible for wire-level proxying, protocol parsing, and policy evaluation. It is performance-critical and memory-safe.
- Control Plane (TypeScript/Bun): Handles CLI operations, policy validation, and provides the management/audit APIs.
- UI (React): A dashboard for audit logs and approval workflows, which is compiled and embedded into the Rust binary.
The diagram shows the interaction between the data plane, control plane, and the embedded dashboard.
Sources: wiki/deep-dive/architecture.md:54-90, wiki/getting-started/overview.md:62-85
Module Responsibilities
| Module | Language | Primary Responsibility |
|---|---|---|
honmoon-core | Rust | Policy model, CEL engine, protocol parsers, audit logging. |
honmoon-proxy | Rust | CONNECT egress proxy and the approval registry for held requests. |
honmoon-mgmt | Rust | Axum-based API and embedded dashboard hosting. |
@honmoon/policy | TS | JSON Schema, type definitions, and runtime decision models. |
@honmoon/api | TS | Durable query layer for historical audit logs. |
Sources: wiki/deep-dive/architecture.md:14-25, README.md:93-104
Policy and Decision Engine
Honmoon's decision engine is housed in honmoon-core. A critical architectural invariant is that this core remains transport-agnostic, meaning it has no networking or I/O dependencies, allowing for pure unit testing of policy logic.
Sources: wiki/deep-dive/architecture.md:45-48, wiki/onboarding/contributor-guide.md:91-95
Decision Verdicts
Every request processed by the gateway results in a Verdict:
- Allow: The request is permitted and tunneled to the destination.
- Deny: The request is blocked (returning a
403 Forbidden). - Pause: The connection is held for up to 300 seconds, awaiting a human to approve or reject the action via the dashboard.
Sources: wiki/getting-started/overview.md:16-19, wiki/onboarding/product-manager-guide.md:46-48
Fail-Closed Principle
The system is designed to fail closed. The default egress posture is deny. If a rule is broken or a request does not match any specific "allow" criteria, the system defaults to blocking the traffic to ensure maximum security.
Sources: wiki/getting-started/overview.md:20-21, wiki/onboarding/contributor-guide.md:158-164
This sequence illustrates the request lifecycle from interception to final verdict application.
Sources: wiki/deep-dive/architecture.md:51-68, README.md:36-45
Operating Modes
Honmoon supports different deployment patterns depending on the required level of isolation.
Sources: wiki/getting-started/overview.md:98-100, README.md:111-113
| Mode | Command | Description |
|---|---|---|
| Process Wrapper | honmoon run | Wraps a single process, typically using environment variables like https_proxy. |
| Gateway | honmoon gateway | Acts as a standalone central proxy server accepting client connections. |
| Join | honmoon join | (Planned) Routes all host traffic to a central gateway via a tunnel. |
Sources: wiki/getting-started/overview.md:102-109, README.md:115-117
Implementation Status and Roadmap
The project follows an open-core model where the data plane (proxy and parsers) is open source to ensure auditability and trust.
Sources: wiki/deep-dive/roadmap-open-core.md:8-11, wiki/onboarding/executive-guide.md:86-88
Maturity Matrix
- Implemented (Phases 0–4): Egress proxy, CEL engine, SQL/Kubernetes parsers, audit logs, and the React dashboard.
- Planned (Phases 5–7): Hardened network-namespace isolation, live-traffic protocol enforcement (TD-006), and enterprise fleet management.
Sources: wiki/index.md:16-21, wiki/deep-dive/roadmap-open-core.md:13-21
The roadmap status highlights completed core functionality and upcoming isolation features.
Sources: wiki/deep-dive/roadmap-open-core.md:24-34, README.md:209-220
Conclusion
Honmoon provides a necessary security layer for the era of autonomous AI agents by moving beyond simple IP/domain blocking. By integrating deep protocol parsing with a human-in-the-loop approval workflow, it allows organizations to grant agents high levels of autonomy while maintaining strict control over production environments. Its transport-agnostic core and dual-plane architecture ensure the system remains both highly performant and easily manageable.