Policy Engine & CEL Evaluator

Relevant source files

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

• crates/honmoon-core/src/engine.rs
• wiki/deep-dive/policy-engine.md
• crates/honmoon-core/src/lib.rs
• ARCHITECTURE.md
• wiki/deep-dive/architecture.md
• wiki/getting-started/policy-authoring.md

The Policy Engine is the central decision-making component of Honmoon. It is responsible for evaluating network requests against a declarative security policy to produce a Verdict: Allow, Deny, or Pause. The engine operates within the honmoon-core crate and is strictly transport-agnostic, meaning it has no dependencies on networking libraries like tokio. It consumes a set of Facts—protocol-level attributes extracted from request traffic—and matches them against configured rules using the Common Expression Language (CEL).

This dual-layered engine combines protocol-aware rules with broader egress domain filtering. By leveraging CEL, the engine provides a portable and safe way to evaluate complex conditions over SQL, Kubernetes, and HTTP facts. The system is designed with a "fail-closed" posture, ensuring that any evaluation errors or unmatched requests default to a Deny verdict.
Sources: ARCHITECTURE.md:47-48, wiki/deep-dive/policy-engine.md, wiki/getting-started/policy-authoring.md

Core Data Model

The Policy Engine relies on several key structures defined in the domain layer. The relationship between these entities determines how a final decision is reached.

Policy Structure

A Policy consists of a schema version, an Egress block for domain filtering, and an ordered list of fine-grained Rule objects.
Sources: crates/honmoon-core/src/lib.rs:25-34, wiki/deep-dive/policy-engine.md

Component	Field	Description
Verdict	Allow, Deny, Pause	The possible outcomes of a policy decision.
Egress	default, allow, deny	Domain-level filtering. deny list always takes precedence over allow.
Rule	name, endpoint, condition, verdict	A protocol-specific rule using a CEL condition.
Facts	domain, http, sql, k8s	Contextual data extracted from the request wire-level traffic.

Sources: crates/honmoon-core/src/lib.rs:14-91, wiki/getting-started/policy-authoring.md

Entity Relationships

The following diagram illustrates the hierarchy of the policy model:

The Policy Engine consumes Policy and Facts to output a Verdict.
Sources: wiki/deep-dive/architecture.md, crates/honmoon-core/src/lib.rs:25-119

Decision Logic & Precedence

The decision engine follows a strict two-stage evaluation process: Rules first, Egress second. This ensures that specific protocol-aware restrictions take precedence over general domain allow/deny lists.

Evaluation Workflow

1. Rule Matching: The engine iterates through the rules list in order. A rule fires if the request endpoint matches (or the rule specifies *) and the CEL condition evaluates to true.
2. Egress Matching: If no rules match, the engine falls back to domain-level filtering.
3. Default: If neither rules nor egress lists match, the Egress::default verdict is returned (which defaults to Deny).

This flowchart shows the prioritized logic used by decide_explained() to reach a verdict.
Sources: crates/honmoon-core/src/engine.rs:19-45, wiki/deep-dive/policy-engine.md

Domain Matching Logic

The matches_domain function handles domain pattern matching. It supports case-insensitive exact matches and single leading wildcards (e.g., *.github.com). A pattern like *.github.com matches both api.github.com and the bare github.com.
Sources: crates/honmoon-core/src/engine.rs:81-89, wiki/getting-started/policy-authoring.md

CEL Evaluation Engine

Rules utilize the Common Expression Language (CEL) via the cel-interpreter crate. This allows developers to write complex logic over protocol facts.

The eval_condition Function

The engine injects protocol facts (http, sql, k8s) as variables into the CEL execution context. Only an explicit Ok(Bool(true)) result from the CEL interpreter counts as a match. Any other result—including compilation errors, runtime errors, or missing fact references—defaults to false.
Sources: crates/honmoon-core/src/engine.rs:66-91, wiki/deep-dive/policy-engine.md

// crates/honmoon-core/src/engine.rs:66-71
fn eval_condition(condition: &str, facts: &Facts) -> bool {
    let mut program = match Program::compile(condition) {
        Ok(p) => p,
        Err(e) => {
            warn!("Failed to compile CEL condition '{}': {}", condition, e);
            return false;
        }
    };
    // ... facts injection logic ...
}

The engine uses a "fail-false" approach during CEL evaluation to maintain the system's "fail-closed" invariant.
Sources: crates/honmoon-core/src/engine.rs:66-71

Variable Context

The following facts are available for use in CEL conditions:

Fact Type	Attributes	Description
HTTP	method, host, path, body_size	Extracted from HTTP/HTTPS traffic.
SQL	verb, table	Parsed from database wire protocols (e.g., PostgreSQL).
K8s	verb, resource, namespace	Extracted from Kubernetes API requests.

Sources: crates/honmoon-core/src/lib.rs:92-119, wiki/getting-started/policy-authoring.md

Invariants and Safety

The Policy Engine is built around several architectural invariants to ensure security and reliability.

• Fail Closed: The system is designed so that failure leads to safety. If a CEL condition fails to compile or refers to a missing fact, it returns false, preventing an accidental Allow. The default egress verdict is always Deny.
• Transport Agnostic: The engine is a pure logic layer. This allows it to be unit-tested hermetically without requiring a network runtime or complex I/O mocking.
• Ordered Evaluation: Rules are evaluated in the order they appear in the YAML policy, allowing for fine-grained overrides (e.g., denying a specific table before allowing general SQL access).

Sources: ARCHITECTURE.md:82-100, wiki/deep-dive/policy-engine.md, crates/honmoon-core/src/engine.rs:16-18

Conclusion

The Policy Engine & CEL Evaluator provide a robust, protocol-aware defense mechanism for AI agents. By separating transport logic from policy decision-making and utilizing a standardized expression language like CEL, Honmoon achieves a high degree of flexibility and security. The fail-closed architecture ensures that even in the face of configuration errors or unparsed traffic, production systems remain protected from unauthorized agent actions.