CanaryTrap
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:
[]
= "0.2"
With all sinks enabled:
[]
= { = "0.2", = ["sinks"] }
Quick Start
use ;
Sinks and Decorators
CanaryTrap provides multiple sinks and composable decorators:
use ;
use Duration;
Run the full demo:
Generated Canary Values
CanaryTrap can generate realistic fake canary values:
use ;
Supported built-in kinds: Password, ApiKey, Token, Jwt, DbUrl,
PrivateKey, Custom(String).
Registry Example
use ;
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:
[]
= { = "0.2", = false, = ["registry", "tracing"] }
Examples
Run the included examples:
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>/memreads;- 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;
// Bad — do not log the canary value
println!;
// Better — print metadata, not the value
let value = token.reveal;
println!;
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.