# hak5/usbrubberducky-payloads architecture

> Architecture diagram of the GitHub repository hak5/usbrubberducky-payloads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hak5/usbrubberducky-payloads
- Repository: https://github.com/hak5/usbrubberducky-payloads

## Overview

##### Main Components
- Repository Core: This includes the common “root” of the repository with general documents such as README.md, CONTRIBUTING.md, and GitHub configuration files (in .github). These files guide contributions, coding standards, and legal disclaimers.
- Languages Module: Represented by the “languages” directory. This module contains JSON files (e.g., us.json, jp.json, de.json, etc.) that provide keyboard layout configurations. They are integral to compiling payloads correctly for various locales.
- Payloads Module: A major component, which itself breaks down into several sub-components:
– Examples: In the “payloads/examples” directory, where sample payloads for different attack modes (e.g., ATTACKMODE, Button, Conditions, etc.) reside.
– Extensions: Found in “payloads/extensions” that provide additional helper scripts or advanced functionalities to extend DuckyScript.
– Library: The “payloads/library” directory is further divided into categories such as credentials, execution, exfiltration, general, incident_response, mobile, prank, recon, and remote_access. These categories help organize the hundreds of payloads by their intended function or attack type.
- Compiler/Editor (PayloadStudio): Although not part of the repository codebase, the README explains that payloads must be compiled using PayloadStudio (which is an external, client‐side editor and compiler) into a binary “inject.bin” file that the USB Rubber Ducky can execute.
- USB Rubber Ducky Device: This is the end target where the compiled payloads (created by PayloadStudio using code from this repository) are deployed for keystroke injection. Although not “inside” the repository, it is an essential part of the payload lifecycle.
- Community/Developer Interaction: The repository is hosted on GitHub and is driven by community contributions. This dynamic is indicated by pull requests, the CONTRIBUTING.md guidelines, and the social links provided (Discord, forums, etc.).

##### Relationships and Data Flow
- Flow Direction: Show that payload authors (developers/contributors) use the repository as a source for DuckyScript payloads. These authors push new payloads, language configurations, and extensions into specific directories.
- Feedback/Iteration: Optionally, include how developers might iterate on their payloads based on community feedback (e.g., pull requests, issues).

##### Important Architectural Patterns
- Modular Organization: Emphasize that the repository is neatly organized into modules (languages, payloads with well-defined subdirectories) that make it easy to add or extend both payload types and language support.
- Separation of Concerns: Note the clear separation between the “source” (written in DuckyScript as plain text payload files and language mapping files) and the “compiled” artifact (the inject.bin file). Also, there’s a separation between the contributions (payloads) and the external tool (PayloadStudio) that compiles and deploys them.
- Static Repository with External Integration: Although the repository is static, it interacts with external tools (PayloadStudio and the device) to complete the payload generation and deployment lifecycle.

##### Incorporate Relevant Technologies and Components
- DuckyScript™: Mark that the payload files are written in this specific scripting language.
- JSON for Languages: Include technology (JSON) in the languages module.
- Git and GitHub Infrastructure: Show that community collaboration is managed via pull requests, commits, and the .github directory.
- External Tools: PayloadStudio (editor and compiler) and the USB Rubber Ducky device are external but critical to the overall workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-Level: Payload Authors and Community
    PA("Payload Authors"):::community
    CD("Community & Documentation"):::community

    %% Repository Core Subgraph
    subgraph "Repository Core"
        R1("README.md"):::repository
        R2("CONTRIBUTING.md"):::repository
        R3(".github"):::repository
    end

    %% Languages Module
    LM("Languages Module<br/>(JSON Configurations)"):::languages

    %% Payloads Module Subgraph
    subgraph "Payloads Module"
        P1("Examples"):::payload
        P2("Extensions"):::payload
        P3("Library"):::payload
    end

    %% External Components
    PS("PayloadStudio (Compiler/Editor)"):::process
    DUCK("USB Rubber Ducky Device"):::device

    %% Data Flow Connections
    PA -->|"contributes"| CD
    CD -->|"guides"| R1
    CD --> R2
    CD --> R3

    %% Repository Core is central to the repository
    R1 --- R2
    R2 --- R3

    %% Repository Core related modules
    R1 -->|"includes"| LM
    R1 -->|"includes"| P1
    R1 --> P2
    R1 --> P3

    %% Modules feed into the compilation process
    LM -->|"supplies config"| PS
    P1 -->|"payload source"| PS
    P2 --> PS
    P3 --> PS

    %% Compilation to Deployment Flow
    PS -->|"compiles to binary"| DUCK

    %% Click Events for Mapped Components
    click R1 "https://github.com/hak5/usbrubberducky-payloads/blob/master//README.md"
    click R2 "https://github.com/hak5/usbrubberducky-payloads/blob/master//CONTRIBUTING.md"
    click R3 "https://github.com/hak5/usbrubberducky-payloads/blob/master//.github"
    click LM "https://github.com/hak5/usbrubberducky-payloads/tree/master//languages"
    click P1 "https://github.com/hak5/usbrubberducky-payloads/tree/master//payloads/examples"
    click P2 "https://github.com/hak5/usbrubberducky-payloads/tree/master//payloads/extensions"
    click P3 "https://github.com/hak5/usbrubberducky-payloads/tree/master//payloads/library"

    %% Styles
    classDef repository fill:#f2d7d5,stroke:#c0392b,stroke-width:2px;
    classDef languages fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef payload fill:#fcf3cf,stroke:#f39c12,stroke-width:2px;
    classDef process fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef device fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef community fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
```
