Expand description
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};
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"
);§Generator example
use canarytrap::{generate, CanaryKind};
let password = generate(&CanaryKind::Password)?;
assert!(!password.is_empty());
let api_key = generate(&CanaryKind::ApiKey)?;
assert!(api_key.starts_with("ct_ak_"));§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.
Structs§
- ApiKey
Generator - Generator for API key-like canary values.
- Callback
Sink - A
Sinkthat calls a user-provided callback. - Canary
Event - Metadata event emitted when access to a canary token is detected.
- Canary
Registry - A thread-safe registry for canary tokens.
- Canary
Token - A managed fake secret that emits events when instrumented access occurs.
- Canary
Token Builder - Builder for
CanaryToken. - Custom
Generator - Generator for custom canary values.
- DbUrl
Generator - Generator for database URL-like canary values.
- Deduplicating
Sink - A sink wrapper that suppresses duplicate events.
- JwtGenerator
- Generator for JWT-like canary values.
- Parse
Canary Kind Error - Error returned when a string cannot be parsed as a
CanaryKind. - Parse
Trigger Source Error - Error returned when a string cannot be parsed as a
TriggerSource. - Password
Generator - Generator for password-like canary values.
- Private
KeyGenerator - Generator for private key-like canary values.
- Rate
Limited Sink - A sink wrapper that limits the rate of event delivery.
- Token
Generator - Generator for opaque token-like canary values.
Enums§
- Canary
Kind - The kind of canary value represented by a token.
- Error
- Errors returned by CanaryTrap operations.
- Trigger
Source - The source that triggered access to a canary token.
Traits§
Functions§
- generate
- Generates a fake canary value for the given kind using the thread RNG.
- generate_
using - Generates a fake canary value for the given kind using the provided RNG.
Type Aliases§
- Result
- A specialized
Resulttype for CanaryTrap operations.