Skip to main content

ash_log/
backends.rs

1//! Pluggable audit logging backends for writing events to various destinations.
2
3use super::AuditEvent;
4use std::io::Write;
5
6/// Audit log backend trait. Synchronous writes ensure events persist before execution continues.
7pub trait AuditBackend: Send + Sync {
8    /// Write an audit event
9    fn log_audit(&self, event: &AuditEvent);
10
11    /// Write a raw OCSF (or other JSON) security event as a JSON line.
12    ///
13    /// The default implementation is a no-op.  Override this in backends that
14    /// should persist OCSF events.  All built-in backends (`StdoutAuditBackend`,
15    /// `StderrAuditBackend`, `MultiAuditBackend`) provide a real implementation.
16    fn security_log(&self, event: &serde_json::Value) {
17        let _ = event;
18    }
19
20    /// Flush buffered entries
21    fn flush(&self) {
22        // Default: no-op
23    }
24}
25
26/// Writes audit events to stdout as JSON lines
27#[derive(Debug, Clone, Copy, Default)]
28pub struct StdoutAuditBackend;
29
30impl AuditBackend for StdoutAuditBackend {
31    fn log_audit(&self, event: &AuditEvent) {
32        match serde_json::to_string(event) {
33            Ok(json) => {
34                println!("{json}");
35            }
36            Err(e) => {
37                eprintln!("[AUDIT ERROR] Failed to serialize audit event: {e}");
38            }
39        }
40    }
41
42    fn security_log(&self, event: &serde_json::Value) {
43        match serde_json::to_string(event) {
44            Ok(json) => {
45                println!("{json}");
46            }
47            Err(e) => {
48                eprintln!("[AUDIT ERROR] Failed to serialize OCSF event: {e}");
49            }
50        }
51    }
52
53    fn flush(&self) {
54        drop(std::io::stdout().flush());
55    }
56}
57
58/// Writes audit events to stderr as JSON lines
59#[derive(Debug, Clone, Copy, Default)]
60pub struct StderrAuditBackend;
61
62impl AuditBackend for StderrAuditBackend {
63    fn log_audit(&self, event: &AuditEvent) {
64        match serde_json::to_string(event) {
65            Ok(json) => {
66                eprintln!("{json}");
67            }
68            Err(e) => {
69                eprintln!("[AUDIT ERROR] Failed to serialize audit event: {e}");
70            }
71        }
72    }
73
74    fn security_log(&self, event: &serde_json::Value) {
75        match serde_json::to_string(event) {
76            Ok(json) => {
77                eprintln!("{json}");
78            }
79            Err(e) => {
80                eprintln!("[AUDIT ERROR] Failed to serialize OCSF event: {e}");
81            }
82        }
83    }
84
85    fn flush(&self) {
86        drop(std::io::stderr().flush());
87    }
88}
89
90/// Discards all audit events (testing only)
91#[derive(Debug, Clone, Copy, Default)]
92pub struct NoopAuditBackend;
93
94impl AuditBackend for NoopAuditBackend {
95    fn log_audit(&self, _event: &AuditEvent) {
96        // Intentionally discard
97    }
98}
99
100/// Writes audit events to multiple backends simultaneously
101pub struct MultiAuditBackend {
102    backends: Vec<Box<dyn AuditBackend>>,
103}
104
105impl MultiAuditBackend {
106    /// Create a new multi-backend logger
107    #[must_use]
108    pub fn new(backends: Vec<Box<dyn AuditBackend>>) -> Self {
109        Self { backends }
110    }
111
112    /// Create a new multi-backend logger from Arc-wrapped backends
113    #[must_use]
114    pub fn from_arcs(backends: Vec<std::sync::Arc<dyn AuditBackend>>) -> Self {
115        Self {
116            backends: backends
117                .into_iter()
118                .map(|b| -> Box<dyn AuditBackend> { Box::new(b) })
119                .collect(),
120        }
121    }
122
123    /// Add a backend
124    pub fn add_backend(&mut self, backend: Box<dyn AuditBackend>) {
125        self.backends.push(backend);
126    }
127}
128
129impl AuditBackend for MultiAuditBackend {
130    fn log_audit(&self, event: &AuditEvent) {
131        for backend in &self.backends {
132            backend.log_audit(event);
133        }
134    }
135
136    fn security_log(&self, event: &serde_json::Value) {
137        for backend in &self.backends {
138            backend.security_log(event);
139        }
140    }
141
142    fn flush(&self) {
143        for backend in &self.backends {
144            backend.flush();
145        }
146    }
147}
148
149/// One buffered entry, tagged so it replays through the matching backend method.
150enum BufferedEntry {
151    Audit(Box<AuditEvent>),
152    Security(Box<serde_json::Value>),
153}
154
155/// Buffers events in memory, writing them to an inner backend only when the
156/// buffer fills or [`flush`](AuditBackend::flush) is called.
157///
158/// This trades the crate's default durability guarantee for throughput: an
159/// event still buffered when the process dies abruptly is lost. Use it only
160/// where that is acceptable — high-volume telemetry, not the compliance trail.
161/// For the default synchronous behaviour, use the inner backend directly.
162///
163/// Audit and security events share one queue and drain in FIFO order, so
164/// sequence numbers and checksums applied by an
165/// [`AuditIntegrity`](crate::AuditIntegrity) reach the inner backend in
166/// the order they were generated.
167///
168/// # Flush on drop
169///
170/// The [`Drop`] impl flushes, giving the equivalent of Go's `defer sync()`.
171/// Rust runs destructors only on normal scope exit and unwinding, so buffered
172/// events are still lost on [`std::process::exit`], a panic under
173/// `panic = "abort"`, or SIGKILL. Call `flush()` explicitly at shutdown paths
174/// that bypass unwinding.
175///
176/// # Examples
177///
178/// ```rust
179/// use ash_log::*;
180///
181/// let backend = BufferedAuditBackend::new(StdoutAuditBackend, 128);
182///
183/// let event = AuditEvent::builder()
184///     .event_type(AuditEventType::MethodInvocation)
185///     .result(AuditResult::Success)
186///     .build();
187///
188/// backend.log_audit(&event);      // buffered, not yet written
189/// assert_eq!(backend.buffered(), 1);
190///
191/// backend.flush();                // now written to stdout
192/// assert_eq!(backend.buffered(), 0);
193/// ```
194pub struct BufferedAuditBackend<B: AuditBackend> {
195    inner: B,
196    buffer: std::sync::Mutex<Vec<BufferedEntry>>,
197    capacity: usize,
198}
199
200impl<B: AuditBackend> BufferedAuditBackend<B> {
201    /// Create a buffered backend that flushes to `inner` once `capacity`
202    /// events have accumulated.
203    ///
204    /// A `capacity` of 0 is treated as 1, making every write pass straight
205    /// through to the inner backend.
206    #[must_use]
207    pub fn new(inner: B, capacity: usize) -> Self {
208        Self {
209            inner,
210            buffer: std::sync::Mutex::new(Vec::new()),
211            capacity: capacity.max(1),
212        }
213    }
214
215    /// Number of events currently buffered and not yet written.
216    #[must_use]
217    pub fn buffered(&self) -> usize {
218        self.lock().len()
219    }
220
221    /// Flush any pending events and return the inner backend.
222    #[must_use]
223    pub fn into_inner(self) -> B {
224        self.drain_to_inner();
225        // Take `inner` out by value. `Self` implements `Drop`, so it cannot be
226        // destructured; replacing the buffer is unnecessary since the drained
227        // `Vec` is empty and dropping it is a no-op.
228        let mut this = std::mem::ManuallyDrop::new(self);
229        // SAFETY: `this` is never read or dropped again, so moving `inner` out
230        // cannot cause a double free or a read of moved-from memory.
231        let inner = unsafe { std::ptr::read(&raw const this.inner) };
232        // `ManuallyDrop` suppresses every field's destructor, not just
233        // `inner`'s, so drop the buffer explicitly rather than leaking its
234        // allocation. It was drained above, so no events are discarded.
235        // SAFETY: `this.buffer` is valid and initialised here, and is never
236        // accessed again afterwards.
237        unsafe { std::ptr::drop_in_place(&raw mut this.buffer) };
238        inner
239    }
240
241    /// Lock the buffer, recovering the contents if another thread panicked
242    /// while holding the lock. A poisoned buffer still holds valid events, and
243    /// discarding audit records because an unrelated thread panicked would be a
244    /// worse failure than continuing.
245    fn lock(&self) -> std::sync::MutexGuard<'_, Vec<BufferedEntry>> {
246        self.buffer
247            .lock()
248            .unwrap_or_else(std::sync::PoisonError::into_inner)
249    }
250
251    /// Drain buffered events into the inner backend and flush it.
252    ///
253    /// The lock is released before writing so a slow inner backend does not
254    /// block concurrent producers.
255    fn drain_to_inner(&self) {
256        let drained = {
257            let mut buffer = self.lock();
258            if buffer.is_empty() {
259                return;
260            }
261            std::mem::take(&mut *buffer)
262        };
263
264        for entry in drained {
265            match entry {
266                BufferedEntry::Audit(event) => self.inner.log_audit(&event),
267                BufferedEntry::Security(event) => self.inner.security_log(&event),
268            }
269        }
270        self.inner.flush();
271    }
272
273    /// Buffer one entry, draining first if it fills the buffer.
274    fn push(&self, entry: BufferedEntry) {
275        let full = {
276            let mut buffer = self.lock();
277            buffer.push(entry);
278            buffer.len() >= self.capacity
279        };
280
281        if full {
282            self.drain_to_inner();
283        }
284    }
285}
286
287impl<B: AuditBackend> AuditBackend for BufferedAuditBackend<B> {
288    fn log_audit(&self, event: &AuditEvent) {
289        self.push(BufferedEntry::Audit(Box::new(event.clone())));
290    }
291
292    fn security_log(&self, event: &serde_json::Value) {
293        self.push(BufferedEntry::Security(Box::new(event.clone())));
294    }
295
296    fn flush(&self) {
297        self.drain_to_inner();
298    }
299}
300
301impl<B: AuditBackend> Drop for BufferedAuditBackend<B> {
302    fn drop(&mut self) {
303        self.drain_to_inner();
304    }
305}
306
307/// A shared backend is itself a backend, so an `Arc<dyn AuditBackend>` composes
308/// wherever a concrete one does — most usefully as the inner backend of a
309/// [`BufferedAuditBackend`], which requires a sized type.
310///
311/// `?Sized` covers the erased `Arc<dyn AuditBackend>` as well as `Arc<T>` for a
312/// concrete `T`.
313///
314/// ```rust
315/// use ash_log::*;
316/// use std::sync::Arc;
317///
318/// let shared: Arc<dyn AuditBackend> = Arc::new(StdoutAuditBackend);
319/// let buffered = BufferedAuditBackend::new(shared.clone(), 128);
320/// ```
321impl<T: AuditBackend + ?Sized> AuditBackend for std::sync::Arc<T> {
322    fn log_audit(&self, event: &AuditEvent) {
323        (**self).log_audit(event);
324    }
325
326    fn security_log(&self, event: &serde_json::Value) {
327        (**self).security_log(event);
328    }
329
330    fn flush(&self) {
331        (**self).flush();
332    }
333}
334
335#[cfg(test)]
336mod tests {
337    use super::*;
338    use crate::{AuditEventType, AuditResult};
339
340    #[test]
341    fn test_noop_backend() {
342        let backend = NoopAuditBackend;
343        let event = AuditEvent::builder()
344            .event_type(AuditEventType::MethodInvocation)
345            .result(AuditResult::Success)
346            .build();
347
348        backend.log_audit(&event); // Should not panic
349        backend.flush(); // Should not panic
350    }
351
352    #[test]
353    fn test_multi_backend() {
354        let multi =
355            MultiAuditBackend::new(vec![Box::new(NoopAuditBackend), Box::new(NoopAuditBackend)]);
356
357        let event = AuditEvent::builder()
358            .event_type(AuditEventType::AuthenticationAttempt)
359            .result(AuditResult::Success)
360            .build();
361
362        multi.log_audit(&event);
363        multi.flush();
364    }
365
366    /// Counts writes so tests can observe when the buffer actually drains.
367    #[derive(Default)]
368    struct CountingBackend {
369        audits: std::sync::atomic::AtomicUsize,
370        securities: std::sync::atomic::AtomicUsize,
371        flushes: std::sync::atomic::AtomicUsize,
372    }
373
374    impl CountingBackend {
375        fn audits(&self) -> usize {
376            self.audits.load(std::sync::atomic::Ordering::Relaxed)
377        }
378    }
379
380    impl AuditBackend for CountingBackend {
381        fn log_audit(&self, _event: &AuditEvent) {
382            self.audits
383                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
384        }
385
386        fn security_log(&self, _event: &serde_json::Value) {
387            self.securities
388                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
389        }
390
391        fn flush(&self) {
392            self.flushes
393                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
394        }
395    }
396
397    fn test_event() -> AuditEvent {
398        AuditEvent::builder()
399            .event_type(AuditEventType::MethodInvocation)
400            .result(AuditResult::Success)
401            .build()
402    }
403
404    #[test]
405    fn test_buffered_backend_defers_writes_until_flush() {
406        let inner = std::sync::Arc::new(CountingBackend::default());
407        let buffered = BufferedAuditBackend::new(inner.clone(), 10);
408
409        buffered.log_audit(&test_event());
410        buffered.log_audit(&test_event());
411
412        assert_eq!(buffered.buffered(), 2);
413        assert_eq!(inner.audits(), 0, "nothing written before flush");
414
415        buffered.flush();
416
417        assert_eq!(buffered.buffered(), 0);
418        assert_eq!(inner.audits(), 2, "flush wrote both events");
419    }
420
421    #[test]
422    fn test_buffered_backend_flushes_when_capacity_reached() {
423        let buffered = BufferedAuditBackend::new(CountingBackend::default(), 3);
424
425        buffered.log_audit(&test_event());
426        buffered.log_audit(&test_event());
427        assert_eq!(buffered.buffered(), 2, "below capacity");
428
429        buffered.log_audit(&test_event());
430        assert_eq!(buffered.buffered(), 0, "drained at capacity");
431        assert_eq!(buffered.into_inner().audits(), 3);
432    }
433
434    #[test]
435    fn test_buffered_backend_zero_capacity_writes_through() {
436        let buffered = BufferedAuditBackend::new(CountingBackend::default(), 0);
437
438        buffered.log_audit(&test_event());
439        assert_eq!(buffered.buffered(), 0);
440        assert_eq!(buffered.into_inner().audits(), 1);
441    }
442
443    #[test]
444    fn test_buffered_backend_flushes_on_drop() {
445        let inner = std::sync::Arc::new(CountingBackend::default());
446
447        {
448            let buffered = BufferedAuditBackend::new(inner.clone(), 100);
449            buffered.log_audit(&test_event());
450            buffered.log_audit(&test_event());
451            assert_eq!(inner.audits(), 0, "still buffered while in scope");
452        }
453
454        assert_eq!(inner.audits(), 2, "drop flushed the buffer");
455    }
456
457    #[test]
458    fn test_buffered_backend_preserves_order_across_event_kinds() {
459        /// Records the interleaving of audit and security writes.
460        #[derive(Default)]
461        struct OrderBackend(std::sync::Mutex<Vec<&'static str>>);
462
463        impl AuditBackend for OrderBackend {
464            fn log_audit(&self, _event: &AuditEvent) {
465                self.0.lock().unwrap().push("audit");
466            }
467
468            fn security_log(&self, _event: &serde_json::Value) {
469                self.0.lock().unwrap().push("security");
470            }
471        }
472
473        let buffered = BufferedAuditBackend::new(OrderBackend::default(), 100);
474
475        buffered.log_audit(&test_event());
476        buffered.security_log(&serde_json::json!({"class_uid": 3002}));
477        buffered.log_audit(&test_event());
478
479        let inner = buffered.into_inner();
480        let order = inner.0.lock().unwrap().clone();
481        assert_eq!(order, vec!["audit", "security", "audit"]);
482    }
483
484    #[test]
485    fn test_buffered_backend_survives_poisoned_lock() {
486        let buffered =
487            std::sync::Arc::new(BufferedAuditBackend::new(CountingBackend::default(), 100));
488
489        let poisoner = std::sync::Arc::clone(&buffered);
490        let handle = std::thread::spawn(move || {
491            let _guard = poisoner.buffer.lock().unwrap();
492            panic!("poison the buffer lock");
493        });
494        assert!(handle.join().is_err(), "helper thread should have panicked");
495
496        // The lock is poisoned, but buffered events must still be recoverable.
497        buffered.log_audit(&test_event());
498        buffered.flush();
499        assert_eq!(buffered.buffered(), 0);
500    }
501}