Packet Squirrel payloads: a community library for Hak5's pocket network device

What the repository actually is

The repository is the payload library for the Packet Squirrel by Hak5, and the readme describes its purpose plainly: this repository contains payloads and extensions for the Hak5 Packet Squirrel and the Hak5 Packet Squirrel Mark II, community developed payloads are listed, and developers are encouraged to create pull requests to make changes to or submit new payloads.

The interesting property is that the payloads are the source code. The files in the repository are the source code for your payloads and run directly on the device with no compilation required, so you place your payload.txt in the appropriate directory and you are ready to go. There is no build step, no cross-compiler, no toolchain, and nothing to install on the host beyond whatever you use to edit a text file.

That makes the repository a different kind of artefact from most of the projects on this site. A payload library is a set of scripts that run somewhere other than your workstation, on a device with its own operating system, its own CPU and its own idea of what filesystem it has. The consequence for a reader is that the interesting question is not what the code does but where it runs and what it assumes about the environment.

The repository tree is two directories and a readme: legacy-mk1/ holds the payloads for the original hardware, payloads/ holds the ones for the Mark II, and README.md sits at the top.

legacy-mk1/
payloads/
README.md

The primary language is recorded as Shell, which is consistent with the payload set mixing DuckyScript with Bash and Python, and the topic list names duckyscript, ethernet, networking, pentesting and security-tools, which describes both the payloads and the device they run on.

Two hardware revisions, and why the split matters

The readme spends its first real section on a distinction that is easy to miss and expensive to get wrong.

There are currently two versions of the Packet Squirrel. The original Packet Squirrel can be identified by the micro-usb power port, while the Packet Squirrel Mark II can be identified by the USB-C power port, and the instruction that follows is: please make sure you select payloads for the device you have.

The reason for the split is not cosmetic. The Mark II expands the DuckyScript for Packet Squirrel commands and adds many new commands and features, and in general payloads from the original Packet Squirrel can be adapted to run on the Mark II by adopting the new commands, with the Mark II payload documentation linked for the details. Payloads for the original Packet Squirrel can be found in the legacy-mk1/ directory, and the Mark II payloads can be found in the payloads/ directory.

So the compatibility story is a one-way street with a caveat. Old payloads remain available and functional on the original hardware in the legacy-mk1/ directory, so nothing is lost, but moving an old payload forward means editing it, because the command set underneath has changed.

That is the practical thing to check before anything else: whether a script you are copying relies on a command the Mark II renamed, changed the arguments of, or replaced. A payload that runs on the original hardware can fail silently in the sense that it starts and does something different, which for a network device is worth a careful look.

The revision split also means the two directories are maintained by different needs. The legacy directory is effectively frozen in the way a compatibility branch is, while the Mark II directory grows as the hardware gains commands, and a reader looking at the repository has to know which of the two they are looking at before anything else makes sense.

DuckyScript, and what the payload language assumes

The payload language is DuckyScript, and the readme gives its history and its rules in a paragraph that is worth reading closely.

DuckyScript is the payload language of Hak5 gear. It originated on the Hak5 USB Rubber Ducky as a standalone language, and the Packet Squirrel uses DuckyScript commands to bring the ethos of easy-to-use actions to the payload language.

The syntax rule is simple and absolute: DuckyScript commands are always in all capital letters to distinguish them from other system or script language commands. Typically they take a small number of options, or sometimes no options at all.

The composition rule is what makes it usable for network work. Payloads can be constructed of DuckyScript commands alone, or combined with the power of bash scripting and system commands to create fully custom, advanced actions. The Mark II goes further still: use simplified DuckyScript for Packet Squirrel to create payloads, or use the full power of Bash script or Python 3 for complex payloads.

So there are three levels of payload on this device, and choosing the level is a design decision rather than a limitation. A DuckyScript-only payload is short, readable and portable to other Hak5 hardware. A payload that mixes DuckyScript with Bash is where the network work happens, because the Bash side can use the ordinary tools. A Python 3 payload is where you write something with real logic.

The capitalisation rule is doing a real job here. Because the device runs three languages in one file, the parser needs a way to tell a DuckyScript command from a shell command from a Python line, and a rule that all DuckyScript verbs are uppercase is a convention that survives being mixed with two other languages, which is not true of most delimiters.

The development environment is documented too: edit payloads live in the web UI editor with syntax highlighting, over SSH, or build your payloads with Payload Studio, and the readme links to PayloadStudio as a web-based, entirely client side development environment.

