keyguard-lab - Defensive security research laboratory for keyboar

项目说明

KeyGuard Lab

A defensi research laboratory for keyboard-input capture and detection.

![Python]()

---

What this is

KeyGuard Lab is an educational cybersecurity project that demonstrates
how keyboard-input capture technology works — from both the offensive
perspective (how malware captures keystrokes) and the defensi
(how defenders detect such behavior). It is designed to be **safe by
construction**: no network code, no persistence mechanisms, no stealth,
synthetic-data-only tests, and an explicit consent gate.

The project was built from first principles as a portfolio piece for a
cybersecurity learner. It is not a copy of any existing keylogger
tutorial or repository.

---

Why this exists

Keylogging is one of the oldest and most pre malware techniques
(MITRE ATT&CK T1056.001).
Understanding how it works — at the API level, the data-flow level, and
the detection level — is foundational knowledge for any defensive
security engineer. Most public educational resources either:

* Show only the offensive side (how to build a keylogger), with no
detection component, OR
* Show only the defensive side (how to detect keyloggers), with no
concrete understanding of what they're detecting.

KeyGuard Lab closes that gap by building both sides in a single
safe, synthetic, self-contained laboratory.

---

Quick start

Output appears under lab_output/<session-uuid>/:

---

What you'll learn

| Topic | Where it's taught |
|---|---|
| How keyboard hooks work on Windows / macOS / Linux | src/keyguard/capture/pynput_adapter.py, docs/concepts.md |
| Event normalization and stable representations | src/keyguard/normalize/normalizer.py |
| Timezone-aware UTC timestamping | src/keyguard/models/events.py |
| Thread-safe event bus with backpressure | src/keyguard/control/e.py |
| Size-based log rotation | src/keyguard/storage/rotation.py |
| State-machine controller (start/pause/resume/stop) | src/keyguard/control/controller.py |
| Rule-based detection engine | src/keyguard/detection/rules.py, engine.py |
| Synthetic EDR-style telemetry | src/keyguard/detection/telemetry.py |
| MITRE ATT&CK mapping | docs/detection.md |
| Threat modeling and abuse cases | docs/threat-model.md |
| Safe-lab design principles | SECURITY.md, docs/testing.md |

---

Safety properties ( by automated tests)

The following in are enforced by the test suite in tests/safety/:

1. No network code anywhere. A static scan no socket,
urllib, requests, http.client, etc. imports. A runtime test
monkeypatches socket.socket to raise and runs the full pipeline.
2. No persistence mechanisms. A static scan no winreg,
LaunchAgents, crontab, systemctl, os.system, or
subprocess.* calls. A runtime test no files are written
to startup locations during a session.
3. Stop mechanism is responsive. stop() completes within 2 seconds
even with an acti, including when paused.
4. Tests use synthetic input only. A static scan no test
file imports the real PynputAdapter.
5. Explicit consent required. The CLI refuses to start without
--i-consent (interactive) or --i-consent flag (non-interactive).
6. Output is labelled. All output files have a LAB_ prefix or
li a session-UUID subdirectory.

Run the safety suite any time:

---

Project structure

---

Documentation

The docs/ directory contains long-form educational content:

| File | What it covers |
|---|---|
| o.md | High-le orientation |
| concepts.md | Keyboard hook APIs, MITRE ATT&CK, defensi concepts |
| architecture.md | Component diagram, data flow, event lifecycle |
| implementation.md | Walk-through of each module with design rationale |
| detection.md | MITRE ATT&CK mapping, detection rules, Sigma/Sysmon references |
| threat-model.md | Threat model, abuse-case table, security controls |
| testing.md | Test architecture, safety in, how to add tests |
| troubleshooting.md | Common problems and solutions |
| challenges.md | Design challenges encountered and how they were resolved |

---

CLI reference

| Flag | Description |
|---|---|
| --config PATH | Path to a TOML config file (default: configs/default.toml) |
| --i-consent | Explicit consent flag. Required to start capture. |
| --synthetic | Use the synthetic input adapter (no real keyboard capture). |
| --real | Use the real pynput adapter. Requires pynput installed and (macOS) Accessibility permission. |
| --script demo\|suspicious | Which synthetic script to use (default: demo) |
| --duration SECONDS | Run for this many seconds, then stop. If omitted, runs until Ctrl+C. |
| --no-detection | Disable the detection engine. |
| -- | Enable DEBUG logging. |
| -- | Print and exit. |

---

Responsible use

This project is intended exclusively for:

* Your own personal computer
* A dedicated cybersecurity laboratory
* Authorized security research and education
* Defensi analysis and demonstration

**You MUST only run the capture component on devices you own or for which
you ha, written authorization.** Capturing keyboard input
without consent is illegal in most jurisdictions. See SECURITY.md
for the full responsible-use policy.

---

License

MIT — see LICENSE.

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive security research laboratory for keyboard-input capture and detection (educational, safe-by-design)展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。