Wire-level Protocol Parsing
Relevant source files
The following files were used as context for generating this wiki page:
Protocol-aware parsing is a core architectural pillar of Honmoon, enabling the system to go beyond simple domain-level egress filtering. It allows the policy engine to inspect specific actions within a protocol—such as SQL commands or Kubernetes API requests—and apply fine-grained rules based on the actual intent of the traffic. This capability serves as the project's "moat," distinguishing it from commodity firewalls.
The parsing logic is implemented as a set of pure functions within the honmoon-core crate. This design ensures that parsing is transport-agnostic, meaning it does not depend on networking libraries or active sockets, allowing for extensive unit testing and easy embedding into various components of the data plane.
Sources: wiki/deep-dive/protocol-parsing.md, ARCHITECTURE.md:47-48
Architectural Design and Invariants
The protocol parsing system is built around several key invariants designed to ensure security, privacy, and performance.
- Transport-Agnostic Core: The parsers live in
honmoon-coreand have no dependencies ontokioor networking infrastructure. They operate purely on byte buffers or strings provided by the proxy layer. - No Decryption Surprises: The system only extracts the specific "facts" needed for policy evaluation (e.g., SQL verbs, Kubernetes resources). It does not perform full Deep Packet Inspection (DPI) or buffer entire payloads unless explicitly required by a rule.
- Fail-Closed Parsing: If a packet is malformed or cannot be parsed correctly, the parser returns
None. The policy engine treats this as a non-match for protocol rules, causing the request to fall back to the default egress policy (which defaults toDeny).
Sources: crates/honmoon-core/src/protocols.rs:1-8, ARCHITECTURE.md:91-100, wiki/deep-dive/protocol-parsing.md
Data Flow Overview
The following diagram illustrates how raw wire bytes are transformed into actionable facts for the policy engine.
PostgreSQL and SQL Parsing
Honmoon implements a two-stage approach for SQL inspection. First, it identifies the specific wire-level protocol frame; second, it applies a heuristic-based parser to the extracted SQL text.
PostgreSQL Wire Frame Handling
The parse_postgres_query function targets the Simple Query ('Q') message. This message type consists of a single tag byte, a 4-byte length header, and a NUL-terminated SQL string.
SQL Heuristic Analysis
Instead of a full SQL grammar, Honmoon uses a high-performance heuristic in parse_sql to extract the command "verb" and the target "table." This is sufficient for security policies that need to block destructive operations like DROP or DELETE.
| Extraction Strategy | Target Verbs | Logic |
|---|---|---|
| Modifier Skipping | DROP, TRUNCATE | Skips tokens like TABLE, IF EXISTS, ONLY to find the identifier. |
| Anchor Search | INSERT, DELETE, SELECT | Finds the token immediately following INTO or FROM. |
| Direct Follow | UPDATE | Extracts the token immediately following the verb. |
Sources: crates/honmoon-core/src/protocols.rs:41-93, wiki/deep-dive/protocol-parsing.md
Kubernetes API Parsing
The Kubernetes parser (parse_k8s_request) derives facts from the HTTP method and the request path. It is designed to handle the complexity of the Kubernetes API structure, including core APIs, grouped APIs, and namespaced resources.
Path Resolution Logic
The parser must correctly identify the resource and namespace while ignoring version segments (e.g., v1, v1beta1).
- Core APIs (
/api/v1/...): Skips the first 2 segments to reach the resource/namespace logic. - Grouped APIs (
/apis/apps/v1/...): Skips the first 3 segments. - Namespaced Resources: Recognizes the
namespaces/{name}/pattern to isolate the specific namespace.
Sources: crates/honmoon-core/src/protocols.rs:111-156, wiki/deep-dive/protocol-parsing.md
Kubernetes Verb Mapping
The parser maps standard HTTP methods to specific Kubernetes verbs. Notably, it distinguishes between a single resource get and a collection list based on whether a resource name is present in the path.
Fact Data Structures
The outputs of the parsers are encapsulated in specific "Facts" structs defined in the core library. These structs are then injected as variables into the Common Expression Language (CEL) environment for rule evaluation.
| Struct | Fields | Purpose |
|---|---|---|
SqlFacts | verb: String, table: String | Captured from PostgreSQL or raw SQL traffic. |
K8sFacts | verb: String, resource: String, namespace: String | Captured from Kubernetes API traffic. |
Facts | domain, endpoint, http, sql, k8s | The aggregate object passed to the policy engine. |
Sources: crates/honmoon-core/src/lib.rs:72-119, wiki/deep-dive/architecture.md
Implementation Status and Caveats
While the parsers are fully implemented and pass extensive unit tests, their integration into live network traffic is subject to the project's phased roadmap.
- Engine-Complete: The parsers successfully generate facts that the
decide()function uses to reach verdicts in test environments. - TD-006 (Live Relay): As of the current phase, the parsers are not yet connected to a live TCP relay or inline proxy. Wiring these to per-endpoint listeners is a high-priority roadmap item.
- TLS Limitation: For HTTPS/Kubernetes traffic over a standard CONNECT tunnel, only the host (domain) is visible. Full protocol parsing for these requires TLS termination, which is planned for future phases.
Sources: wiki/deep-dive/protocol-parsing.md, wiki/deep-dive/roadmap-open-core.md, ARCHITECTURE.md:123-131
Conclusion
Wire-level protocol parsing provides the intelligence necessary for Honmoon to act as a sophisticated gatekeeper for AI agents. By distilling complex network traffic into simple, normalized facts, it enables developers to author human-readable policies that protect critical infrastructure from unauthorized or destructive actions at the protocol level.