Skip to content

threat_model.md

Latest commit

 

History

History
70 lines (57 loc) · 3.8 KB

threat_model.md

File metadata and controls

70 lines (57 loc) · 3.8 KB
Raw

KeyWraith — Threat Model, Scope & Ethics

KeyWraith is defensive-security research. Its deliverable is a detector plus an explainable endpoint alert. The offensive component (a Flipper Zero acting as a BadUSB device, plus a software adaptive attacker) exists solely to generate honest, labeled training data and to red-team the defense. This document is a binding part of the project, not boilerplate.

1. What KeyWraith defends

The BadUSB / "Rubber Ducky" attack: a device enumerates as a USB HID keyboard and injects a scripted keystroke sequence at machine speed. Operating systems trust keyboards implicitly, so this bypasses most host defenses. Existing mitigations are overwhelmingly policy (disable USB, allow-list device IDs) rather than behavioral. KeyWraith asks: can the endpoint tell, from the typing itself, that "the user" typing right now is actually an injection device — and can it explain that call to an analyst?

2. Actors

Actor Capability In scope
Genuine human operator Types naturally; variable cadence, pauses, typos ✅ (benign class)
Stock BadUSB attacker Flipper/Ducky burst or fixed-delay injection ✅ (attack class)
Adaptive attacker Deliberately humanizes timing to evade detection ✅ (the research payoff)
Defender / analyst Runs the behavioral detector, reads alerts ✅ (the user)

3. Scope limits (hard rules)

  1. Injection is performed only against hosts the author owns. Never against any machine you are not explicitly authorized to test.
  2. No weaponized payloads. Every shipped DuckyScript is benign: it types a clearly-labeled marker phrase and nothing else. The repo contains no credential theft, downloaders, reverse shells, privilege escalation, or any turnkey attack tooling. See ../flipper/payloads/README.md.
  3. The humanized attacker is a data/analysis tool, not a delivery tool. It produces timing sessions used to train and stress-test the detector. It does not emit or assemble a runnable payload.
  4. No detection-evasion for malicious use. The arms-race study measures the cost of evasion to inform defenders; it is not a recipe for evading real deployed EDRs, and it is scoped to KeyWraith's own detector on owned hardware.

4. Human-subject data — consent & privacy

  • Any genuine-human typing data is collected with informed consent.
  • Only de-identified timing/keycode-class features are ever stored or committed — never raw text, never the literal characters typed. The capture agent records a coarse keycode class (letter/space/digit/punct/ backspace), so a stored session cannot reconstruct what was typed.
  • Data must never contain real credentials. Volunteers type neutral, non-sensitive content.
  • Raw captures stay local and git-ignored (data/capture*.ndjson, data/raw/). Only the synthetic dataset and de-identified feature CSVs are tracked.

5. Responsible-use notice

KeyWraith is for authorized endpoint-security research and assessment only. Only test devices you own or are explicitly authorized to test. The offensive emulation exists solely to generate training data and to red-team the detector. You are responsible for complying with all applicable laws and policies.

6. Residual risks & non-goals

  • Not a shipping EDR. KeyWraith is a research pipeline; the detector is not hardened for production adversaries or side-channels.
  • Sim-to-real gap is real. Tier 1 results come from a synthetic generator. Numbers will move on real hardware and real humans; that gap is itself measured (see the evaluation plan), never hidden.
  • False positives on fast, metronomic human typists are the key deployability risk and are explicitly measured, not assumed away.