What the device does, and what a payload can be aimed at

The hardware description is where the ethics of the library live, and it is worth reading in the project's own words.

The Packet Squirrel Mark II by Hak5 is described as a stealthy pocket-sized man-in-the-middle. It is an Ethernet multi-tool designed to give you covert remote access, painless packet captures and secure VPN connections with the flip of a switch, and the feature list adds packet capture, man-in-the-middle network manipulation, stream filtering and redirection, and remote VPN access.

Then there is the line about use: exfiltrate data or pentest from anywhere with Hak5 Cloud C2.

Put those together and the scope of the library is clear. The payloads run on hardware that sits between two devices on a network and can observe, alter or redirect the traffic passing through it. Some of that is unambiguously benign, because packet capture is how every network engineer learns what a network is actually doing, and a filtering or redirection payload is a way to test a firewall rule or to prove that a monitoring system sees what it claims to see. Some of it is only lawful in an authorised environment, and the device's own description as a covert man-in-the-middle says which side of that line most of the interesting payloads sit on.

That is not a reason to skip the repository, which is a public, community-contributed library published by the hardware vendor with a Discord, a forum and a Discord-based support channel. It is a reason to read what a payload does before you run it, and to have the authorisation conversation before the hardware does.

There is also a commercial layer around the library, and it is worth noting for anyone assessing the project. The readme points at the Hak5 shop for the Packet Squirrel, for PayloadStudio Pro and for the wider tool range, and at PayloadHub, which is described as a place to get your payload in front of thousands with a leaderboard and prize money in the Hak5 Payload Awards. So the payload library, the authoring tool and the device are three parts of one commercial ecosystem, and the open repository is the community-facing half of it.

Where the payload library is the wrong tool

The first limit is that it is not software you install. There is no library to add to a project, no API to call and no package to depend on, and if you are evaluating it as a software dependency then it does not qualify. The unit of use is a device on a network and a text file on it.

The second is the licensing question, and it is unresolved. The licence field for the repository is one that GitHub cannot classify, which means there is no recognised licence, and the readme does not state terms in prose. For a collection of scripts that people are invited to contribute to and copy between devices, that is a real gap. Somebody building a business on a payload library needs to know whether they may modify it, redistribute it and put it inside a product, and the repository does not answer that.

The third is the split between the two directories and what it costs. The legacy directory is a compatibility branch that will not be updated with new capabilities, so a payload that would be easy on the Mark II may need work on the original hardware, and the readme says as much. For a user who owns the older device, the library is largely a fixed set of scripts rather than a growing one.

The fourth is that the library is a community repository, and that cuts both ways. It means there are more payloads than a single author would have written, which is the reason to use it at all, and it means the quality bar is set by review rather than by authorship. The readme asks for pull requests and does not describe a review process, so the expectations on the maintainers should be set accordingly, and a payload from the community is code you should read rather than code you should trust.

And the fifth is the operational one. A payload that runs on the device runs with whatever privileges that device has, and a device that sits in the middle of a network and can manipulate traffic is a device that should be treated as sensitive equipment. The documentation does not discuss the operational hygiene around it, and for a tool whose capabilities include covert remote access, that is a gap a buyer should close themselves.

Editorial conclusion

The Packet Squirrel payload library is worth looking at if you own the hardware and work with network captures, because the payloads are plain text files that run on the device with no compilation step, because the repository splits them by hardware revision so a Mark II user does not have to guess which scripts will work, and because the community contribution route means the library grows with the tasks people actually face. It is the wrong tool if you want a software tool, and it is the wrong tool if you have no authorisation to touch the network you are pointing it at. Before you flash anything, check three things: which hardware revision you have, because the original Packet Squirrel is identified by its micro-usb power port and the Mark II by its USB-C port, and the payloads for the original live in legacy-mk1/ while the Mark II ones live in payloads/; that the licence is not declared, since the repository's licence field is one GitHub cannot classify and the terms are not stated in the documentation, which matters if you plan to reuse a payload in your own tooling; and that you understand the authorisation question, because the device is described as a stealthy pocket-sized man-in-the-middle and a tool of that kind is only lawful to point at networks you own or have permission to test.

Frequently asked questions

Official sources

1. hak5/packetsquirrel-payloads on GitHub
2. Issues
3. Project website
4. README