KeyWraith - Adaptive BadUSB/HID attack emulation + behavioral

项目说明

KeyWraith

Adapti/HID attack emulation + beha endpoint detection with the Flipper Zero.

> A *wraith* typing at superhuman speed through the keyboard interface — the
> in injected-keystroke attacker. KeyWraith uses the Flipper Zero's
> USB-HID capability to build, then defeat, a keystroke-injection
> detector.


---

One-line pitch

Turn a Flipper Zero into a controlled keystroke-injection ad to build the
labeled dataset nobody has, then train and stress-test a beha BadUSB
detector — an end-to-end HID purple-team platform. **The deli is a
detector + explainable endpoint alert; the offensi exists only to
generate honest training data and to red-team the defense.**

The problem

The Flipper Zero can present itself to a computer as a USB keyboard and "type" a
scripted payload at machine speed (the classic Rubber Ducky / BadUSB attack).
The OS trusts keyboards implicitly, so this bypasses most host defenses. The
offensive side is well-trodden. The defensive side — reliably detecting that
"the user" typing right now is actually an injection device, grounded in real
beha data rather than de allow-lists — is surprisingly thin.

KeyWraith builds both halves: a reproducible HID-injection emulator that
manufactures a labeled injected- keystroke dataset, and a beha
detector (the logic an EDR agent would run) that flags injection in real time
from timing dynamics and produces an operator-readable alert. Then it closes the
loop: *can an adapti slow down and humanize the injection to evade the
detector, and at what cost?*

Why it's novel

1. **A labeled human- keystroke dataset — including humanized attack
— which is scarce.** The methodology + dataset is itself a contribution.
2. Beha BadUSB detection grounded in data, the usual
de/policy heuristics.
3. The e arms race. Quantifying the detection-
tradeoff — how slow an attacker must go to look human, and whether that's
still detectable — is a real research result, not just a classifier.
4. Keystroke dynamics repurposed for defense, not biometrics. Usually studied
for user authentication; here it distinguishes human injection.

Architecture

Full module map in docs/architecture.md.

Quickstart

Or with make: make setup && make demo && make report. Run the tests with
make test (30 tests).

Indi stages:

More CLI commands:

Tiers

KeyWraith is scoped so the full research story runs in software, with hardware as
an optional upgrade.

| Tier | Needs | What it delivers |
|---|---|---|
| 1 — software *(default, in this repo)* | Python only | Synthetic generator → features → detector → explainable alert, benchmarked against a nai baseline across humanization levels. A complete, no with no Flipper. |
| 2 — hardware + human data | Flipper Zero, consenting typists, pynput | Wire in real injection (keywraith.host_agent + benign payloads, auto-labeled by keywraith.labeling) and real human captures; measure the sim-to-real gap. Same feature/detector code. |
| 3 — research payoff | Tier 1 | The adapti and e arms race: sweep humanization, plot detection throttle cost, test whether an e retrained detector wins the round. |

Headline results (Tier 1, seed 17)

_Regenerate with python -m keywraith.cli report. Full numbers in
results/results_summary.md and
results/metrics.json._

Detection quality — beha detector vs the standard speed-threshold defense:

!ROC and PR

Why it works — inter-key timing separates human from each injection mode:

!IKI distributions

**The e arms race (headline figure) — the detector holds full detection
through humanization level 0.9 while the nai collapses once the
attacker slows down; full e costs the attacker a ~40× longer exposure
window:**

!E curve

**Detection recall per injection mode — the baseline is defeated by humanization;
the beha detector is not:**

!Per-mode recall

Winning the next round — e retraining. A *standard* detector that
only trained on weak humanization collapses once the attacker humanizes past ~0.5.
An *e* detector that also trained on strong humanization reclaims the
lost region — up to 0.95 detection at humanization level 0.9 — with **no
increase in human false positives** (both stay at FPR ≈ 0.00). Only full
humanization (level 1.0, statistically indistinguishable from a human, at maximum
attacker time cost) defeats both:

!E retraining

