Skip to content
OpenFirma OpenFirma
Blog

audit

Module: audit

Section titled “Module: audit”

Contents

Section titled “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].
  • Decision - Enforcement outcome as recorded in the audit log.

Traits

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

firma_sidecar::audit::AuditPayload

Section titled “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: Decision - 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.
  • 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
  • From
    • fn from(msg: &RunAuditMessage) -> Self
  • Clone
    • fn clone(self: &Self) -> AuditPayload

firma_sidecar::audit::AuditSink

Section titled “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

Section titled “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

Section titled “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::Decision

Section titled “firma_sidecar::audit::Decision”

Enum

Enforcement outcome as recorded in the audit log.

Serialized as its numeric proto wire value (1 = ALLOW, 2 = DENY, 3 = ABORT, 4 = MODIFY, 5 = STEP_UP, 6 = DEFER), matching the i32 decision field on [AuditPayload] and [ExecutionEvent] and the firma.v1.EnforcementDecision proto enum (AARM R4). This typed view is for consumers that read back the JSON audit records and want to match on the outcome instead of bare ints. PASSTHROUGH is serialized as ALLOW (1) with an empty token_id.

Variants:

  • Allow - Request passed enforcement and was dispatched.
  • Deny - Request was denied before dispatch.
  • Abort - Critical failure aborted the request.
  • Modify - AARM R4 MODIFY: a transformed version of the request was dispatched.
  • StepUp - AARM R4 STEP_UP: the request was blocked pending human approval.
  • Defer - AARM R4 DEFER: the request was blocked and deferred for retry.

Traits: Copy, Eq

Trait Implementations:

  • PartialEq
    • fn eq(self: &Self, other: &Decision) -> bool
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<D>(deserializer: D) -> ::core::result::Result<Self, <D as >::Error>
  • PartialOrd
    • fn partial_cmp(self: &Self, other: &Decision) -> $crate::option::Option<$crate::cmp::Ordering>
  • Ord
    • fn cmp(self: &Self, other: &Decision) -> $crate::cmp::Ordering
  • Clone
    • fn clone(self: &Self) -> Decision
  • Serialize
    • fn serialize<S>(self: &Self, serializer: S) -> ::core::result::Result<<S as >::Ok, <S as >::Error>

firma_sidecar::audit::ExecutionEvent

Section titled “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: Decision - 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
  • PartialEq
    • fn eq(self: &Self, other: &ExecutionEvent) -> bool
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

Module: builder

Section titled “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

Section titled “Module: sink”

Concrete audit sink implementations.