
1 Overview

  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.

  PaD technology was originally designed to work in conjunction
  with WebJob and is currently maintained and distributed under
  that project.

  WebJob downloads a program or script from a remote WebJob server
  and executes it in one unified operation.  Any output produced
  by the program/script is packaged up and sent to a remote, possibly
  different, WebJob server.  WebJob is useful because it provides
  a mechanism for running known good programs on damaged or potentially
  compromised systems.  This makes it ideal for remote diagnostics,
  incident response, and evidence collection.  WebJob also provides
  a framework that is conducive to centralized management.  Therefore,
  it can support and help automate a large number of common
  administrative tasks and host-based monitoring scenarios such as
  periodic system checks, file updates, integrity monitoring,
  patch/package management, and so on.  WebJob is available at:

    http://webjob.sourceforge.net

1.1 Revision

  $Id: README,v 1.12 2008/05/19 14:45:44 mavrik Exp $

1.2 Table of Contents

  Section 1 .................... Overview
  Section 1.1 .................. Revision
  Section 1.2 .................. Table of Contents
  Section 2 .................... The Basics
  Section 3 .................... Highlights and Advantages
  Section 4 .................... Drawbacks and Issues
  Section 5 .................... Construction
  Section 6 .................... Requirements
  Section 7 .................... PaD and WebJob
  Section 8 .................... Acknowledgments
  Section 9 .................... License

2 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.

3 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.

4 Drawbacks and Issues

  PaD technology are 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.

5 Construction

  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

  or

    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

6 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.

7 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/dojob.sh

  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.

8 Acknowledgments

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

9 License

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

