Security Models & Invariants

Relevant source files

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

• ARCHITECTURE.md
• crates/honmoon-core/src/lib.rs
• crates/honmoon-core/src/engine.rs
• wiki/deep-dive/architecture.md
• wiki/getting-started/overview.md
• crates/honmoon-cli/src/hook.rs

Honmoon operates as a policy-based firewall gateway positioned between AI agents and production environments. Its primary mission is to enforce a declarative security boundary, intercepting outbound traffic to apply three distinct verdicts: allow, deny, or pause (human approval). The project unifies traditional egress domain filtering with protocol-aware deep inspection of SQL, Kubernetes, and HTTP traffic.

The security model is built on a foundation of "fail-closed" defaults and architectural invariants designed to maintain trust and auditability. By separating the performance-critical Rust data plane from the TypeScript control plane, Honmoon ensures that security-critical wire handling remains isolated, performant, and open for inspection.

Core Architectural Invariants

Honmoon enforces several non-negotiable architectural invariants to ensure the integrity of the security gateway. These rules prevent common failure modes and ensure the system remains auditable.

Invariant	Description	Rationale
Fail Closed	The default egress verdict is always deny.	Prevents unauthorized access if a rule is missing or broken.
Open Data Plane	Components inspecting traffic (crates/*) must be OSS (Apache-2.0).	Security teams must be able to audit the code that sees their data.
Transport Agnostic Core	honmoon-core contains no I/O, networking, or tokio dependencies.	Allows the policy engine to be unit-tested hermetically and embedded anywhere.
No Decryption Surprises	Extract only declared protocol Facts at the wire level.	Prevents silent Deep Packet Inspection (DPI) beyond what policy defines.
Dual Model Sync	Rust and TypeScript models must be manually kept in sync.	Ensures consistent policy evaluation across the data and control planes.

Sources: ARCHITECTURE.md:82-100, wiki/deep-dive/architecture.md:123-145

Transport-Agnostic Policy Engine

A critical invariant is the isolation of honmoon-core. It is strictly pure logic, receiving Facts and returning a Verdict without any knowledge of the underlying transport mechanism.

The Policy Decision Model

The security model relies on a hierarchical evaluation of facts against a loaded policy. Decisions follow a specific precedence to ensure safety.

Verdict Precedence

When the engine evaluates a request, it follows this logic:

1. Rule Evaluation: Check fine-grained CEL rules (SQL, K8s, HTTP) in order.
2. Egress Matching: If no rules match, check the domain against the deny list.
3. Allow List: Check the domain against the allow list.
4. Default Posture: If no match is found, fall back to the egress.default verdict.

Fail-Closed Implementation

The Verdict enum and Egress struct are designed so that the absence of a configuration results in a Deny.

// crates/honmoon-core/src/lib.rs:15-25
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
pub enum Verdict {
    #[default]
    Deny,
    Allow,
    Pause,
}

// crates/honmoon-core/src/lib.rs:48-60
impl Default for Egress {
    fn default() -> Self {
        Self {
            default: Verdict::Deny, // Hardcoded fail-closed
            allow: Vec::new(),
            deny: Vec::new(),
        }
    }
}

Sources: crates/honmoon-core/src/lib.rs:15-60, crates/honmoon-core/src/engine.rs:19-28

Protocol-Aware Security (The Moat)

Honmoon's security model extends beyond simple IP/Domain blocking. It parses wire-level protocols to extract specific "Facts" that drive the Common Expression Language (CEL) engine.

Fact Extraction & CEL Evaluation

The system extracts specific attributes from the traffic stream without full payload decryption. This allows for granular security policies such as "Allow SELECT but Pause DROP".

Protocol	Extracted Facts	Example Policy Condition
SQL	Verb, Table	sql.verb == 'DROP' || sql.verb == 'TRUNCATE'
K8s	Verb, Resource, Namespace	k8s.resource == 'secrets' && k8s.verb == 'delete'
HTTP	Method, Path, Body Size	http.method == 'POST' && http.body_size > 10485760

Sources: wiki/getting-started/overview.md:55-65, crates/honmoon-core/src/lib.rs:90-115

Secure Communication & Hooks

The honmoon-cli includes a hook module designed for integration with AI tools like Claude Code. This provides a secure transport for PII and secret redaction.

Salted HMAC Security Model

To prevent unauthorized use of the redaction hooks, Honmoon utilizes a salted HMAC-SHA256 signature process. This ensures that only authorized entities can trigger redaction or tokenization of sensitive strings.

• Key Material: A signature is generated using a combination of a secret key and a salt.
• Verification: The verify_signature function in hook.rs ensures that incoming requests match the expected HMAC.

// crates/honmoon-cli/src/hook.rs:105-115
pub fn verify_signature(key: &[u8], salt: &[u8], expected: &str) -> bool {
    let mut mac = HmacSha256::new_from_slice(key).expect("HMAC can take key of any size");
    mac.update(salt);
    let result = mac.finalize().into_bytes();
    hex::encode(result) == expected
}

Sources: crates/honmoon-cli/src/hook.rs:100-120, ARCHITECTURE.md:148-155

Operating Mode Security Boundaries

Honmoon provides different levels of isolation depending on the operating mode.

1. Process Wrapper (run): Currently uses environment-variable isolation (https_proxy). This is considered advisory and not yet fully enforcing, as a malicious or broken process could ignore the proxy settings.
2. Gateway (gateway): Acts as a central terminating proxy. This is the most secure current implementation as it forces traffic through the policy engine.
3. Join (join): (Planned) Intended to route all host traffic through a secure tunnel to a gateway.

Sources: wiki/getting-started/overview.md:125-145, ARCHITECTURE.md:120-130

Summary

The Honmoon security model is defined by its fail-closed architecture and transport-agnostic core. By leveraging protocol-aware parsing and CEL-based rules, it provides a more granular security boundary than traditional firewalls. While some isolation features (like Linux netns in run mode) are currently advisory, the core decision logic in honmoon-core provides a robust foundation for guarding AI agent boundaries.