hak5/usbrubberducky-payloads

Payload Library for the USB Rubber Ducky by Hak5

This repository contains payloads, extensions and languages for the Hak5 USB Rubber Ducky. Community developed payloads are listed and developers are encouraged to create pull requests to make changes to or submit new payloads.

Payloads here are written in official DuckyScript™ specifically for the USB Rubber Ducky. Payloads here must be compiled using Hak5 PayloadStudio. Hak5 does NOT guarantee payload functionality. See Legal and Disclaimers

     

View Featured Ducky Payloads and Leaderboard
Get your payload in front of thousands. Enter to win over $2,000 in prizes in the Hak5 Payload Awards!

                       

Table of contents

Shop

• NEW USB Rubber Ducky
• PayloadStudio Pro
• Shop All Hak5 Tools

Getting Started

• Build and Encode Payloads with PayloadStudio | QUICK START GUIDE | Your First Payload

Documentation / Learn More

• Documentation | Quick Reference Guide
• Advanced DuckyScript Online Course | Textbook

Community

Got Questions? Need some help? Reach out:

• Discord | Forums

Additional Links

Follow the creators

Korben's Socials

Darren's Socials

About the NEW USB Rubber Ducky

A "flash drive" that types keystroke injection payloads into unsuspecting devices at incredible speeds.

New USB Rubber Ducky (A+C, DuckyScript 3.0, 2022)

Computers trust humans. Humans use keyboards. Hence the universal spec — HID, or Human Interface Device.

A keyboard presents itself as a HID, and in turn it's inherently trusted as human by the computer.

The USB Rubber Ducky — which looks like an innocent flash drive to humans — takes advantage of this trust to deliver powerful payloads, injecting keystrokes at superhuman speeds.

Easily automate any task you can perform with a keyboard with an easy to learn language designed specifically for the USB Rubber Ducky.

About DuckyScript™

Legacy DuckyScript (1.0)

Hak5 introduced Keystroke Injection in 2010 with the USB Rubber Ducky™. This technique, developed by Hak5 founder Darren Kitchen, was his weapon of choice for automating mundane tasks at his IT job — fixing printers, network shares and the like. Today the USB Rubber Ducky is a hacker culture icon, synonymous with the keystroke injection technique it pioneered. It’s found its way into the hearts and toolkits of Cybersecurity and IT pros the world over — including many movies and TV shows! Core to its success is its simple language, DuckyScript™. Originally just three commands, it could be learned by anyone—regardless of experience—in minutes.

With the new USB Rubber Ducky in 2022, DuckyScript 3.0 has been introduced.

DuckyScript 3.0

DuckyScript 3.0 is a feature rich, structured programming language. It includes all of the previously available commands and features of the original DuckyScript.

(DuckyScript 3.0 is backwards compatible with DuckyScript 1.0; this means all your favorite DuckyScript 1.0 payloads are valid DuckyScript 3.0)

Additionally, DuckyScript 3.0 introduces control flow constructs, loops, functions, extensions. Plus, DuckyScript 3.0 includes many features specific to keystroke injection attack/automation, such as HID & Storage attack modes, OS Detection, Keystroke Reflection (Video + Whitepaper), jitter and randomization to name a few.

While many of the Hak5 Tools run various versions of DuckyScript; unlike the Bash Bunny, Key Croc and even the officially licenced DuckyScript compatible devices from O.MG - which use INTERPRETED versions of DuckyScript - the USB Rubber Ducky uses COMPILED inject.bin payloads.

Interpreted DuckyScript means the payload runs straight from source code (the code you write e.g. DELAY 1000).

Compiled DuckyScript means that there is both source code and an inject.bin generated from the source code. (DuckyScript 1.0 was "encoded" rather than "compiled" - references to either mean the same)

The files in this repository are the source code in the form of payload.txt files.

Learn DuckyScript directly from the creators

Learn Advanced DuckyScript directly from the creators and unlock creative potential for the USB Rubber Ducky. Covering all aspects of advanced DuckyScript and Keystroke Injection attacks, these practical lessons build on one another from the basics on up.

This online course includes 7 hours of video instruction covering 54 lessons, 40+ exercises to reinforce your knowledge, quizzes throughout as well as 8 projects to test your skills.

Build your payloads with PayloadStudio

Take your DuckyScript™ payloads to the next level with this full-featured, web-based (entirely client side) development environment.

Payload studio features all of the conveniences of a modern IDE, right from your browser. From syntax highlighting and auto-completion to live error-checking and repo synchronization - building payloads for Hak5 hotplug tools has never been easier!

Supports your favorite Hak5 gear - USB Rubber Ducky, Bash Bunny, Key Croc, Shark Jack, Packet Squirrel & LAN Turtle!


Become a PayloadStudio Pro and Unleash your hacking creativity!
OR
Try Community Edition FREE


Payload Studio Themes Preview GIF


Payload Studio Autocomplete Preview GIF

DuckyScript Ecosystem

Languages

Compiling payloads for the correct language / keyboard layout has never been easier:

Open PayloadStudio > Settings > Compiler Settings

PayloadStudio includes all the languages provided in this repo built-in for your convenience.

PayloadStudio Pro has a dedicated language editor specifically for editing and building language files!

The default language is US (languages/us.json)

Extensions

Payload Studio Extensions Preview GIF

As the payload library continues to grow, so too will the DuckyScript 3.0 language. To that end, the extensions feature of the language and editor facilitate the continued growth of the language. Extensions are blocks of reusable code which may be implemented in any payload. Think of them as snippets, or building blocks, upon which your next payload may benefit. While Hak5 developers cannot envision all possible use cases for the USB Rubber Ducky, the DuckyScript language has been architected in such a way so that the community as a whole may gain new features and abilities with each contributed extension.

