Policy Authoring & YAML Format

Relevant source files

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

• wiki/getting-started/policy-authoring.md
• policies/agent.yaml
• packages/policy/schema/policy.schema.json
• crates/honmoon-core/src/lib.rs
• crates/honmoon-core/src/engine.rs
• packages/policy/src/index.ts

Honmoon policies define the security posture of the firewall gateway, controlling how AI agents interact with production systems. A policy is a single YAML document that specifies two distinct layers of protection: an egress block for broad domain filtering and a rules list for fine-grained, protocol-aware enforcement using Common Expression Language (CEL).

The policy structure is unified across the project, sharing a common schema represented in Rust for the data plane, TypeScript for the control plane, and a formal JSON Schema for external validation. This design ensures that the same declarative rules are interpreted consistently whether they are being evaluated at the wire level or displayed in the management dashboard.

Sources: wiki/getting-started/policy-authoring.md, README.md:11-17

Policy Structure Overview

A Honmoon policy consists of three primary top-level fields. The version field ensures compatibility, while egress and rules define the logic for request verdicts.

Field	Type	Description
version	integer	The schema version (must be ≥ 1).
egress	object	Configures domain-based allow/deny lists and the default fallback verdict.
rules	array	An ordered list of protocol-aware rules evaluated before egress checks.

Sources: packages/policy/schema/policy.schema.json:7-19, wiki/getting-started/policy-authoring.md

Data Model Relationships

The following diagram illustrates how a Policy document is composed of Egress configurations and a sequence of individual Rules.

Egress Domain Filtering

The egress block provides a coarse-grained mechanism for controlling outbound traffic based on destination domains. It supports exact matches and leading wildcard patterns (e.g., *.github.com).

Matching Logic Precedence

When the gateway evaluates a domain, it follows a strict precedence to ensure a "fail-closed" security posture:

1. Deny List: If the domain matches a pattern in egress.deny, the verdict is immediately deny.
2. Allow List: If the domain matches a pattern in egress.allow, the verdict is allow.
3. Default: If no list matches, the egress.default verdict is returned (which defaults to deny if omitted in the schema).

Wildcard Support

Honmoon supports a single leading *. wildcard. A pattern like *.github.com matches both the root github.com and any subdomain such as api.github.com.
Sources: crates/honmoon-core/src/engine.rs:56-64

Protocol-Aware Rules (CEL)

Rules provide fine-grained control by inspecting protocol-level "Facts" extracted at the wire level (SQL, Kubernetes, or HTTP). Rules are evaluated in the order they appear in the YAML file. The first rule to match both the endpoint and the CEL condition determines the verdict.

Rule Configuration Parameters

Parameter	Purpose	Example
name	Human-readable identifier for audit logging.	sql-no-prod-drop
endpoint	The target system name; * matches all endpoints.	postgres-prod
condition	A CEL expression evaluated against protocol facts.	sql.verb == 'DROP'
verdict	The action to take: allow, deny, or pause.	pause

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

Common Expression Language (CEL) Integration

Honmoon utilizes cel-interpreter to evaluate conditions. Facts are injected as variables into the CEL context. If a condition references a fact that is not present (e.g., sql.verb on an HTTP connection), the condition evaluates to false, ensuring that missing data does not lead to an accidental allow.

Verdict Types

The system supports three primary verdicts that govern request lifecycle:

• allow: The request is permitted and proxied to the destination.
• deny: The request is blocked (returning a 403 Forbidden to the agent).
• pause: The request is held in an approval registry. The gateway waits for a human operator to approve or reject the request via the management dashboard.

Sources: crates/honmoon-core/src/lib.rs:14-23, packages/policy/schema/policy.schema.json:24-27

Example Policy Configuration

The following example demonstrates a production-grade policy combining egress filtering with specific database and Kubernetes safety rules.

# yaml-language-server: $schema=../packages/policy/schema/policy.schema.json
version: 1

egress:
  default: deny
  allow:
    - github.com
    - '*.githubusercontent.com'
    - api.anthropic.com
  deny:
    - '*.internal.corp'

rules:
  - name: k8s-no-secret-delete
    endpoint: k8s-prod
    condition: "k8s.resource == 'secrets' && k8s.verb == 'delete'"
    verdict: deny

  - name: sql-no-prod-drop
    endpoint: postgres-prod
    condition: "sql.verb == 'DROP' || sql.verb == 'TRUNCATE'"
    verdict: pause

  - name: http-block-large-upload
    endpoint: '*'
    condition: "http.method == 'POST' && http.body_size > 10485760"
    verdict: deny

Sources: policies/agent.yaml:1-27

Policy Validation

Developers can validate policies using three distinct methods:

1. JSON Schema: The file policy.schema.json provides structural validation and IDE support via the yaml-language-server modeline.
2. Rust Loader: The Policy::from_yaml function in honmoon-core provides strict deserialization used by the data plane.
3. TypeScript CLI: The @honmoon/cli package includes a validate command (currently a stub) intended for CI/CD linting.

Sources: packages/policy/schema/policy.schema.json, crates/honmoon-core/src/lib.rs:121-126, wiki/getting-started/policy-authoring.md

Policy Authoring in Honmoon provides a multi-layered defense strategy. By combining simple domain allowlists with deep protocol inspection through CEL, Honmoon ensures that AI agents operate within safe, human-defined boundaries while providing a robust "fail-closed" mechanism for unhandled scenarios.