Skip to main content

Crate canarytrap

Crate canarytrap 

Source
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§

ApiKeyGenerator
Generator for API key-like canary values.
CallbackSink
A Sink that calls a user-provided callback.
CanaryEvent
Metadata event emitted when access to a canary token is detected.
CanaryRegistry
A thread-safe registry for canary tokens.
CanaryToken
A managed fake secret that emits events when instrumented access occurs.
CanaryTokenBuilder
Builder for CanaryToken.
CustomGenerator
Generator for custom canary values.
DbUrlGenerator
Generator for database URL-like canary values.
DeduplicatingSink
A sink wrapper that suppresses duplicate events.
JwtGenerator
Generator for JWT-like canary values.
ParseCanaryKindError
Error returned when a string cannot be parsed as a CanaryKind.
ParseTriggerSourceError
Error returned when a string cannot be parsed as a TriggerSource.
PasswordGenerator
Generator for password-like canary values.
PrivateKeyGenerator
Generator for private key-like canary values.
RateLimitedSink
A sink wrapper that limits the rate of event delivery.
TokenGenerator
Generator for opaque token-like canary values.

Enums§

CanaryKind
The kind of canary value represented by a token.
Error
Errors returned by CanaryTrap operations.
TriggerSource
The source that triggered access to a canary token.

Traits§

Generator
A generator of fake canary values.
Sink
A destination for canary event metadata.

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 Result type for CanaryTrap operations.