KeyForge is built from the ground up with a Security-First Architecture designed by software engineers and cybersecurity analysts. Because input automation software interacts directly with the operating system's low-level input queues (user32.SendInput and SetWindowsHookEx), macro utilities historically suffer from severe security and reliability vulnerabilities.

• Threat: Many legacy macro tools use scripting engines, eval(), exec(), pickle, or embedded shell commands in saved macro files, turning community-shared macros into malware delivery vectors.
• Mitigation:
  • KeyForge profiles (.kfmacro.json) are strictly declarative data structures parsed via json.loads with custom depth/size limits.
  • Zero dynamic code evaluation (eval, exec, pickle, subprocess, os.system) exists anywhere in the runtime or profile loader.
  • Every action type, key name, mouse button, coordinate, and timing parameter is validated against a strict allowlist schema (keyforge.security.validator).

• Threat: Silent corruption or unauthorized modification of saved macro files causing erratic input behavior.
• Mitigation:
  • Saved profiles compute and embed a canonical SHA-256 integrity digest (integrity_sha256) over the normalized macro payload.
  • When loading a profile, KeyForge verifies the SHA-256 digest before parsing steps into the engine (with explicit user notification if a file was manually edited outside KeyForge).

• Threat:
  1. Malformed "JSON bomb" files (deeply nested Repeat loops or gigabyte files) crashing the application.
  2. Zero-delay infinite loops (0ms wait) flooding the Windows USER32 input queue and locking the user out of their PC.
  3. Stuck modifier keys (Shift, Ctrl, Alt) or mouse buttons left depressed when a macro is aborted mid-cycle.
• Mitigation:
  • File Size & Complexity Caps: Maximum profile file size is capped at 1 MiB; maximum step count (5,000), maximum repeat nesting depth (5), and maximum expanded execution operations per cycle (100,000) are strictly enforced.
  • OS Input Queue Flood Protection: If a repeating macro loop contains 0ms total delay across an entire cycle, the execution engine automatically enforces a configurable minimum safety yield (MIN_SAFE_CYCLE_DELAY_MS = 5ms) so the Windows kernel and UI thread remain responsive.
  • Hardware Panic Kill-Switch: A dedicated low-level hotkey (F12 by default) immediately trips an atomic threading.Event, waking any active wait timer within <5ms.
  • Automatic Stuck-Input Sanitizer: The executor tracks every depressed key (KEY_DOWN) and mouse button (MOUSE_DOWN) in a thread-safe ledger and unconditionally dispatches matching KEY_UP / MOUSE_UP events in a finally: block upon completion, stop, panic abort, or exception.

• Threat: A macro sends a keystroke that triggers its own Start hotkey or gets re-recorded by the Live Recorder, causing exponential recursion.
• Mitigation:
  • Every synthetic Win32 INPUT event dispatched by KeyForge is stamped with a magic signature in dwExtraInfo (0x4B465247 / "KFRG").
  • Both the Live Recorder and Global Hotkey hooks inspect dwExtraInfo and ignore synthetic events generated by KeyForge itself.

• Threat: Malicious file paths or symlinks overwriting sensitive system files.
• Mitigation:
  • Profile paths are canonicalized with Path.resolve(), verified against null bytes, restricted to .json / .kfmacro.json extensions, and written atomically via temporary file swap.

• KeyForge makes zero network connections, includes no analytics, no telemetry, no update pings, and no third-party tracking libraries.

If you discover a security issue in KeyForge, please open a GitHub Security Advisory on the repository or contact the maintainer directly before public disclosure.