1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//! 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.
pub use CanaryTokenBuilder;
pub use ;
pub use CanaryEvent;
use json_escape;
pub use ;
pub use ;
pub use ;
pub use CanaryToken;
pub use ;
pub use LogSink;
pub use TracingSink;
pub use CanaryRegistry;
pub use FileAuditSink;
pub use ;