Metadata-Version: 2.4
Name: duckhunt-win
Version: 1.0.0rc1
Summary: Prevent RubberDucky and keystroke injection attacks
Author: Pedro M. Sosa
Maintainer: qb20nh
License-Expression: MIT
License-File: LICENSE
Keywords: keystroke-injection,rubberducky,security,usb-security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: pillow==12.0.0
Requires-Dist: pynput==1.8.1
Requires-Dist: pystray==0.19.5
Provides-Extra: dev
Requires-Dist: build==1.3.0; extra == 'dev'
Requires-Dist: pyinstaller==6.17.0; extra == 'dev'
Description-Content-Type: text/markdown

# DuckHunt

![DuckHunt Logo](duckhunt.32.png)

[![PyPI version](https://img.shields.io/pypi/v/duckhunt-win.svg?logo=pypi&logoColor=white)](https://pypi.org/project/duckhunt-win/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://github.com/qb20nh/duckhunt/actions/workflows/release.yml/badge.svg)](https://github.com/qb20nh/duckhunt/actions/workflows/release.yml)

**Prevent RubberDucky and Keystroke Injection Attacks**

DuckHunt protects Windows from "**RubberDucky**" attacks by monitoring typing patterns and immediately locking the system upon detecting inhumanly fast keystroke inputs.

## ✨ Features

* **Heuristic Detection**: Analyzes typing speed and burst patterns to distinguish between human typing and automated scripts.
* **Background Protection**: Runs unobtrusively in the system tray.
* **Smart Session Monitoring**: Event-based detection automatically pauses monitoring when the workstation is locked (no polling overhead).
* **Secure & Robust**:
  * Uses a split-process architecture (GUI + Daemon) for stability.
  * Single-instance enforcement prevents conflicts.
  * Auto-restarting daemon ensures continuous protection.
* **Configurable**: Adjustable sensitivity thresholds to match your typing style.

## 📦 Installation

**Prerequisites:** Python 3.10 or higher.

1. **Install from PyPI:**

   ```bash
   pip install duckhunt-win
   ```

2. **Clone the repository (for development):**

   ```bash
   git clone https://github.com/qb20nh/duckhunt.git
   cd duckhunt
   ```

3. **Install dependencies:**

```bash
pip install .
```

*For development, you can install with dev dependencies:*

```bash
pip install -e .[dev]
```

## 🚀 Usage

### Starting DuckHunt

You can start the application by running the module directly:

```bash
python -m duckhunt-win
```

Or by running the executable if you have downloaded the [latest release](https://github.com/qb20nh/duckhunt/releases/latest).

### System Tray Controls

Once running, DuckHunt appears in your system tray:

* **Left-Click / Toggle**: Enable or Disable monitoring.
* **Settings**: Open the configuration window to adjust sensitivity.
* **Exit**: Quit the application and stop the background protection daemon.

### How it Works

1. **Monitoring**: The `Daemon` process listens to global keystrokes using low-level hooks.
2. **Detection**: If the typing speed exceeds the configured **Threshold** (default 30ms/key) or exhibits suspicious **Bursts**, the detector flags the activity.
3. **Reaction**: The workstation is immediately locked via Windows API.
4. **Notification**: When you unlock your computer, DuckHunt notifies you that an attack was blocked.

## ⚙️ Configuration

You can configure DuckHunt via the Settings window or by creating a `duckhunt.toml` (or `duckhunt.conf`) file in your home directory or the application folder.

| Setting | Default | Description |
| :--- | :--- | :--- |
| `threshold` | `30` | Average interval between keys in milliseconds. Lower means faster typing is allowed (less sensitive). |
| `history_size` | `25` | Number of recent keystrokes to analyze for average speed. |
| `burst_keys` | `10` | Number of keys in a sequence to trigger "burst" detection. |
| `burst_window_ms` | `100` | Maximum time (ms) allowing `burst_keys` to be pressed before flagging as suspicious. |
| `allow_auto_type` | `true` | (Experimental) Allow software simulated keys. |

## 📄 License

MIT License
