Audit Logging
Relevant source files
The following files were used as context for generating this wiki page:
Audit Logging in Honmoon provides a comprehensive record of every decision made by the policy engine regarding network traffic. It captures the facts extracted from a request (such as domain, SQL verbs, or Kubernetes resources) and the resulting verdict—whether a request was allowed, denied, or held for human approval. This system ensures transparency and accountability for AI agent actions at the network boundary.
The system is split into two primary layers: a high-performance in-memory ring buffer for live observation via the management dashboard, and a durable JSONL (JSON Lines) file sink for long-term compliance and historical analysis.
Sources: wiki/deep-dive/architecture.md, ARCHITECTURE.md:50-69
Core Data Model
The audit system is built around the AuditEvent structure and the Decision enumeration. These structures define what data is captured during a request's lifecycle.
Decision Types
Every network request processed by the gateway results in an audit record with one of the following decisions:
| Decision | Description |
|---|---|
allowed | Request met policy criteria and was permitted to pass. |
denied | Request violated policy and was blocked. |
paused | Request triggered a rule requiring human intervention; held in a queue. |
approved | A previously paused request was manually permitted by an operator. |
rejected | A previously paused request was manually blocked by an operator. |
Sources: crates/honmoon-core/src/audit.rs:17-25, packages/policy/src/index.ts:33-40
Audit Event Schema
An AuditEvent contains the following fields:
| Field | Type | Description |
|---|---|---|
id | u64 | Monotonically increasing identifier (resets on restart). |
timestamp | OffsetDateTime | RFC3339 formatted time of the decision. |
decision | Decision | The outcome of the policy evaluation. |
facts | FactsSummary | Extracted wire-level data (domain, SQL, K8s, etc.). |
rule_name | Option<String> | The specific policy rule that triggered the decision. |
Sources: crates/honmoon-core/src/audit.rs:44-52, packages/policy/src/index.ts:70-78
System Architecture
The audit system operates across both the Rust data plane and the TypeScript control plane to provide both live and historical views.
The data plane writes events to two destinations simultaneously: an in-memory ring buffer for the live dashboard and a JSONL file for persistence.
Sources: wiki/deep-dive/control-plane.md, ARCHITECTURE.md:30-49
Implementation Details
In-Memory Ring Buffer (AuditLog)
In honmoon-core, the AuditLog structure manages an in-memory ring buffer. It uses a VecDeque protected by a RwLock to allow concurrent reads and writes from the gateway and management API.
- Capacity: The buffer is bounded to prevent unbounded memory growth.
- ID Generation: The
next_idis an atomic counter that increments with every event. - Access: The
events()method returns a clone of the recent events, newest first.
Sources: crates/honmoon-core/src/audit.rs:107-113, crates/honmoon-core/src/audit.rs:135-143
JSONL Persistence
The honmoon-proxy gateway can be configured with an --audit-log path. When provided, every decision is serialized to JSON and appended to the specified file as a new line. This format is chosen for its simplicity and efficiency in append-only logging.
// In honmoon-proxy/src/gateway.rs
if let Some(ref mut sink) = audit_sink {
let line = serde_json::to_string(&event)?;
sink.write_all(line.as_bytes())?;
sink.write_all(b"\n")?;
}
Sources: crates/honmoon-proxy/src/gateway.rs:34-59, README.md:145-148
Querying Audit Data
The control plane provides a specialized service, @honmoon/api, for querying the persistent audit log. It supports filtering by decision type, time range, and specific facts like domain.
API Endpoints (Durable Layer)
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/audit | GET | limit, decision, since, domain | Returns filtered historical events. |
/api/audit/stats | GET | (none) | Returns event counts grouped by decision. |
Sources: packages/api/src/audit.ts:43-72, wiki/deep-dive/control-plane.md
Management API (Live Layer)
The honmoon-mgmt crate provides endpoints to access the live in-memory buffer:
GET /api/audit: Returns the most recent events from the ring buffer.limit: Optional query parameter to restrict the number of returned events (default 200, max 1000).
Sources: crates/honmoon-mgmt/src/lib.rs:86-93
Request Decision Flow
The following sequence diagram illustrates how an audit event is generated during a standard request lifecycle.
Conclusion
Audit logging in Honmoon is a critical security feature that bridges the gap between autonomous AI actions and human oversight. By providing both a high-speed live view via in-memory buffers and a durable historical record via JSONL files, it enables real-time monitoring through the dashboard and deep forensics through the control plane API. All components are designed with a "fail closed" mentality, ensuring that every request is accounted for.