Win32-Input-Detector

A lightweight Python security and input telemetry tool designed to capture physical vs. software-injected keyboard events and monitor raw XInput gamepad inputs on Windows.

Win32-Input-Detector intercepts low-level OS input events to detect synthetic keypresses generated by macros, key mappers, or injection software using the Win32 KBDLLHOOKSTRUCT API. It also provides structured XInput telemetry polling for Xbox/DirectInput controllers with configurable stick deadzones.

---

Key Features

• Injected Keystroke Detection: Inspects Win32 KBDLLHOOKSTRUCT flags (LLKHF_INJECTED = 0x10) to distinguish physical keyboard hardware events from synthetic/software-injected keystrokes.
• XInput Gamepad Telemetry: Polls digital button states, trigger threshold transitions, and optional high-precision analog stick movements via xinput1_4.dll.
• Interactive Startup Wizard: Run directly to launch a guided CLI menu, or bypass prompts using command-line arguments.
• Flexible Capture Modes: Monitor Keyboard + Gamepad concurrently, Keyboard-only, or Gamepad-only (with optional analog stick tracking).

---

Technical Overview

1. Keyboard Injection Detection (KBDLLHOOKSTRUCT)

When a keyboard event occurs, Windows passes a low-level hook structure (KBDLLHOOKSTRUCT) to registered listeners. The tool evaluates the bitmask data.flags & 0x10 (LLKHF_INJECTED).

• Physical Hardware: LLKHF_INJECTED bit is 0.
• Synthetic/Injected: LLKHF_INJECTED bit is 1 (triggered by SendInput, keybd_event, or macro software).

2. Controller State Polling (XInput)

Controller telemetry is retrieved using native C structures (XINPUT_STATE and XINPUT_GAMEPAD) loaded dynamically via ctypes. Digital buttons are processed using bitwise masks, while analog stick telemetry applies deadzone filtering to prevent log spamming during small stick shifts.

---

Project Structure

Win32-Input-Detector/
├── .gitignore
├── License.txt
├── README.md
├── input_detector.py
└── requirements.txt

---

Prerequisites

• OS: Windows 10 / 11
• Python: Python 3.8+

---

Installation

1. Clone the repository:

git clone [https://github.com/ConceptExplorer/Win32-Input-Detector.git](https://github.com/ConceptExplorer/Win32-Input-Detector.git)
cd Win32-Input-Detector

2. Install dependencies:

pip install -r requirements.txt

---

Usage

Interactive Mode (Default)

Simply run the script without arguments to open the interactive setup wizard:

python input_detector.py

CLI Flag Mode

Bypass the interactive wizard by passing command-line arguments:

Goal	Command
Both (Keyboard + Gamepad Buttons)	python input_detector.py
Both (Buttons + Analog Sticks)	python input_detector.py --include-analogs
Keyboard Only	python input_detector.py --mode kb-only
Gamepad Only (Buttons only)	python input_detector.py --mode gamepad-only
Gamepad Only (Buttons + Analog Sticks)	python input_detector.py --mode gamepad-only --include-analogs

---

Output Examples

Keyboard Hardware vs. Injected Keystrokes

[KEYBOARD HARDWARE] Physical Keypress: VK 65
[KEYBOARD FLAGGED] INJECTED KEYSTROKE DETECTED! VK: 65 | Flags: 0x10

Gamepad Telemetry

[GAMEPAD EVENT] Packet #412 | A, RIGHT_SHOULDER (RB)
[GAMEPAD EVENT] Packet #428 | LT (Val: 185)
[GAMEPAD EVENT] Packet #502 | LX: -14200, LY: 22100

---

License

MIT License. See License.txt for details.