sleep.taint
Class TaintUtils

java.lang.Object
  sleep.taint.TaintUtils

public class TaintUtils
extends java.lang.Object

Sleep supports a mode where variables received from external sources are considered tainted. This is a security mechanism to help educate scripters when they may be using tainted data within dangerous operations.

Terminology used here comes from Run-time taint support proposal by Wietse Venema posted to the PHP internals mailing list.

Sleep's implementation of taint is designed to have little to no runtime impact when turned off. When enabled taint mode wraps operations within the Sleep interpreter with taint wrappers. These wrappers check if any of the arguments on the current "frame" are tainted. If the answer is yes then the original operation is executed as normal and the return value is tainted.

Wrapped operations include operations and function calls. Parsed literals are treated as a special case.

Sleep has 4 categories of functions and their relation to tainted values:

• Sensitive - functions that are not allowed to receive a tainted input. Any attempt to send tainted input will immediately throw a runtime exception. Sleep functions in this category are responsible for making themselves known. The mechanism for this is described below.
• Permeable - functions or primitives that return a tainted result only when their input is tainted. By default all Sleep functions fall into this category.
• Tainters - functions that always return tainted results. These functions are expected to self identify as well.
• Sanitizers - functions that always return untainted results.

The taint mechanism depends on bridge writers and application developers to flag their Sleep extensions into the appropriate category. With this in mind Sleep tries to make this process as easy and transparent as possible.

   public void scriptLoaded(ScriptInstance si)
   {
      // install &foo as a Tainter function.
      si.getScriptEnvironment().getEnvironment().put("&foo", TaintUtils.Tainter(this));

      // install &bar as a Sanitizer function.
      si.getScriptEnvironment().getEnvironment().put("&bar", TaintUtils.Sanitizer(this));

      // install &dbquery as a Sensitive function.
      si.getScriptEnvironment().getEnvironment().put("&dbquery", TaintUtils.Sensitive(this));
   }

The TaintUtils class contains static methods that accept different Sleep bridges as parameters. They return wrapped versions of these bridges if tainting is enabled. If tainting is disabled these functions merely return the original bridges that were passed in. If you're writing a bridge you merely need to identify which of your functions are permeable or tainters and wrap them using one static call listed here.

Constructor Summary

TaintUtils()

Method Summary

static java.lang.String	checkArguments(java.util.Stack arguments) checks the specified argument stack for tainted values.
static boolean	isTainted(Scalar value) checks if a scalar is tainted
static boolean	isTaintMode() checks if Sleep is in taint mode or not.
static java.lang.Object	Sanitizer(java.lang.Object f) Wraps the specified bridge in such a way that all results are considered sanitized (untainted).
static java.lang.Object	Sensitive(java.lang.Object f) Wraps the specified bridge in such a way that all values on current frame are checked for tainted values.
static Scalar	taint(Scalar value) taints the specified scalar (if it is a value scalar only).
static java.util.Stack	taint(java.util.Stack values) taints all of the Scalar values in the specified stack.
static Scalar	taintAll(Scalar value) taints the specified scalar (bridge writers should call this on their scalars).
static java.lang.Object	Tainter(java.lang.Object f) Wraps the specified bridge in such a way that all results are considered tainted.
static Scalar	untaint(Scalar value) untaints the specified scalar.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TaintUtils

public TaintUtils()

Method Detail

isTaintMode

public static boolean isTaintMode()

checks if Sleep is in taint mode or not. This value does not change during runtime

taint

public static Scalar taint(Scalar value)

taints the specified scalar (if it is a value scalar only). returns the original container. If tainting is disabled the original bridge is returned.

taint

public static java.util.Stack taint(java.util.Stack values)

taints all of the Scalar values in the specified stack. More fun that a barrel full of monkeys. this function acts on the passed in stack

taintAll

public static Scalar taintAll(Scalar value)

taints the specified scalar (bridge writers should call this on their scalars). recurses on hashes and arrays. returns the original container. If tainting is disabled the original bridge is returned. not safe for circular data structures.

untaint

public static Scalar untaint(Scalar value)

untaints the specified scalar. returns the original container.

isTainted

public static boolean isTainted(Scalar value)

checks if a scalar is tainted

Sanitizer

public static java.lang.Object Sanitizer(java.lang.Object f)

Wraps the specified bridge in such a way that all results are considered sanitized (untainted). If tainting is disabled the original bridge is returned.

Tainter

public static java.lang.Object Tainter(java.lang.Object f)

Wraps the specified bridge in such a way that all results are considered tainted. If tainting is disabled the original bridge is returned.

Sensitive

public static java.lang.Object Sensitive(java.lang.Object f)

Wraps the specified bridge in such a way that all values on current frame are checked for tainted values. Any tainted values will result in an exception preventing the function from being called. If tainting is disabled then the original bridge is returned.

checkArguments

public static java.lang.String checkArguments(java.util.Stack arguments)

checks the specified argument stack for tainted values. If there are tainted values a comma separated string description is returned. Otherwise null is returned.