| Model | ROC-AUC | Precision | Recall | FPR |
|---|---|---|---|---|
| Beha detector | 1.000 | 1.000 | 1.000 | 0.000 |
| Speed-threshold baseline | 0.997 | 0.995 | 0.951 | 0.004 |

> On the fully-synthetic Tier 1 data the beha detector is near-perfect; the
> honest, interesting result is the arms-race curve, where it maintains
> detection long after the speed baseline is blind, and the cost the attacker
> pays to e evade it. Absolute numbers will move on real hardware — that
> sim-to-real gap is measured, not hidden.

Example endpoint alert

The defensi is an operator-readable alert. From keywraith.cli demo
on a humanized injection (full sample):

Note how at humanization level 0.6 the speed already looks human (5.9 cps, a
40-second session) — a speed threshold is blind here — yet the machine-regular
dwell time and low cadence still give the wraith away.

Real-time detection

Beyond scoring whole sessions, keywraith.stream.StreamDetector
runs the detector the way an EDR would — over a **sliding window of the most
recent keystrokes**, with alert debouncing so a single noisy window doesn't fire.
Feed it li one at a time (push) or scan a session offline
(scan_session); the two paths are exactly equi. On the Tier 1 data it
catches injection with a median time-to-detection of ~50 keystrokes, at a 0%
human false-alarm rate (python -m keywraith.cli stream).

Feature set

19 timing/cadence features, chosen because human and injected typing separate
along them. The scale-free regularity features (iki_cv, iki_autocorr_lag1,
dwell_cv, digraph_) are what keep the detector alive when an attacker
simply slows down to beat a speed threshold. Full table:
docs/feature_set.md.

E plan

Detection quality: ROC/PR and false-alarm rate vs a speed-threshold baseline.

Robustness: performance across injection modes and unseen humanization levels.

Sim-to-real: does a detector trained on synthetic hold up on shifted / real

captures? Quantified (Tier 1 ships a shifted-profile proxy; Tier 2 uses real data).

Ad: the e arms race — attacker cost to evade, and whether

retraining recovers detection.

False positives on real humans: fast/metronomic typists are the key

deployability risk and are measured explicitly.

Security

Software-security posture (project responsible-use rules are in the threat model):

Tamper-e models. scikit-learn models are pickles, and unpickling runs

code. Beha.save() writes a .sha256 sidecar; .load()
it by default and refuses a tampered, corrupt, or un model, and
refuses trusted=False. Integrity, not authenticity — still only load models you
trust.

Input on every prediction (shape + finite-value checks).

No network I/O, no secrets, no untrusted deserialization of data (datasets

are plain numeric NDJSON/CSV). Raw human captures are git-ignored.

CI + CodeQL + Dependabot with least-pri GITHUB_TOKEN permissions

(.github/). See SECURITY.md for reporting.

Threat model & ethics

Defensi is central and binding. Injection is performed only against
hosts the author owns; the repo ships no weaponized payloads (DuckyScripts are
limited to benign, clearly-labeled marker strings), no turnkey attack tooling, and
no real credentials. Human data is consented and stored only as de-identified
timing features, never raw text. Read docs/threat_model.md
before running any hardware.

Repository layout

Reading list

Flipper Zero BadUSB / DuckyScript documentation · HID keystroke injection (Rubber
Ducky) attacks · keystroke-dynamics feature literature · USB/HID security and
BadUSB mitigations · beha endpoint detection (EDR) concepts · ad
e of beha detectors. This work sits where USB/HID hardware attacks
meet beha ML detection meet endpoint defense.

Citation

See CITATION.cff.

Author

Krishita Sanjay Choksi () — sole
author and contributor. Released under the MIT License.

项目信息

开发语言：Python

Star 数：5

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Adaptive BadUSB/HID attack emulation + behavioral endpoint detection with the Flipper Zero. Defensive-security research: build a labeled human-vs-injected keystroke dataset, train an EDR-style detector, and red-team it with an adaptive humanized attacker.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。