canarytrap 0.2.0

Rust-native canary tokens and honeytokens for early detection of suspicious access to secrets and configuration.
Documentation
//! Event delivery abstractions for canary triggers.
//!
//! This module defines the [`Sink`] trait and provides built-in
//! implementations. Sinks receive [`CanaryEvent`] metadata only — never
//! the canary value.

mod callback;

#[cfg(feature = "file-audit")]
mod file;

pub use callback::CallbackSink;
#[cfg(feature = "file-audit")]
pub use file::FileAuditSink;

#[cfg(feature = "tracing")]
mod tracing_sink;

#[cfg(feature = "tracing")]
pub use tracing_sink::TracingSink;

#[cfg(feature = "log")]
mod log_sink;

mod dedup;
mod rate_limit;

use crate::CanaryEvent;

#[cfg(feature = "log")]
pub use log_sink::LogSink;

pub use dedup::DeduplicatingSink;
pub use rate_limit::RateLimitedSink;

/// A destination for canary event metadata.
///
/// Implementations receive [`CanaryEvent`] metadata only. They never receive
/// the canary value itself.
///
/// # Security
///
/// Implementations should not log, print, or persist the canary value. The
/// event type intentionally does not contain the value, but implementations
/// must also avoid reconstructing or leaking it through side channels.
///
/// # Error handling
///
/// Implementations should handle their own internal errors. A sink must not
/// break the instrumented application. `CanaryToken` additionally isolates
/// sink panics, but sink implementations should prefer graceful degradation
/// over panicking.
///
/// # Example
///
/// ```
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use std::sync::Arc;
///
/// use canarytrap::{CallbackSink, CanaryKind, CanaryToken, Sink};
///
/// let count = Arc::new(AtomicUsize::new(0));
/// let counter = count.clone();
///
/// let sink = CallbackSink::new(move |_event| {
///     counter.fetch_add(1, Ordering::SeqCst);
/// });
///
/// let token = CanaryToken::new("prod.db.password", CanaryKind::Password, "fake")
///     .with_sink(sink);
///
/// token.reveal();
///
/// assert_eq!(count.load(Ordering::SeqCst), 1);
/// ```
pub trait Sink: Send + Sync {
    /// Emits a canary event to this sink.
    ///
    /// This method receives metadata only.
    fn emit(&self, event: &CanaryEvent);
}