GhostLock

GhostLock is a cross-platform keep-alive and input-isolation utility for Windows, Linux, and macOS. It simulates light mouse and keyboard activity to prevent session lockouts and screen sleep, while blocking physical keyboard and mouse input to protect your workstation against unintended local tampering or accidental bumps.

Key Features

• Linux & Ubuntu (Wayland & X11): Full native support for both Ubuntu Wayland (default) and Ubuntu on Xorg (X11). Injects keep-alive events directly through kernel /dev/uinput, completely bypassing Wayland security restrictions that break traditional mouse jigglers.
• Cross-Platform Physical Input Shielding:
  • Windows: Uses Win32 Low-Level Hooks (WH_KEYBOARD_LL & WH_MOUSE_LL) to suppress physical inputs while allowing synthetic keep-alive events to pass through.
  • Linux (Ubuntu & others): Uses kernel evdev (EVIOCGRAB) on physical /dev/input/event* devices for exclusive hardware-level isolation.
  • macOS: Uses Quartz Event Taps to intercept and suppress physical events.
• Subtle Keep-Alive Simulation: Injects tiny cursor jitters (+/-1 pixel) and safe modifier key taps (Shift / Ctrl) to prevent idle detection without modifying open files or documents.
• Emergency Hardware Unlock: Hardware-level shortcut (Shift + Escape) is the exclusive way to release hardware locks and stop GhostLock when input shielding is active. (Terminal Ctrl+C is disabled during shielding so the lock cannot be bypassed).
• Configurable CLI: Customize pulse intervals, cursor jitter distance, auto-exit timeouts, or run in keep-alive only mode (--no-grab).
• Clean Teardown: Automatically releases all hooks, kernel grabs, and virtual devices upon exit.

Requirements

• Python 3.8+ (tested with Python 3.10 and 3.12)
• Windows: Standard user privileges (Administrator recommended to block input across elevated windows). Zero external dependencies required (uses built-in ctypes).
• Linux: Root privileges (sudo) or membership in the input group.
• macOS: Accessibility permissions in System Settings > Privacy & Security > Accessibility.

Installation

Clone the repository and install dependencies:

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
# On Linux / macOS:
source .venv/bin/activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install requirements
pip install -r requirements.txt

(Note: On Windows, input shielding and keep-alive run via Python's standard library ctypes, requiring zero external packages or compiled extensions).

Usage

Run GhostLock with default settings (1-second pulses, 1-pixel alternating toggle, hardware lock enabled):

# On Linux (Wayland & X11):
sudo .venv/bin/python ghostlock.py

# On Windows:
python ghostlock.py

# On macOS:
python ghostlock.py

Command-Line Options

usage: ghostlock [-h] [-i INTERVAL] [-j JITTER] [--no-grab] [-t TIMEOUT] [-v]

options:
  -h, --help            Show this help message and exit
  -i, --interval SECS   Interval between pulses in seconds (default: 1.0)
  -j, --jitter PIXELS   Cursor jitter in pixels per pulse (default: 1)
  --no-grab, --no-lock  Run in keep-alive only mode without blocking physical inputs
  -t, --timeout DURATION
                        Auto-exit duration (e.g. '30s', '15m', '2h')
  -v, --version         Show program's version number and exit

Examples

# Default mode (physical lock active, only Shift+Escape unlocks):
python ghostlock.py

# Keep-alive only mode (no input locking, Ctrl+C enabled) for 45 minutes:
python ghostlock.py --no-grab -t 45m

# Pulse every 5 seconds:
python ghostlock.py -i 5

Stopping & Unlocking

1. Standard Mode (Input Shield Active)

When the physical input shield is engaged, all physical keyboard/mouse input and terminal interrupt signals (Ctrl + C) are intentionally blocked.

Shift + Escape is the exclusive shortcut to release hardware locks and terminate GhostLock:

• 👉 Shift + Escape

2. Keep-Alive Only Mode (--no-grab)

If you explicitly ran with --no-grab, physical inputs are not blocked and you can stop GhostLock with standard Ctrl + C.

3. Emergency Remote Kill (Secondary Shell)

If physical access is completely unavailable:

# Linux / macOS (via SSH or secondary terminal):
pkill -f ghostlock.py

# Windows (PowerShell):
Stop-Process -Name python -Force

Project Structure

GhostLock/
├── ghostlock.py             # CLI entrypoint & argument parser
├── requirements.txt         # Platform-tagged dependencies (PEP 508)
├── LICENSE                  # MIT License
├── README.md                # Documentation
├── ghostlock_core/
│   ├── app.py               # Central application coordinator
│   ├── activity.py          # Synthetic keep-alive pulse engine (uinput / Win32 / pynput)
│   └── backends/
│       ├── base.py          # Abstract BaseInputShield interface
│       ├── windows_hook.py  # Win32 Low-Level Hooks (ctypes)
│       ├── linux_evdev.py   # Linux kernel evdev device grabber (EVIOCGRAB)
│       └── macos_tap.py     # macOS Quartz Event Tap
└── tests/
    ├── unit/                # Unit tests (CLI, backends, activity, app)
    └── integration/         # Integration tests (CLI subprocesses & engine coordination)

Running Tests

GhostLock includes a test suite divided into Unit Tests and Integration Tests:

# Run all tests (unit + integration):
python -m unittest discover -s tests

# Run unit tests only:
python -m unittest discover -s tests/unit

# Run integration tests only:
python -m unittest discover -s tests/integration

License

This project is licensed under the MIT License - see the LICENSE file for details.