audit

Module: audit

Contents

Modules

• builder - Audit event builder.
• sink - Concrete audit sink implementations.

Structs

• AuditPayload - Lightweight audit payload sent from the pipeline hot path through the channel.
• ExecutionEvent - Domain-level audit event produced by the enforcement pipeline.

Enums

• AuditSinkError - An error that can occur on an [AuditSink].

Traits

• AuditSink - An audit sink that consumes signed [ExecutionEvent]s and writes

---

firma_sidecar::audit::AuditPayload

Struct

Lightweight audit payload sent from the pipeline hot path through the channel.

Contains only the fields extracted from the enforcement decision — no signing, no UUID generation. The EventBuilder on the sink side converts this into a fully populated, signed [ExecutionEvent].

Fields:

• session_id: String - Session that produced this event.
• token_id: String - Capability token ID evaluated during enforcement.
• agent_id: String - Agent that initiated the action.
• action: String - Canonical action class from the normalizer (e.g., llm.inference).
• resource: String - Target resource identifier (e.g., URL, table name).
• decision: i32 - Enforcement outcome (proto wire value: 1 = ALLOW, 2 = DENY).
• deny_reason: String - Human-readable reason when decision is DENY or ABORT. Empty on
• enforcement_latency_us: i64 - Wall-clock time spent in the enforcement pipeline, in
• context_hash: String - Integrity hash of the Cedar context used during evaluation.
• bundle_version: String - Policy bundle version active at decision time.
• dispatch_status: i32 - HTTP status code returned by the connector. Zero when the call
• dispatch_latency_us: i64 - Connector dispatch latency in microseconds. Zero when the call
• response_size: i64 - Target response body size in bytes. Zero when the call never

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Clone
  • fn clone(self: &Self) -> AuditPayload

firma_sidecar::audit::AuditSink

Trait

An audit sink that consumes signed [ExecutionEvent]s and writes them to an external destination.

Each concrete sink (stdout, file, gRPC, WAL) is constructed with only the configuration it needs. The run method drives the sink to completion, draining events from the channel until the cancellation token fires or an unrecoverable error occurs.

Object safety

This trait uses RPITIT (impl Future) and is therefore not object-safe. That is intentional: the concrete sink type is selected once at startup based on the [audit] config section, so dynamic dispatch is unnecessary.

Methods:

• run: Drives the sink, consuming events from rx until exit is

firma_sidecar::audit::AuditSinkError

Enum

An error that can occur on an [AuditSink].

Variants:

• BindFailed(String) - The audit sink failed to bind to the configured address or
• ServerError(String) - An unrecoverable server error occurred while the audit sink was

Traits: Error

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

firma_sidecar::audit::ExecutionEvent

Struct

Domain-level audit event produced by the enforcement pipeline.

Converted into the proto wire type via From<ExecutionEvent>.

Fields:

• event_id: String - Unique event identifier (UUID v7, time-ordered).
• session_id: String - Session that produced this event.
• token_id: String - Capability token ID evaluated during enforcement.
• agent_id: String - Agent that initiated the action.
• action: String - Canonical action class from the normalizer (e.g., http_get).
• resource: String - Target resource identifier (e.g., URL, table name).
• decision: i32 - Enforcement outcome.
• deny_reason: String - Human-readable reason when decision is DENY or ABORT. Empty on
• enforcement_latency_us: i64 - Wall-clock time spent in the enforcement pipeline, in
• context_hash: String - Integrity hash of the Cedar context used during evaluation.
• bundle_version: String - Policy bundle version active at decision time.
• timestamp: Option<u128> - Event timestamp as nanoseconds since the Unix epoch.
• dispatch_status: i32 - HTTP status code returned by the connector. Zero when the call
• dispatch_latency_us: i64 - Connector dispatch latency in microseconds. Zero when the call
• response_size: i64 - Target response body size in bytes. Zero when the call never
• sandbox_id: String - Per-run identity scoping the event to a single firma run
• signature: Vec<u8> - ECDSA signature (DER-encoded) over all preceding fields.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> ExecutionEvent
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &ExecutionEvent) -> bool
• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

Module: builder

Audit event builder.

Constructs and signs [ExecutionEvent]s from [AuditPayload]s. The builder holds the ECDSA signing key, loaded once at startup, and provides a single [EventBuilder::build] method that maps an [AuditPayload] into a fully populated, signed audit event.

The builder lives on the sink side of the audit channel, keeping ECDSA signing off the enforcement hot path.

Module: sink

Concrete audit sink implementations.