Documentation
¶
Overview ¶
Package badusb parses DuckyScript / BadUSB payload scripts into structured line-by-line views — command + arguments + validation status. Pure offline parser; no transport, no hardware.
Wrap-vs-native judgement: DuckyScript v1 is a public language (Hak5's USB Rubber Ducky reference, mirrored by Flipper Zero BadUSB and the broader BadUSB ecosystem). The parser is a line-based lexer + command-dispatch table. Wrapping a FAP for this would require an SD-card install + a firmware-fork dependency for a pure parser. We implement natively so operators get a pre-deployment syntax check that surfaces:
- Unknown commands
- Invalid argument types (e.g. DELAY needs a positive int)
- Total estimated execution time
- Line-numbered diagnostics
Pairs with the existing internal/validator/badusb.go (which does severity-pattern scanning for malicious payloads) — together they cover the syntactic + semantic validation surface.
What this package covers:
- Line tokenisation: command (first whitespace-delimited word) + arguments (the rest, preserved as a single string for STRING / STRINGLN; split for key-combo commands)
- Command catalog: ~50 documented DuckyScript v1 commands (DELAY / STRING / GUI / CTRL / ALT / SHIFT / ENTER / TAB / ESC / function keys / navigation / locks / modifiers / REPEAT / REM / DEFAULTDELAY)
- Per-command argument validation (DELAY → positive int, STRING → free text, key combos → single key, etc.)
- Comment + blank line handling
- Estimated execution time calculation (DELAY + DEFAULTDELAY between commands + per-keystroke STRING typing time)
What this package does NOT cover (deliberately out of scope):
- DuckyScript v3 (Hak5's extended dialect: variables, conditionals, loops, language layouts) — separate parser when callers materialise
- Severity-pattern scanning (powershell -enc, rm -rf, etc.) — covered by internal/validator/badusb.go
- Script execution (operators bring the Flipper transport)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Line ¶
type Line struct {
// Number is the 1-based line number in the source.
Number int `json:"number"`
// Source is the original line content, leading/trailing
// whitespace stripped.
Source string `json:"source"`
// Kind is "blank", "comment", "command", or "invalid".
Kind string `json:"kind"`
// Command is the uppercase command name (empty for blank /
// comment lines).
Command string `json:"command,omitempty"`
// Args is the raw argument string after the command word.
// For STRING / STRINGLN / REM this preserves the full
// remaining text; for key-combo commands it's the additional
// key name(s).
Args string `json:"args,omitempty"`
// Issue is non-empty when the line failed validation
// (unknown command, invalid argument format).
Issue string `json:"issue,omitempty"`
// EstimatedMS is the per-line execution-time estimate added
// to the total. 0 for blank / comment / pure-modifier lines.
EstimatedMS int `json:"estimated_ms"`
}
Line is one parsed DuckyScript line.
type Script ¶
type Script struct {
// Lines is the ordered list of parsed lines.
Lines []Line `json:"lines"`
// LineCount is len(Lines).
LineCount int `json:"line_count"`
// CommandCount counts non-blank non-comment lines.
CommandCount int `json:"command_count"`
// CommentCount counts REM / blank lines.
CommentCount int `json:"comment_count"`
// IssueCount counts lines with validation issues.
IssueCount int `json:"issue_count"`
// EstimatedTotalMS is the sum of per-line estimates.
EstimatedTotalMS int `json:"estimated_total_ms"`
// DefaultDelayMS reflects the script's effective
// DEFAULTDELAY value (default 0; updated when the script
// sets it).
DefaultDelayMS int `json:"default_delay_ms"`
}
Script is the top-level parsed result.
Source Files