NullAILab/nullai-keylogger

# 键盘记录器 带有配套离线取证分析器的教育性按键记录工具。通过操作系统级别的输入钩子将按键记录捕获到循环日志文件中，随后允许你解析会话、提取词频并计算退格率。本工具旨在帮助你理解键盘记录器的工作原理——以便你能够检测并清除它们。 ## 你将构建的内容 两款工具： | 工具 | 用途 | |------|---------| | `keylogger.py` | 将按键记录捕获到带有可选时间戳的循环日志文件中 | | `parser.py` | 离线取证分析器——从日志文件中提取单词、三元组和会话统计信息 | ## 技术栈 | 组件 | 技术 | |-----------|-----------| | 语言 | Python 3.10+ | | 输入捕获 | `pynput`（封装了操作系统的钩子：`WH_KEYBOARD_LL` / Xlib / Quartz） | | 并发 | `threading.Thread` + `threading.Lock` | | 日志轮转 | 基于文件大小的重命名机制 | ## 项目结构 ``` 02-keylogger/ ├── README.md ├── .gitignore ├── src/ │ ├── keylogger.py ← Keystroke listener + log manager │ ├── parser.py ← Offline log analyser │ └── requirements.txt └── docs/ └── NOTES.md ← Architecture decisions ``` ## 安装说明 ``` cd 02-keylogger/src pip install -r requirements.txt ``` **macOS：** 你必须在 `系统偏好设置 → 隐私与安全性 → 辅助功能` 中授予终端（或你的 IDE）**辅助功能**权限。 ## 运行说明 ### 记录器 ``` # Basic — 记录到 keylog.txt，每 10 秒 flush 一次 python keylogger.py # 自定义路径和 flush 间隔 python keylogger.py --log /tmp/session.log --interval 5 # 禁用每键时间戳（更小的文件） python keylogger.py --no-timestamps # 在 1 MB 后 Rotate python keylogger.py --max-size 1024 ``` 使用 **Ctrl+C** 停止记录器。 **日志输出示例：** ``` ============================================================ Session started: 2026-04-28T14:32:10 ============================================================ [14:32:11.042]H[14:32:11.098]e[14:32:11.154]l[14:32:11.198]l[14:32:11.242]o [ENTER] [14:32:13.001]p[14:32:13.055]a[14:32:13.108]s[14:32:13.155]s[BKSP][BKSP]... ``` ### 解析器 ``` # 分析 log 文件 python parser.py keylog.txt # 显示前 30 个 words，忽略短于 4 个字符的 words python parser.py keylog.txt --top 30 --min-word 4 ``` **输出示例：** ``` ============================================================ KEYSTROKE LOG ANALYSIS REPORT ============================================================ Sessions found : 2 Total keystrokes : 1 842 Backspaces : 47 (2.6% of all keys) Session 1 | started: 2026-04-28T14:32:10 Keystrokes : 920 Unique words: 88 Top-5 words: 12 the 8 password 7 login ``` ## 工作原理 ### pynput 监听器 `pynput.keyboard.Listener` 向操作系统注册一个底层钩子： - **Windows** — 后台线程中的 `SetWindowsHookEx(WH_KEYBOARD_LL)` - **Linux** — Xlib 的 `XRecord` 扩展或 evdev - **macOS** — 通过 Quartz 框架的 `CGEventTap` 每次按键按下事件都会触发 `on_press(key)`。该回调函数将按键转换为 字符串 token 并将其追加到内存缓冲区中。 ### 线程安全的缓冲区 ``` Listener thread → append to buf (Lock) → Flush thread (every N sec) → file ``` 刷新线程按定时器唤醒，在锁的保护下排空缓冲区，并将 数据块写入磁盘。这最大限度地减少了 I/O 调用，并避免了在 两次刷新之间进程被杀死时丢失按键记录。 ### 日志轮转 当日志文件大小超过 `--max-size` KB 时，它会被重命名为 `keylog.txt.YYYYMMDD_HHMMSS`， 并且会在新文件中写入新的会话头。 ## 学习目标 - [ ] 理解 Windows 的 `WH_KEYBOARD_LL` 钩子链 - [ ] 理解 macOS 的辅助功能/Quartz 事件点击模型 - [ ] 了解键盘记录器如何实现持久化（注册表运行键、LaunchAgents、cron） - [ ] 了解 EDR/AV 工具如何检测键盘记录器 - [ ] 编写 YARA 规则以检测键盘记录器产物 - [ ] 识别 IOC：可疑的 `SetWindowsHookEx` 调用、异常的进程句柄 ## 防御检测 | 检测方法 | 检查内容 | |-----------------|-----------------| | 进程列表 | 意外的 Python 进程或加壳可执行文件 | | 启动项 | 注册表 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` | | 文件系统 | 临时目录或 AppData 目录中异常的 `.txt`/`.enc` 文件 | | 键盘钩子审计 | `GetRegisteredRawInputDevices`、Sysinternals Process Monitor | ## 挑战与扩展 - 增加 **邮件数据外发**——在刷新时通过 SMTP 发送日志数据块（仅限实验环境） - 使用 `pyperclip` 或 Win32 剪贴板 API 增加 **剪贴板捕获** - 增加 **屏幕截图触发器**——在按下特定热键时截取屏幕 - 实现 **日志加密**（Fernet / AES），确保原始文本不会写入磁盘 - 编写一个 **检测器**，用于枚举所有已注册的底层键盘钩子 - 使用 PyInstaller 打包为 `.exe`，提交至 VirusTotal，并研究检测结果 ## 参考资料 - [pynput 文档](https://pynput.readthedocs.io/) - [Windows 钩子链 — MSDN](https://docs.microsoft.com/en-us/windows/win32/winmsg/hooks) - [macOS CGEventTap — Apple Developer](https://developer.apple.com/documentation/coregraphics/1454426-cgeventtapcreate) - MITRE ATT&CK：[T1056.001 — 键盘记录](https://attack.mitre.org/techniques/T1056/001/) ## 道德声明 本工具仅供**教育和授权取证用途**。只能在你拥有或获得明确书面授权进行监控的 机器上运行它。未经同意记录按键在全球范围内的 CFAA、GDPR 及相关法律中 均属违法行为。 *NullAI Lab — 键盘记录器*

标签：DAST, pynput, Python, TGT, 代码示例, 安全教育, 并发编程, 恶意代码研究, 恶意软件分析, 攻防演练, 数据分析, 数据展示, 文件操作, 无后门, 日志轮转, 离线分析, 系统钩子, 红队, 线程安全, 网络安全, 键盘记录器, 隐私保护, 频率统计, 黑客技术学习