Extensions (beyond some first party examples) are currently reserved for collections of helper functions (+ required variables, defines, and configuration options) required to make a complex task simple - abstracting very complex problems down into one or a few calls for the ease of use to others (example: the translate extension).

To add an extension to your payload, simply start typing the name of the desired extension in your payload from within PayloadStudio then select it from the auto-complete drop down. Alternatively the full library can be found from within the Extensions folder of this repo.

Read more here

Contributing

View Featured Payloads and Leaderboard

Please adhere to the following best practices and style guides when submitting a payload.

Once you have developed your payload, you are encouraged to contribute to this repository by submitting a Pull Request. Reviewed and Approved pull requests will add your payload to this repository, where they may be publically available.

Please include all resources required for the payload to run. If needed, provide a README.md in the root of your payload's directory to explain things such as intended use, required configurations, or anything that will not easily fit in the comments of the payload.txt itself. Please make sure that your payload is tested, and free of errors. If your payload contains (or is based off of) the work of other's please make sure to cite their work giving proper credit.

Purely Destructive payloads will not be accepted. No, it's not "just a prank".

Subject to change. Please ensure any submissions meet the latest version of these standards before submitting a Pull Request.

Naming Conventions

Please give your payload a unique, descriptive and appropriate name. Do not use spaces in payload, directory or file names. Each payload should be submit into its own directory, with - or _ used in place of spaces, to one of the categories such as exfiltration, phishing, remote_access or recon. Do not create your own category.

Staged Payloads

"Staged payloads" are payloads that download code from some resource external to the payload.txt.

While staging code used in payloads is often useful and appropriate, using this (or another) github repository as the means of deploying those stages is not. This repository is not a CDN for deployment on target systems.

Staged code should be copied to and hosted on an appropriate server for doing so by the end user - Github and this repository are simply resources for sharing code among developers and users. See: GitHub acceptable use policies

Additionally, any source code that is intended to be staged (by the end user on the appropriate infrastructure) should be included in any payload submissions either in the comments of the payload itself or as a seperate file. Links to staged code are unacceptable; not only for the reasons listed above but also for version control and user safety reasons. Arbitrary code hidden behind some pre-defined external resource via URL in a payload could be replaced at any point in the future unbeknownst to the user -- potentially turning a harmless payload into something dangerous.

Including URLs

URLs used for retrieving staged code should refer exclusively to example.com using DEFINE in any payload submissions see Payload Configuration section below.

Staged Example

Example scenario: your payload downloads a script and the executes it on a target machine.

• Include the script in the directory with your payload
• Provide instructions for the user to move the script to the appropriate hosting service.
• Provide a DEFINE with the placeholder example.com for the user to easily configure once they have hosted the script

Simple Example of this style of payload

Payload Configuration

Be sure to take the following into careful consideration to ensure your payload is easily tested, used and maintained. In many cases, payloads will require some level of configuration by the end payload user.

• Abstract configuration(s) for ease of use. Use DEFINE where possible. Best practice is to use labels that start with # for easy identification throughout your payload.
• Remember to use PLACEHOLDERS for configurable portions of your payload - do not share your personal URLs, API keys, Passphrases, etc...
• URLs to staged payloads SHOULD NOT BE INCLUDED. URLs should be replaced by example.com. Provide instructions on how to specific resources should be hosted on the appropriate infrastructure.
• Make note of both REQUIRED and OPTIONAL configuration(s) in your payload using comments at the top of your payload or "inline" where applicable

Example: 
	BEGINNING OF PAYLOAD 
	... Payload Documentation... 

	REM CONFIGURATION
	REM REQUIRED - Provide URL used for Example
	DEFINE #MY_TARGET_URL example.com

	REM OPTIONAL - How long until payload starts; default 5s
	DEFINE #BOOT_DELAY 5000

	DELAY #BOOT_DELAY
	...
	STRING #MY_TARGET_URL
	...

Payload Documentation

Payloads should begin with REM comments specifying the title of the payload, the author, the target, and a brief description.

Example:
	BEGINNING OF PAYLOAD

	REM Title: Example Payload
	REM Author: Korben Dallas
	REM Description: Opens hidden powershell and
	REM Target: Windows 10
	REM Props: Hak5, Darren Kitchen, Korben
	REM Version: 1.0
	REM Category: General

Legal

Payloads from this repository are provided for educational purposes only. Hak5 gear is intended for authorized auditing and security analysis purposes only where permitted subject to local and international laws where applicable. Users are solely responsible for compliance with all laws of their locality. Hak5 LLC and affiliates claim no responsibility for unauthorized or unlawful use.

USB Rubber Ducky and DuckyScript are the trademarks of Hak5 LLC. Copyright © 2010 Hak5 LLC. All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means without prior written permission from the copyright owner. USB Rubber Ducky and DuckyScript are subject to the Hak5 license agreement (https://hak5.org/license) DuckyScript is the intellectual property of Hak5 LLC for the sole benefit of Hak5 LLC and its licensees. To inquire about obtaining a license to use this material in your own project, contact us. Please report counterfeits and brand abuse to [email protected]. This material is for education, authorized auditing and analysis purposes where permitted subject to local and international laws. Users are solely responsible for compliance. Hak5 LLC claims no responsibility for unauthorized or unlawful use. Hak5 LLC products and technology are only available to BIS recognized license exception ENC favorable treatment countries pursuant to US 15 CFR Supplement No 3 to Part 740.

See also:

Hak5 Software License Agreement

Terms of Service

Disclaimer

As with any script, you are advised to proceed with caution.

Generally, payloads may execute commands on your device. As such, it is possible for a payload to damage your device. Payloads from this repository are provided AS-IS without warranty. While Hak5 makes a best effort to review payloads, there are no guarantees as to their effectiveness.