canarytrap 0.2.0

Rust-native canary tokens and honeytokens for early detection of suspicious access to secrets and configuration.
Documentation

CanaryTrap

Crates.io Docs.rs CI Rust 1.85+ License

CanaryTrap is a Rust-native library for canary tokens and honeytokens. It helps applications detect suspicious access to secrets, configuration values, and other internal data by placing controlled fake values and emitting events when those values are accessed through instrumented APIs.

Status: v0.2.0 — sinks, decorators, and extended events. The API is not stable yet.

Why CanaryTrap?

Many incidents start quietly:

  • someone reads a config file;
  • someone prints secrets in debug output;
  • someone copies environment variables;
  • someone tries to use an internal API key;
  • someone explores application internals.

CanaryTrap lets you place controlled fake secrets — canary tokens — and receive a signal when they are accessed. It is an early-detection and deception tool.

Current Status

Module Description Status
CanaryToken Managed fake secret with instrumented access ✅ implemented
CanaryKind Classification of canary value type ✅ implemented
CanaryEvent Metadata-only event with correlation/thread ids ✅ implemented
TriggerSource Source of the trigger ✅ implemented
Sink trait Event delivery abstraction ✅ implemented
Callback sink Calls a user-provided function on trigger ✅ implemented
File audit sink JSONL audit log ✅ implemented
tracing sink Integration with tracing ✅ implemented
log sink Integration with log ✅ implemented
Deduplicating sink Suppresses duplicate events ✅ implemented
Rate limiting sink Sliding window rate limiter ✅ implemented
CanaryRegistry Thread-safe registry for canary tokens ✅ implemented
Generators Fake passwords, API keys, tokens, JWTs, DB URLs, keys ✅ implemented
Builder API Convenient CanaryToken construction ✅ implemented
Examples Basic, registry, generator, and sinks demos ✅ implemented
File canary Canary files and access monitoring 🔜 planned
Env canary Canary values in environment variables 🔜 planned
Derive macros #[derive(Canary)], #[canary] 🔜 planned

Installation

Add to your Cargo.toml:

[dependencies]
canarytrap = "0.2"

With all sinks enabled:

[dependencies]
canarytrap = { version = "0.2", features = ["sinks"] }

Quick Start

use canarytrap::{CanaryKind, CanaryToken};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = CanaryToken::builder("prod.db.password")
        .kind(CanaryKind::Password)
        .value("canary-fake-password-9f8a7b")
        .on_trigger(|event| {
            eprintln!(
                "canary triggered: id={} name={} kind={} source={}",
                event.token_id,
                event.token_name,
                event.kind,
                event.source,
            );
        })
        .build()?;

    // Place this fake value in config, env, test data, or another location.
    // The example intentionally prints only the length, not the value itself.
    let fake_value = token.reveal();
    println!("fake value length: {}", fake_value.len());

    Ok(())
}

Sinks and Decorators

CanaryTrap provides multiple sinks and composable decorators:

use canarytrap::{
    CanaryKind, CanaryToken, DeduplicatingSink, FileAuditSink,
    RateLimitedSink, TracingSink, LogSink,
};
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // JSONL file audit with deduplication and rate limiting.
    let file_sink = FileAuditSink::new("/var/log/canarytrap.jsonl")?;
    let decorated = RateLimitedSink::per_second(
        DeduplicatingSink::with_window(file_sink, Duration::from_secs(60)),
        10,
    );

    let token = CanaryToken::builder("prod.api.key")
        .kind(CanaryKind::ApiKey)
        .generate_value()
        .with_sink(decorated)
        .with_sink(TracingSink::new())
        .with_sink(LogSink::new())
        .build()?;

    let _ = token.reveal();
    Ok(())
}

Run the full demo:

cargo run --example sinks_demo --features sinks

Generated Canary Values

CanaryTrap can generate realistic fake canary values:

use canarytrap::{generate, CanaryKind, CanaryToken};

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_"));

    let token = CanaryToken::generate("prod.db.password", CanaryKind::Password)?;
    let fake_value = token.reveal();
    println!("generated token id: {}", token.id());
    println!("generated value length: {}", fake_value.len());

    Ok(())
}

Supported built-in kinds: Password, ApiKey, Token, Jwt, DbUrl, PrivateKey, Custom(String).

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-9f8a7b")
        .build()?;

    let id = registry.register(token)?;

    let by_id = registry.reveal(&id)?;
    let by_name = registry.reveal("prod.db.password")?;
    assert_eq!(by_id, by_name);

    Ok(())
}

Feature Flags

Feature Description Default
registry Thread-safe canary token registry yes
generators Fake canary value generators yes
file-audit JSONL file audit sink no
tracing tracing sink integration no
log log sink integration no
sinks All sinks (file-audit, tracing, log) no
full Enable all features no

Example with selective features:

[dependencies]
canarytrap = { version = "0.2", default-features = false, features = ["registry", "tracing"] }

Examples

Run the included examples:

cargo run --example basic_canary
cargo run --example registry_demo --features registry
cargo run --example generated_tokens --features generators
cargo run --example sinks_demo --features sinks

Security Model

CanaryTrap is a defense-in-depth and deception tool.

What CanaryTrap can help detect

  • access to a fake secret through CanaryTrap APIs;
  • suspicious use of configuration values;
  • suspicious access to environment-like canary values;
  • early signs of compromise.

What CanaryTrap does NOT guarantee

CanaryTrap cannot guarantee detection of:

  • raw memory reads;
  • process memory dumps;
  • /proc/<pid>/mem reads;
  • kernel-level attacks;
  • fully compromised operating systems;
  • physical attacks.

Important rule

Canary events contain metadata only. They do not contain the canary value.

// Good
token.on_trigger(|event| {
    eprintln!("canary triggered: {}", event.token_name);
});

// Bad — do not log the canary value
println!("canary value: {}", token.reveal());

// Better — print metadata, not the value
let value = token.reveal();
println!("canary value length: {}", value.len());

See SECURITY.md for the full threat model and security policy.

Roadmap

Version Focus
v0.1 Core: tokens, registry, events, callback sink, generators
v0.2 Sinks (file/tracing/log), decorators, extended events
v0.3 Proc-macros, serde, integrations
v0.4 Advanced deception capabilities

For security vulnerabilities, do not open a public issue. Use private security reporting — see SECURITY.md.

MSRV

Minimum Supported Rust Version: 1.85

CanaryTrap uses Rust edition 2024.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.