Redox023/Keytrace

# KeyTrace **按键遥测与行为分析框架**     ## ⚠️ 伦理守门机制 在项目根目录下创建一个 `CONSENT.md` 文件，确认你拥有或者获得了明确的书面授权来监控运行该工具的系统之前，KeyTrace 将不会运行。未经授权的按键捕获在大多数司法管辖区均属重罪（美国：18 U.S.C. § 2511；欧盟：GDPR 第 5 条及各国窃听法；印度：IT 法案 § 66E/72）。同意验证门已在 `keytrace/ethics/consent.py` 中实现，且无法被静默绕过。 ## 为什么会有这个项目 大多数“初学者键盘记录器”项目只是展示了如何调用 `pynput.Listener`。KeyTrace 的构建是为了展示不同的东西：我理解围绕凭证窃取工具的完整安全生命周期——从收集、存储处理、数据外发，再到检测工程。 这个项目中的每一项功能都对应一项现实世界中的安全能力： | 功能 | 展示的技能 | |---|---| | AES-256-GCM 静态加密 | 应用密码学（认证加密） | | PBKDF2-HMAC-SHA256 密钥派生 | KDF 选择、加盐、迭代调优 | | HMAC 链式日志条目 | 防篡改日志记录，取证完整性 | | 按键动力学提取（停留/飞行时间） | 行为生物识别，持续身份验证 | | 统计异常检测（基于基线的 z-score） | 轻量级 UEBA，基线建模 | | 自动脱敏 CC/SSN/JWT/API-key 模式 | DLP 工程，正则表达式强化 | | MITRE ATT&CK 映射 | 威胁知情防御素养 | | 内置 YARA + Sigma 规则 | 检测工程，紫队思维 | | 基于同意的执行控制 | 默认安全工具，道德披露 | ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ CONSENT GATE │ │ (refuses to start without signed CONSENT.md in project root) │ └────────────────────────────────┬────────────────────────────────┘ │ ┌──────────────────┴──────────────────┐ │ CAPTURE LAYER │ │ pynput listener → raw events │ │ active-window enricher │ │ F9 runtime pause/resume │ └──────────────────┬──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ ANALYTICS PIPELINE │ │ ├─ Keystroke dynamics │ │ │ (dwell, flight, rhythm σ) │ │ └─ Anomaly detector │ │ (z-score vs trained baseline) │ └──────────────────┬──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ REDACTION FILTER │ │ Regex DLP for CC/SSN/JWT/keys │ │ → replaces with [REDACTED:TYPE] │ └──────────────────┬──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ INTEGRITY LAYER │ │ HMAC-SHA256 chain over entries │ │ (Hₙ = HMAC(K, Hₙ₋₁ ‖ entryₙ)) │ └──────────────────┬──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ STORAGE LAYER │ │ AES-256-GCM (PBKDF2-derived key) │ │ Size-based rotation │ └─────────────────────────────────────┘ ``` 完整详情请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。MITRE ATT&CK 映射在 [`docs/MITRE-ATTACK.md`](docs/MITRE-ATTACK.md)。威胁模型在 [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md)。 ## 快速开始 ``` git clone https://github.com/Redox023/keytrace.git cd keytrace python -m venv .venv && source .venv/bin/activate pip install -e . # 签署同意文件（否则将拒绝运行） cp CONSENT.template.md CONSENT.md # 编辑 CONSENT.md，替换 和 # 运行 keytrace run --passphrase-env KEYTRACE_PASS ``` 按 **F9** 暂停/恢复捕获。按 **Ctrl+C** 停止并刷新加密日志。 ### 解密会话日志 ``` keytrace decrypt logs/2026-05-11T13-22-04.kt.enc --passphrase-env KEYTRACE_PASS keytrace verify logs/2026-05-11T13-22-04.kt.enc # checks HMAC chain ``` ### 分析按键动力学 ``` keytrace analyze logs/2026-05-11T13-22-04.kt.enc # → 平均停留时间，平均飞行时间，rhythm σ，前 N 个异常时间窗口 ``` ## 检测工程 KeyTrace 附带了针对该工具本身的检测内容——因为构建攻击性工具时如果不考虑它会被如何捕获，那这个项目就只算完成了一半。 - [`detection/keytrace.yar`](detection/keytrace.yar) — 匹配加密日志魔法字节、嵌入字符串特征以及 GCM nonce 前缀模式的 YARA 规则。 - [`detection/keytrace.sigma.yml`](detection/keytrace.sigma.yml) — 用于 SIEM 接入的 Sigma 规则（进程创建 + 命令行中包含 `pynput` 的可疑 python 子进程 explorer）。 针对示例日志加载 YARA 规则： ``` yara detection/keytrace.yar logs/ ``` ## 威胁模型（摘要） | 威胁 | KeyTrace 中的缓解措施 | |---|---| | 静态日志窃取 | AES-256-GCM，密钥从不写入磁盘 | | 攻击者篡改日志 | HMAC 链——任何静默编辑都会导致 `verify` 失败 | | 日志中的敏感数据（密码、银行卡） | 加密前的正则 DLP 脱敏 | | 操作员滥用 | 同意守门机制；无签名文件则拒绝启动 | | 取证归因 | 日志带有时间戳并进行链式锚定 | | 通过内存转储获取密钥 | 停机时通过 `secrets.token_bytes` 覆盖将密钥清零 | 该威胁模型在某些方面是有意留有未尽的——请参阅 [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md) 了解残留风险的讨论（运行时的内存转储、位于该工具底层的内核级键盘记录器等）。这种讨论本身也是使其成为一件优秀作品集展示的一部分。 ## 电梯演讲（简短推介） 如果你想知道这个项目与标准的键盘记录器教程有何不同，这里就是简短推介： ## 许可证 MIT，附带教育用途附加条款。详见 [`LICENSE`](LICENSE)。请勿在未拥有或未获得明确书面授权监控的系统上使用此工具。

标签：AES-256-GCM, Cloudflare, DNS信息、DNS暴力破解, HMAC, HTTP工具, MITRE ATT&CK, PBKDF2, PII过滤, Python, Sigma规则, YARA规则, Zenmap, 人工智能安全, 伦理安全, 击键动力学, 击键遥测, 合规性, 安全生命周期, 密码学, 密钥派生, 异常检测, 手动系统调用, 按键记录, 教育目的, 数据加密, 数据完整性, 数据防泄漏(DLP), 无后门, 用户和实体行为分析(UEBA), 目标导入, 紫队, 网络安全, 行为生物识别, 逆向工具, 隐私保护, 隐私脱敏