The FTimes Project The HashDig Project The WebJob Project The PaD Project
Location: / Home / WebJob / Payload And Delivery

A Payload and Delivery (PaD) file is a self-extracting executable that can be packaged as either a script or a program. In addition to extracting their payload, PaD executables support flexible payload delivery. In other words, the user controls if, when, and how a given payload will be delivered. Within the PaD context, delivery refers to the act of running one or more commands to manipulate or otherwise make use of the extracted payload.

The Basics

PaD executables contain three basic components: extract/delivery logic, a delimiter, and the target payload.

When invoked without command-line arguments, a PaD executable will extract its payload to a file whose name is the basename of the executable. For example, payload.tgz.pad would be extracted to payload.tgz.

When invoked with command-line arguments, a PaD executable will first extract its payload. Then, it will proceed to deliver that payload by invoking the remaining arguments as a new command. For example, the command line shown below would extract payload.tgz.pad to a file named payload.tgz, and then, deliver the payload using gzip and tar. The %payload argument is a place holder. A PaD executable will replace all instances of this token with the actual payload filename prior to delivery.

  payload.tgz.pad gzip -dc %payload \| tar -C /tmp -xf -

Note how the '|' character is escaped. This ensures that all command-line arguments are passed to the PaD executable. As it turns out, this particular type of delivery would have worked regardless of whether or not the '|' character was escaped. That's because PaD logic does not write any diagnostic/error messages to stdout -- i.e. stdout is kept clean for delivery purposes.

Highlights and Advantages

PaD technology is particularly attractive for the following reasons:

  • Its extract/delivery logic is simple and easy to validate. This supports the position that the PaD mechanism, itself, is safe and reliable.
  • It supports binary payloads.
  • Payload delivery is flexible -- i.e. the user determines if, when, and how the payload will be delivered. This provides a mechanism for the user to include custom payload validation checks in-line with the delivery arguments.
  • It is well suited to on-the-fly construction. This makes it a good candidate for automated content delivery schemes.
  • Payload delivery is not bound to payload extraction -- i.e. one payload can be delivered many ways.
  • It allows you to turn regular files, such as SSH keys or configuration files, into PaD executables. These executables can then be used to drive programs that normally require such files as input.
Drawbacks and Issues

PaD technology is not for everyone:

  • It is general purpose and can, therefore, cut both ways. In other words, an attacker could use or cause you to use a PaD executable to infiltrate and execute malicious tools.
  • It lacks the ability validate payload integrity and has no inherent self-protection mechanisms.
  • It depends on delivery programs that exist on the target system. If you can't trust such programs, then extra precautions may need to be taken to verify that the delivery process went as expected.

To create a functional PaD executable, you need to combine the following components in their respective order: PaD logic, PaD delimiter, and target payload. PaD logic comes in two forms: script and binary. The PaD delimiter is simply the string, PAD_GUTS_DELIMITER, followed by a newline (i.e. '\n'). PaD logic uses this delimiter to determine the location of the embedded payload.

By convention, PaD filenames are constructed by appending '.pad' to the payload's filename. In fact, PaD logic will refuse to extract its payload unless this suffix is present.

The following example demonstrates how payload.tgz.pad can be constructed from payload.tgz. The newly constructed PaD file needs to be executable, so remember to check its permissions and make any necessary adjustments before invoking it.

  pad-make-binary --create payload.tgz > payload.tgz.pad


  pad-make-script --create payload.tgz > payload.tgz.pad

The pad-make-{binary|script} commands conveniently automate PaD construction. The binary form, however, can't create cross-platform PaD files. When you need that capability, use pad-join as it allows you to combine binary guts from the appropriate platform with the target payload. The following example demonstrates how payload.tgz.pad would be constructed from payload.tgz. Assume, for this example, that the binary guts are from Solaris and the the command is invoked under Linux. The result is a native Solaris binary.

  pad-join pad-binary-guts payload.tgz > payload.tgz.pad
PaD Requirements

Any delivery programs that you intend to use (e.g., gzip, tar, etc.) must exist on the target system a priori.

For PaD scripts to work properly, the following programs must exist on the target system: [, awk, basename, echo, expr, grep, head, rm, sed, sh, tail, and wc.

For PaD programs to work properly, they must contain binary guts that are native to the target system.

PaD and WebJob

PaD executables were designed to work in conjunction with WebJob. In particular, they extend the run time environment by allowing WebJob to, in effect, download it. Suppose you need a whole directory of tools to perform some task. One approach would be to tar up the directory and make it available to WebJob clients as a PaD executable. Since payload delivery is user-defined, it would be possible to unpack the tar ball (i.e. the environment) and execute a program or script within it. The following example shows how this might work.

  webjob -e -f webjob.cfg payload.tgz.pad tar -C /tmp -zxf %payload \&\& /tmp/payload/

This example assumes that unpacking payload.tgz will create a directory called payload.

Note: If you execute a PaD command from within a Windows batch file (i.e., .bat or .cmd), you'll need to escape the '%' in '%payload'. This is done by prefixing the string with an additional '%'. Thus, '%payload' becomes '%%payload' in your command.


The idea to use 'tail +${SKIP}' as the extraction mechanism comes from makeself-1.5.3 by Stéphane Peter.


All PaD documentation and code is distributed under same terms and conditions as WebJob.

Copyright 2000-2012 The WebJob Project, All Rights Reserved.
The FreeBSD Project SourceForge Logo KoreLogic, Inc.