_  __          _
 | |/ /___ _   _| |_ _ __ __ _  ___ ___
 | ' // _ \ | | | __| '__/ _` |/ __/ _ \
 | . \  __/ |_| | |_| | | (_| | (_|  __/
 |_|\_\___|\__, |\__|_|  \__,_|\___\___|
           |___/

A transparent, consent-gated keylogger for cybersecurity education — watch exactly how keystroke capture and exfiltration work, end to end, so you can learn to detect and defend against them. 100% local logging · No hidden persistence · No hardcoded credentials.

⚠️ Warning — Ethical use only. Run Keytrace only on a machine or VM you own or are explicitly authorized to test. Never point it at a shared, institutional, or someone else's device. You are responsible for how you use this tool — unauthorized keystroke capture is a criminal offence in most countries (in India: IT Act 2000, Sections 43 & 66), regardless of intent.

📖 Table of Contents

• ✨ Features
• 🔍 How It Works
• 🚀 Installation
• 🧭 Usage
• 💾 Output & Reporting
• 🎓 Discussion Points for Class
• 🛠️ Tech Stack
• 👤 Author

✨ Features

#	Feature	What it does
1️⃣	Visible banner	Prints a clear "recording active" banner the moment it starts — nothing runs hidden
2️⃣	Typed consent gate	Requires the operator to type a confirmation before capture begins
3️⃣	Keystroke capture	Hooks keyboard input via pynput, mapping special keys ([ENTER], [SPACE], [BACKSPACE], etc.) to readable labels
4️⃣	Local logging	Every keystroke is timestamped and written to a plainly-named local file, keylog_output.txt
5️⃣	Email exfiltration demo	On stop (ESC), optionally emails the captured log via Gmail SMTP — demonstrates the exfil step attackers rely on
6️⃣	Zero hardcoded secrets	Credentials are read only from environment variables, never stored in code

🔍 How It Works

Keytrace hooks OS-level keyboard events through pynput, buffers them with timestamps, and writes them to a local log file. When you stop the session, it optionally sends that log over an authenticated SMTP connection to Gmail — the same mechanic real keyloggers use for exfiltration, but fully visible and opt-in here so it can be studied safely.

🚀 Installation

# 1. Clone
git clone https://github.com/Krish-Patwa01/Keytrace.git
cd Keytrace

# 2. Install dependencies
pip install -r requirements.txt

Requirements: Python 3.8+ on a Linux/Unix system.

🧭 Usage

Create a Gmail App Password (requires 2-Step Verification) — do not use your normal Gmail login password:

export GMAIL_ADDRESS="youraccount@gmail.com"
export GMAIL_APP_PASSWORD="xxxx xxxx xxxx xxxx"
export GMAIL_TO="youraccount@gmail.com"   # optional, defaults to GMAIL_ADDRESS

Then run it:

python3 keylogger_edu.py

Type keys to see them captured. Press ESC to stop — Keytrace then emails the captured log (if the env vars above are set) and leaves a copy in keylog_output.txt next to the script.

💾 Output & Reporting

Every session writes a timestamped, human-readable log to keylog_output.txt in the project directory — ideal for walking through in class or diffing between runs. This file is git-ignored by default so captured input never accidentally lands in version control.

🎓 Discussion Points for Class

• What OS-level API is pynput using under the hood on Linux (X11/evdev)?
• How would an EDR/antivirus product detect this process?
• What outbound-traffic signatures would flag the SMTP exfiltration step?
• Why doesn't requiring typed consent + a visible banner make a tool "safe" by itself — what additional controls make this an authorized test vs. malware?

🛠️ Tech Stack

Built with the Python standard library (smtplib, ssl, email) plus one light dependency: pynput.

👤 Author

Krish Patwa GitHub

---

Made for educational & authorized security testing only.