jezman/canarytrap

# CanaryTrap [][crates-url] [][downloads-url] [][docs-url] [][msrv-url] [][license-url] CanaryTrap 是一个原生的 Rust 库，用于 canary token 和 honeytoken。 它通过放置受控的虚假值，并在这些值通过插桩 API 被访问时发出事件， 帮助应用程序检测对 secrets、配置值和其他内部数据的可疑访问。 ## 为什么使用 CanaryTrap？ 许多安全事件都是悄然发生的： - 有人读取了配置文件； - 有人在调试输出中打印了 secrets； - 有人复制了环境变量； - 有人尝试使用内部 API key； - 有人探索了应用程序内部结构。 CanaryTrap 允许你放置受控的虚假 secrets —— 即 canary token —— 并在它们被访问时 接收到信号。 它是一款早期检测和欺骗工具。 ## 功能 | 模块 | 描述 | 状态 | | ---------------- | ------------------------------------------------------------- | ---------- | | `CanaryToken` | 带有插桩访问管理的虚假 secret | 已实现 | | `CanaryKind` | canary 值类型分类 | 已实现 | | `CanaryEvent` | 触发时发出的仅包含元数据的事件 | 已实现 | | `TriggerSource` | 触发源 | 已实现 | | `Sink` trait | 事件传递抽象 | 已实现 | | Callback sink | 触发时调用用户提供的函数 | 已实现 | | `CanaryRegistry` | 用于 canary token 的线程安全注册表 | 已实现 | | Generators | 生成虚假密码、API key、token、类 JWT 值、数据库 URL 和密钥 | 已实现 | | Builder API | 便捷的 `CanaryToken` 构造方式 | 已实现 | | File audit sink | JSONL 审计日志 | 计划中 | | `tracing` sink | 与 `tracing` 集成 | 计划中 | | `log` sink | 与 `log` 集成 | 计划中 | | File canary | Canary 文件及访问监控 | 计划中 | | Env canary | 环境变量中的 Canary 值 | 计划中 | | Derive macros | `#[derive(Canary)]`，`#[canary]` | 计划中 | ## 安装 在 crates.io 上发布后： ``` [dependencies] canarytrap = "0.1" ``` 默认功能： ``` canarytrap = { version = "0.1", features = ["registry", "generators"] } ``` ## 快速入门 ``` use canarytrap::{CanaryKind, CanaryToken}; fn main() -> Result<(), Box> { 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(()) } ``` ## 生成的 Canary 值 CanaryTrap 可以生成虚假的 canary 值： ``` use canarytrap::{generate, CanaryKind, CanaryToken}; fn main() -> Result<(), Box> { 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(()) } ``` 支持的内置类型： ``` CanaryKind::Password CanaryKind::ApiKey CanaryKind::Token CanaryKind::Jwt CanaryKind::DbUrl CanaryKind::PrivateKey CanaryKind::Custom(String) ``` ## Registry 示例 ``` use canarytrap::{CanaryKind, CanaryRegistry, CanaryToken}; fn main() -> Result<(), Box> { 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(()) } ``` ## 功能开关 | 功能 | 描述 | 默认值 | | ------------ | ----------------------------- | ------ | | `registry` | 线程安全的 canary token 注册表 | 是 | | `generators` | 虚假 canary 值生成器 | 是 | | `sinks` | 额外的 sink | 否 | | `full` | 启用所有主要功能 | 否 | 示例： ``` [dependencies] canarytrap = { version = "0.1", default-features = false, features = ["registry", "generators"] } ``` ## 示例 运行内置的示例： ``` cargo run --example basic_canary ``` ``` cargo run --example registry_demo ``` ``` cargo run --example generated_tokens ``` ## 安全模型 CanaryTrap 是一款纵深防御和欺骗工具。 ### CanaryTrap 可以帮助检测什么 - 通过 CanaryTrap API 访问虚假 secret； - 对配置值的可疑使用； - 对类环境 canary 值的可疑访问； - 系统遭到破坏的早期迹象。 ### CanaryTrap 无法保证什么 CanaryTrap 无法保证检测到： - 原始内存读取； - 进程内存转储； - 读取 `/proc//mem`； - 内核级别的攻击； - 完全受损的操作系统； - 物理攻击。 ### 重要规则 Canary 事件仅包含元数据。 它们**不**包含 canary 值本身。 推荐做法： ``` token.on_trigger(|event| { eprintln!("canary triggered: {}", event.token_name); }); ``` 错误做法： ``` token.on_trigger(|_event| { // Do not log the canary value. }); ``` 同时，请避免直接记录 canary 值： ``` // Bad println!("canary value: {}", token.reveal()); ``` 优先使用元数据： ``` // Better let value = token.reveal(); println!("canary value length: {}", value.len()); ``` ## 路线图 | 版本 | 重点 | | ----- | ------------------------------------------------------------------- | | v0.1 | 核心：token、注册表、事件、callback sink、生成器 | | v0.2 | 文件/环境 canary、tracing/log/file sink、速率限制、去重 | | v0.3 | 过程宏、serde、集成 | | v0.4 | 高级欺骗能力 | | v1.0 | 稳定的 API 和安全审计准备 | 对于安全漏洞，请**不要**提交公开的 issue。 请使用私下的安全报告方式，例如 GitHub Security Advisories 或 `SECURITY.md` 中列出的安全联系方式。 ## 许可证 根据以下任一许可证授权： - MIT 许可证 - Apache 许可证，版本 2.0 由你自行选择。

标签：BOF, Rust, StruQ, 可视化界面, 欺骗防御, 网络流量审计, 蜜罐, 证书利用, 通知系统, 金丝雀令牌