Package sleep.taint

Class 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

      Constructors 
      Constructor Description
      TaintUtils()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      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 java.util.Stack taint​(java.util.Stack values)
      taints all of the Scalar values in the specified stack.
      static Scalar taint​(Scalar value)
      taints the specified scalar (if it is a value scalar only).
      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.