HTTP Protocol Facts
Relevant source files
The following files were used as context for generating this wiki page:
HTTP Protocol Facts represent the structured metadata extracted from raw network traffic by Honmoon's data plane. These facts serve as the primary input for the policy engine, allowing for fine-grained control over AI agent interactions with external web services and APIs. By parsing HTTP attributes such as host, method, and path, Honmoon can apply complex Common Expression Language (CEL) conditions to determine whether a request should be allowed, denied, or paused for human approval.
In the current architecture, HTTP facts are extracted during the request lifecycle—specifically during the CONNECT proxy handshake or via wire-level parsing—to populate the domain model used for security decisions.
Architecture and Data Flow
The extraction of HTTP facts occurs at the boundary between the network transport and the policy engine. The honmoon-proxy crate handles the raw socket communication and passes extracted attributes to honmoon-core for evaluation.
The HttpFacts Data Structure
The HttpFacts struct is the container for all HTTP-specific metadata extracted from a request. It is a member of the broader Facts struct, which may also contain SQL or Kubernetes facts depending on the protocol detected.
| Field | Type | Description |
|---|---|---|
host | String | The target hostname (e.g., api.github.com) |
method | Option<String> | The HTTP verb used (e.g., GET, POST) |
path | Option<String> | The request URI path |
body_size | Option<u64> | The size of the request body in bytes |
Sources: crates/honmoon-core/src/lib.rs:88-93, wiki/deep-dive/architecture.md: کلاس دیاگرام
Protocol Fact Extraction
Honmoon utilizes different extraction strategies depending on the proxy mode and the level of traffic inspection enabled.
CONNECT Tunnel Extraction
In Phase 1, when utilizing the CONNECT proxy, the gateway primarily extracts the host and domain from the CONNECT request header. Because CONNECT creates a transparent tunnel, deep inspection of methods and paths is currently limited unless TLS termination is applied.
// Simplified extraction in the gateway
let host = request.uri().host().unwrap_or_default().to_string();
let facts = Facts {
domain: Some(host.clone()),
http: Some(HttpFacts {
host,
method: None,
path: None,
body_size: None,
}),
..Default::default()
};
Sources: crates/honmoon-proxy/src/gateway.rs:81-92, wiki/deep-dive/architecture.md:3-8
Kubernetes HTTP Parsing
While standard HTTP path parsing is straightforward, Honmoon includes specialized logic for Kubernetes API requests within its protocol parsers. The parse_k8s_request function maps HTTP methods to Kubernetes-specific verbs, illustrating how HTTP facts are transformed into domain-specific facts.
| HTTP Method | Resource Name Present? | Resulting K8s Verb |
|---|---|---|
GET | No | list |
GET | Yes | get |
POST | — | create |
PUT | — | update |
DELETE | — | delete |
Sources: crates/honmoon-core/src/protocols.rs:158-176, wiki/deep-dive/protocol-parsing.md:3-8
Integration with Policy Engine
Once HttpFacts are populated, they are injected into the CEL evaluation context. This allows policy authors to write rules targeting specific HTTP behaviors.
Example CEL Conditions
HTTP facts are accessible in CEL via the http namespace:
- Domain Filtering:
http.host.endsWith('.internal.company.com') - Method Restriction:
http.method == 'DELETE' && http.host == 'production-api.com' - Size Limits:
http.body_size > 10485760(blocks requests over 10MB)
Sources: wiki/onboarding/contributor-guide.md: CEL section, crates/honmoon-core/src/engine.rs:73-89
Current Limitations
As documented in the project roadmap and tech debt tracker, HTTP fact extraction faces specific implementation caveats:
- TLS Termination: Body inspection and detailed path/method extraction for HTTPS traffic require TLS termination, which is planned for Phase 2 (TD-004).
- CONNECT Limitations: Over a standard Phase 1 CONNECT tunnel, the gateway only sees the initial
host, meaning path-based rules for encrypted traffic do not yet fire.
Sources: wiki/deep-dive/roadmap-open-core.md: Tech Debt Table, ARCHITECTURE.md:123-131
In summary, HTTP Protocol Facts provide the necessary context for Honmoon to secure the network boundary. By transforming raw HTTP attributes into structured facts, the system enables declarative, protocol-aware security policies that go beyond simple IP or domain blocking.