canarytrap 0.2.0

Rust-native canary tokens and honeytokens for early detection of suspicious access to secrets and configuration.
Documentation
//! CanaryTrap is a Rust-native library for canary tokens and honeytokens.
//!
//! The crate is intended to help applications detect suspicious access to
//! secrets, configuration values, and other sensitive internal data by
//! placing controlled fake values and emitting events when those values are
//! accessed through instrumented APIs.
//!
//! # Example
//!
//! ```
//! use std::sync::atomic::{AtomicUsize, Ordering};
//! use std::sync::Arc;
//!
//! use canarytrap::{CanaryKind, CanaryToken, TriggerSource};
//!
//! let count = Arc::new(AtomicUsize::new(0));
//! let counter = count.clone();
//!
//! let token = CanaryToken::builder("prod.db.password")
//!     .kind(CanaryKind::Password)
//!     .value("canary-fake-password")
//!     .on_trigger(move |event| {
//!         counter.fetch_add(1, Ordering::SeqCst);
//!         assert_eq!(event.source, TriggerSource::Reveal);
//!     })
//!     .build()
//!     .expect("token build should succeed");
//!
//! assert_eq!(token.reveal(), "canary-fake-password");
//! assert_eq!(count.load(Ordering::SeqCst), 1);
//!
//! let debug = format!("{token:?}");
//! assert!(debug.contains("[REDACTED]"));
//! assert!(!debug.contains("canary-fake-password"));
//! ```
//!
//! # Registry example
//!
//! ```
//! use canarytrap::{CanaryKind, CanaryRegistry, CanaryToken};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let registry = CanaryRegistry::new();
//!
//! let token = CanaryToken::builder("prod.db.password")
//!     .kind(CanaryKind::Password)
//!     .value("canary-fake-password")
//!     .build()?;
//!
//! let id = registry.register(token)?;
//!
//! assert_eq!(registry.reveal(&id)?, "canary-fake-password");
//! assert_eq!(
//!     registry.reveal("prod.db.password")?,
//!     "canary-fake-password"
//! );
//! # Ok(())
//! # }
//! ```
//!
//! # Generator example
//!
//! ```
//! use canarytrap::{generate, CanaryKind};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let password = generate(&CanaryKind::Password)?;
//! assert!(!password.is_empty());
//!
//! let api_key = generate(&CanaryKind::ApiKey)?;
//! assert!(api_key.starts_with("ct_ak_"));
//! # Ok(())
//! # }
//! ```
//!
//! # Status
//!
//! This crate is in early development. The public API is not stable yet.
//!
//! # Safety policy
//!
//! The core crate aims to be fully safe Rust. Any future `unsafe` block must
//! include explicit `SAFETY` and `Invariants` comments explaining why the
//! block is sound.
//!
//! # Threat model
//!
//! CanaryTrap is a deception and early-detection tool. It can detect
//! instrumented access to canary values, but it does not guarantee detection
//! of raw memory reads, process dumps, kernel-level attacks, or a fully
//! compromised operating system.
//!
//! # Security rule
//!
//! Canary events must not contain canary values. Events contain only
//! metadata: token id, token name, kind, trigger source, and timestamp.

#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![warn(missing_debug_implementations)]

mod builder;
mod error;
mod event;
mod json;
mod kind;
mod sink;
mod source;
mod token;

#[cfg(feature = "generators")]
mod generator;

#[cfg(feature = "registry")]
mod registry;

pub use builder::CanaryTokenBuilder;
pub use error::{Error, Result};
pub use event::CanaryEvent;
use json::json_escape;
pub use kind::{CanaryKind, ParseCanaryKindError};
pub use sink::{CallbackSink, Sink};
pub use source::{ParseTriggerSourceError, TriggerSource};
pub use token::CanaryToken;

#[cfg(feature = "generators")]
pub use generator::{
    ApiKeyGenerator, CustomGenerator, DbUrlGenerator, Generator, JwtGenerator, PasswordGenerator,
    PrivateKeyGenerator, TokenGenerator, generate, generate_using,
};
#[cfg(feature = "log")]
pub use sink::LogSink;

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

#[cfg(feature = "registry")]
pub use registry::CanaryRegistry;

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

pub use sink::{DeduplicatingSink, RateLimitedSink};