DocumentationPayloadsCommunitySupport

Payload development basics

Begin at the beginning

Packet Squirrel payloads can be written directly on the Packet Squirrel in the syntax-highlighting web UI editor, in a terminal editor like vi or nano, online in the Hak5 Payload Studio, or on your computer in any standard text editor, such as Sublime, vscode, or even Notepad.

The Packet Squirrel Mark II directly supports payloads written in Bash shell or Python. Advanced payloads may leverage other languages, but will require installation of interpreters on a USB storage device.

Interpreters

The Packet Squirrel chooses how to run a payload based on the first line of the script which defines what type of payload it is.

The interpreter line is always #!/path/to/interpreter and must be present as the first line.

Bash payloads

Bash or shell script payloads begin with the bash interpreter:

#!/bin/bash

This header line (also called the “sha-bang” from “hash-bang”) tells the operating system how to interpret the text file: For the Packet Squirrel, we’re telling it to use the bash shell interpreter.

A common mistake is to use a different interpreter by accident. Forgetting to start your payload with a #!/bin/bash for instance, or using #!/bin/sh by mistake can cause the system to try to interpret your payload script differently. Some scripts may work with the simpler sh interpreter, but many will not!

The Bash shell

A shell is a command-line interface that allows users to interact with the operating system by executing commands. The shell acts as an intermediary between the user and the operating system, and is responsible for interpreting and executing user commands.

When a user enters a command into the shell, the shell parses the command and determines what action needs to be taken. The shell then initiates the required system calls to carry out the requested action.

The shell also provides various features and utilities to help users manage and manipulate their environment. For example, it provides the ability to define and use variables, create and execute scripts, and navigate the file system.

When you are logged into a system via the command line, chances are, you're interacting with one of several standard shells. On Windows it is typically the legacy command shell or the more modern Powershell. On Linux, it is typically the bash or dash shells, however dozens exist. On macOS, typically you are using the z shell, or zsh.

With the exception of the Windows command shell and Powershell, most modern shell environments operate extremely similarly, and often scripts written for one shell will operate fine on another. Unfortunately there are some situations where this is not always true, especially when using more advanced pattern matching and other scripting features.

The Packet Squirrel uses the bash shell: bash (the Bourne Again Shell) was derived from sh (the Bourne Shell). It was created in 1987 by Brian Fox for the GNU Project as a free software replacement for the Bourne shell (sh).

Bash incorporates many features of the original Bourne shell, as well as improvements and new features from other shells such as the C shell (csh) and the Korn shell (ksh). This includes features such as command-line editing, history, and job control, and critically for the Packet Squirrel, the ability to define functions and variables.

Over the years, Bash has become the default shell on most Linux distributions, and was the default on macOS until it was replaced by zsh in macOS Catalina. It is also available on other operating systems such as Windows, where it can be installed using the Windows Subsystem for Linux.

Bash has continued to evolve over time, with new features and improvements being added in each release. It is a powerful and flexible shell that is widely used in the Linux and Unix communities, both for interactive use and for writing scripts and automation tasks.

Comments

While meme jokes may say “never trust the comments”, in general commenting your payload is a good idea. Comments let you document your payload for others (or even your future self), explain configuration options, and annotate your payload.

Any content on a line starting with a # is treated as a comment.

# This line is a standard comment!


# The variable FOO controls something.
FOO="BAR"

The built-in payloads on the Packet Squirrel will use comments to explain how configuration variables are used and how certain operations are performed.

You’ll also see a collection of comments at the beginning of every payload: These form the payload information section, and are used by the web UI and the Payload Repository to give more information about the payload!

Payload information

Payloads can have optional information at the top of the file; these comments help the web UI display information about the payload, and helps other users if you contribute to the Payload Repository.

  • Title: A simple payload title. This should be descriptive and summarize the purpose of the payload.

  • Description: A longer description about the payload and what it does.

  • Author: Get credit for your efforts!

Example

# Title: Awesome Squirrel Payload
#
# Description: Do something awesome with the Packet Squirrel
# Author: Packet_Squirrel <packetsquirrel@xyz.abc>

By providing a title and description you make it easier to identify your payload, and the Packet Squirrel web UI will properly display information about each payload on your device.

Variables

Variables are used to store values or data that can be used later in the script.

We've already seen variables in use in the Configuring payloads section, where we use them to control how the payload executes. Variables are significantly more powerful, however.

There are different types of variables in bash:

  1. Environment variables: These variables are set by the shell and are available to all programs that run in the shell environment. Examples include $PATH, which contains a list of directories to search for executable files, and $HOME, which contains the user's home directory.

  2. User-defined variables: These variables are created by the user in the script and can be used to store any type of data. They are typically created using the syntax varname=value, where varname is the name of the variable and value is the value to be assigned to it. For example, name="John" creates a variable called name with the value "John".

  3. Positional parameters: These variables are used to store arguments passed to a script when it is executed. The first argument is stored in $1, the second argument in $2, and so on. For example, if a script is called with the command ./myscript.sh arg1 arg2, then $1 would contain "arg1" and $2 would contain "arg2". Packet Squirrel payloads are not executed with arguments, so the positional parameters will always be empty.

  4. Process and result variables: These variables are set automatically by the shell to reflect the behavior of recently executed processes. Among others, bash manages the interval variables $! which holds the process ID of the last backgrounded process, $? which holds the exit status of the last command, and $$ which holds the process ID of the currently running script itself. These allow scripts to execute background commands, retrieve the results of a command, and manage commands and functions run in the background.

Variables can be referenced in a script using the syntax $varname, where varname is the name of the variable. For example, echo $name would print the value of the variable "name" to the screen. Variables can also be used in calculations or as arguments to other commands. It's important to note that variable names are case-sensitive in bash.

Last updated