Kubernetes Parser

Relevant source files

The following files were used as context for generating this wiki page:

• crates/honmoon-core/src/protocols.rs
• wiki/deep-dive/protocol-parsing.md
• crates/honmoon-core/src/lib.rs
• wiki/onboarding/contributor-guide.md
• wiki/deep-dive/architecture.md

The Kubernetes Parser is a protocol-aware component within honmoon-core responsible for inspecting Kubernetes API traffic at the wire level. Its primary purpose is to extract security-relevant facts—such as the Kubernetes verb, the resource being accessed, and the namespace—from HTTP request methods and paths. These extracted facts enable the Honmoon policy engine to enforce fine-grained rules, such as preventing an AI agent from deleting secrets or listing production pods, without requiring full deep packet inspection (DPI) or decryption of the payload.

The parser is implemented as a pure, transport-agnostic function in honmoon-core::protocols. While it is currently engine-complete and extensively unit-tested, it is designed to be fed by a live socket in the proxy layer, which is tracked as a near-term architectural goal (TD-006). By isolating the parsing logic from I/O, the system ensures that Kubernetes request analysis remains highly testable and performant.

Sources: [wiki/deep-dive/protocol-parsing.md:7-14], [crates/honmoon-core/src/protocols.rs:1-8], [wiki/onboarding/contributor-guide.md:2.4]

Architecture and Data Flow

The Kubernetes parser operates within the honmoon-core domain layer. It receives raw HTTP metadata (Method and Path) extracted by the gateway proxy and transforms it into a structured K8sFacts object.

The flow starts with the proxy extracting metadata, which the parser then processes to produce facts for the CEL-based policy engine.
Sources: [wiki/deep-dive/architecture.md:Architecture], [wiki/deep-dive/protocol-parsing.md:At a glance]

Path Parsing Logic

The parser uses a segment-skipping heuristic to handle different Kubernetes API versions and groups. This ensures that version identifiers (like v1) are not mistaken for resource names.

API Prefix Handling

The parser identifies the API style based on the first path segment:

• Core API (/api): Skips the first 2 segments (e.g., /api/v1).
• Grouped API (/apis): Skips the first 3 segments (e.g., /apis/apps/v1).
• Other/Legacy: Skips 0 segments.

Resource and Namespace Extraction

After skipping the versioning segments, the parser evaluates the remaining path:

1. If the first segment is namespaces and at least three segments remain, it extracts the namespace from the second segment and the resource from the third.
2. If the first segment is namespaces but only one or two segments remain, the target resource is namespaces itself.
3. Otherwise, the first remaining segment is treated as a cluster-scoped resource.

Sources: [crates/honmoon-core/src/protocols.rs:111-156], [wiki/deep-dive/protocol-parsing.md:Kubernetes API parser]

Verb Mapping

The parser maps standard HTTP methods to Kubernetes-specific verbs. A critical distinction is made for GET requests: a GET on a collection (no resource name in path) is mapped to list, while a GET on a specific resource is mapped to get.

HTTP Method	Resource Name in Path?	Kubernetes Verb
GET	No	list
GET	Yes	get
POST	N/A	create
PUT	N/A	update
PATCH	N/A	patch
DELETE	N/A	delete

Sources: [crates/honmoon-core/src/protocols.rs:158-176], [wiki/deep-dive/protocol-parsing.md:Method → verb mapping]

Data Structures

The parser outputs a K8sFacts struct, which is defined in the core library and mirrored in the TypeScript control plane.

K8sFacts

Field	Type	Description
verb	String	The mapped Kubernetes action (e.g., delete, list).
resource	String	The targeted resource (e.g., pods, secrets).
namespace	Option<String>	The namespace of the resource, if applicable.

Sources: [crates/honmoon-core/src/lib.rs:105-112], [wiki/deep-dive/architecture.md:The dual policy model]

Implementation Examples

The following table illustrates how the parser handles various Kubernetes API path shapes:

Request Path	Extracted Resource	Extracted Namespace	Mapped Verb (DELETE)
/api/v1/namespaces/prod/secrets/db	secrets	prod	delete
/apis/apps/v1/deployments/api	deployments	None	delete
/api/v1/nodes	nodes	None	list (if GET)
/api/v1/namespaces	namespaces	None	list (if GET)

Sources: [crates/honmoon-core/src/protocols.rs:239-311], [wiki/deep-dive/protocol-parsing.md:Path shapes handled]

Parser Logic Sequence

The following diagram details the internal logical steps taken by parse_k8s_request:

Summary

The Kubernetes Parser provides the necessary wire-level visibility to protect cluster infrastructure from autonomous AI agents. By accurately extracting namespaces and resources while correctly mapping HTTP methods to Kubernetes verbs, it enables secure, fine-grained policy enforcement. Its transport-agnostic design ensures that it remains a high-performance, testable core component of the Honmoon security architecture.

Sources: [wiki/deep-dive/architecture.md:Architecture], [wiki/onboarding/contributor-guide.md:2.2]