# mqz0211/oh-my-usb architecture

> Architecture diagram of the GitHub repository mqz0211/oh-my-usb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mqz0211/oh-my-usb
- Repository: https://github.com/mqz0211/oh-my-usb

## Overview

##### Project type and purpose
- Oh My USB is a lightweight, command-line Python tool for crafting BadUSB (HID) payloads.
- It targets penetration testers and hardware hackers, not a multi-service web app or distributed system.

##### File structure
- Top-level:
- ohmyusb.py – monolithic Python script containing all business logic, CLI, payload presets, safety checks, reporting.
- README.md + LICENSE – documentation and license.
- No separate “frontend” or “backend” services, no external microservices or databases.

##### README for additional insights
- Core features: preset payloads, custom scripting, stealth mode, payload statistics, dangerous-command detection.
- Invocation flow: user selects preset or writes script → optional stealth delays → safety scan → stats summary → output file.
- No external dependencies besides Python standard library (presumably argparse, random, time, etc.).

a. Main components (logical modules)
- CLI / User Interface – handles user prompts, menu selection.
- Payload Manager – holds built-in presets and loads custom DuckyScript.
- Stealth Mode Processor – injects randomized delays into the payload script.
- Safety Checker – scans commands for disallowed/dangerous patterns.
- Stats Analyzer – computes line counts, delay counts, timing estimates.
- Output Generator – writes final .txt (Rubber Ducky) or other HID formats.

b. Relationships and data flow
1. User → CLI UI: selects preset or custom input
2. CLI UI → Payload Manager: retrieve or accept script lines
3. Payload Manager → Stealth Processor (if enabled): interleave DELAY commands
4. Processed script → Safety Checker: flag/remove dangerous commands
5. Clean script → Stats Analyzer: compute metrics
6. Final script + stats → Output Generator → Written file / clipboard
7. Optional: CLI UI displays stats, safety warnings, suggested external listener.

c. Architectural patterns and principles
- Pipeline design: sequential processing stages (Manager → Stealth → Safety → Stats → Output).
- Single responsibility per module.
- Extensibility hooks: easy to add new presets, output formats, or safety rules.

d. Key technologies
- Python 3.x standard library (argparse or input(), random, time, file I/O).
- DuckyScript syntax (as data format).
- HID-based payload targets (Rubber Ducky, Digispark).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::external
    subgraph "Processing Stages"
        CLI["CLI / User Interface"]:::process
        PayloadMgr["Payload Manager"]:::process
        Stealth["Stealth Mode Processor"]:::process
        Safety["Safety Checker"]:::process
        Stats["Stats Analyzer"]:::process
        Output["Output Generator"]:::process
    end
    subgraph "Data Artifacts"
        DScript(["DuckyScript lines"]):::data
        PScript(["Processed script"]):::data
        CleanScript(["Cleaned script"]):::data
        Report(["Stats report"]):::data
        FinalPayload(["Final HID Payload"]):::data
    end
    subgraph "External Interfaces"
        Rubber["Rubber Ducky / HID Device"]:::external
        Digispark["Digispark / HID Device"]:::external
        Reverse["Reverse-shell listener"]:::external
    end

    %% Flow
    User -->|"select preset or custom"| CLI
    CLI -->|"request script"| PayloadMgr
    PayloadMgr -->|"load lines"| DScript

    DScript -->|"if stealth enabled"| Stealth
    DScript -->|"if stealth disabled"| Safety

    Stealth -->|"interleaved delays"| PScript
    Safety -->|"scan commands"| CleanScript
    PScript --> Safety
    CleanScript -->|"cleaned script"| Stats
    Stats -->|"metrics & counts"| Report
    Report -->|"display stats/warnings"| CLI
    Report --> Output
    Output -->|"write file"| FinalPayload
    FinalPayload --> Rubber
    FinalPayload --> Digispark
    CLI -->|"suggest listener"| Reverse

    %% Click Events
    click CLI "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"
    click PayloadMgr "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"
    click Stealth "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"
    click Safety "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"
    click Stats "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"
    click Output "https://github.com/mqz0211/oh-my-usb/blob/main/ohmyusb.py"

    %% Styles
    classDef process fill:#D6E4FF,stroke:#1F77B4,color:#000
    classDef data fill:#E2F0CB,stroke:#7FBA00,color:#000
    classDef external fill:#F0F0F0,stroke:#A0A0A0,stroke-dasharray:5 5,color:#000
```
