Expand description
§ash-log
Security audit logging for Rust applications.
Provides structured audit logging for security events including authentication, authorization, method invocations, and policy violations.
For logs that must resist deliberate modification, enable the hmac-chain
feature and use HmacChainIntegrity. The default ChecksumIntegrity uses
an unkeyed hash and detects only accidental corruption.
Features: append-only logs, integrity verification, pluggable backends.
§Quick start
use ash_log::*;
use std::sync::Arc;
let backend = Arc::new(StdoutAuditBackend);
let integrity = SequenceIntegrity::new();
let mut event = AuditEvent::builder()
.event_type(AuditEventType::AuthenticationAttempt)
.principal("alice@example.com")
.result(AuditResult::Success)
.build();
integrity.add_integrity(&mut event);
backend.log_audit(&event);Modules§
- ocsf
- OCSF (Open Cybersecurity Schema Framework) 1.8.0 support for ash-log.
Macros§
- ash_
audit - Emit a security event — the tier that is never filtered.
- ash_
debug - Emit a
Debugdiagnostic. - ash_
diagnostic - Emit a diagnostic record at an explicit severity.
- ash_
error - Emit an
Errordiagnostic. - ash_
info - Emit an
Infodiagnostic. - ash_
logger - Build a
Loggerfrom named parts. - ash_
trace - Emit a
Tracediagnostic. - ash_
warn - Emit a
Warningdiagnostic.
Structs§
- AshLog
Layer - A
tracing_subscriberlayer that writes every event it sees to aLoggeras a diagnostic record. - Async
Backend - Writes events on a dedicated thread.
- Async
Backend Builder - Builder for
AsyncBackend. - Audit
Event - A security audit event representing a significant action or decision
- Audit
Event Builder - Builder for creating audit events
- Buffered
Audit Backend - Buffers events in memory, writing them to an inner backend only when the
buffer fills or
flushis called. - Checksum
Integrity - Adds checksum of event fields to detect tampering
- Combined
Integrity - Combines multiple integrity mechanisms
- Counting
Error Sink - Counts failures and lost events without storing them.
- Directive
- One
module=levelrule. - Event
Clock - An
HlcTimestampas it is stored on an event. - File
Backend - Appends audit events to a file as JSON lines.
- File
Backend Builder - Builder for
FileBackend. - Filter
Directives - A parsed set of per-module thresholds.
- FnError
Sink - Calls a closure for each failure.
- FnRedactor
- Redacts whatever a closure objects to.
- HlcClock
- A thread-safe Hybrid Logical Clock.
- HlcTimestamp
- A Hybrid Logical Clock timestamp.
- Hmac
Chain Integrity - Tamper-evident integrity using a keyed HMAC-SHA256 hash chain.
- Ignore
Errors - Discards failures. The default, preserving the behaviour of backends that predate this trait.
- KeyRedactor
- Redacts values whose key matches a denylist, case-insensitively.
- Live
Filter - A filter that can be replaced while the logger is running.
- Logger
- Writes audit events, applying a two-tier admission policy before any integrity metadata is attached.
- Logger
Builder - Builder for
Logger. - Multi
Audit Backend - Writes audit events to multiple backends simultaneously
- NoIntegrity
- No integrity checking
- NoRedaction
- Redacts nothing. The default, so redaction is opt-in.
- Noop
Audit Backend - Discards all audit events (testing only)
- Parse
Severity Error - Returned when a string does not name an
AuditSeverity. - Provenance
- Where an event was emitted from.
- Rotation
Policy - When to start a new file.
- Scope
- Builds a set of scope fields.
- Scope
Fields - Fields bound by a scope, and whatever its parent bound.
- Scope
Guard - Restores the previous scope when dropped.
- Sequence
Integrity - Adds monotonically increasing sequence numbers to detect gaps or duplicates
- Stderr
Audit Backend - Writes audit events to stderr as JSON lines
- Stderr
Error Sink - Writes failures to stderr.
- Stdout
Audit Backend - Writes audit events to stdout as JSON lines
- Write
Error - A write that did not reach its destination.
Enums§
- Audit
Event Type - Types of recorded events.
- Audit
Result - Result of an audited action
- Audit
Severity - Severity level of an audit event, ordered from least to most severe.
- Chain
Error - Why a chain failed to verify.
- HlcError
- Errors that can be returned by
HlcClockoperations. - Overflow
Policy - What to do when the queue is full.
- Rotation
Error - Why a key rotation was refused.
Constants§
- CHAIN_
INDEX_ FIELD - Metadata key holding the event’s position in the chain.
- KEY_
ID_ FIELD - Metadata field naming the key an entry was signed with.
- MAC_
FIELD - Metadata key holding the chained HMAC of an event.
- REDACTED
- What replaces a redacted value.
- WRITER_
FIELD - Metadata field naming the writer that produced an entry.
Traits§
- Audit
Backend - Audit log backend trait. Synchronous writes ensure events persist before execution continues.
- Audit
Integrity - Audit integrity verification trait
- Error
Sink - Receives write failures reported by a backend.
- Redactor
- Decides which fields are secret.
Functions§
- log_
auth_ event - Log authentication/authorization events.
- log_
security_ violation - Log security policy violations (rate limits, banned IPs, etc.).