Package ghidra.pcode.emu.taint

Enum Class TaintPartsFactory

java.lang.Object
java.lang.Enum<TaintPartsFactory>
ghidra.pcode.emu.taint.TaintPartsFactory
All Implemented Interfaces:
AuxEmulatorPartsFactory<TaintVec>, Serializable, Comparable<TaintPartsFactory>, Constable
public enum TaintPartsFactory extends Enum<TaintPartsFactory> implements AuxEmulatorPartsFactory<TaintVec>
The parts factory for creating emulators with taint analysis

This is probably the most straightforward means of implementing a concrete-plus-auxiliary emulator in Ghidra. For our case, the auxiliary piece is the TaintVec. Ideally, the auxiliary piece implements the analog of a byte array, so that each byte in the concrete piece corresponds to an element in the abstract piece. We've done that here by letting each taint set in the vector be the taint on the corresponding byte. Each part we implement must adhere to that rule. For an overview of the parts of a p-code emulator, see PcodeEmulator.

As recommended by the documentation, we've implemented the factory as a singleton. As presented in the source, we'll visit each component in this order:

  • Enum Constant Details

    • INSTANCE

      public static final TaintPartsFactory INSTANCE
      This singleton factory instance

  • Method Details

    • values

      public static TaintPartsFactory[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static TaintPartsFactory valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • getArithmetic

      public PcodeArithmetic<TaintVec> getArithmetic(Language language)
      Get the arithmetic for the emulator given a target language

      Here we simply return the arithmetic for taint vectors for the emulator's language.

      Specified by:
      getArithmetic in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      language - the language
      Returns:
      the arithmetic

    • createSharedUseropLibrary

      public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createSharedUseropLibrary(AuxPcodeEmulator<TaintVec> emulator)
      Create the userop library for the emulator (used by all threads)

      We introduce two userops for tainting variables. Aside from initializing a trace (assuming a trace-integrated emulator), or writing directly to the state in the script, this library will allow clients to quickly initialize taints in the machine. Furthermore, this can permit the placement of taints in intermediate states of the machine during its execution. We construct and return the library here.

      Specified by:
      createSharedUseropLibrary in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      Returns:
      the userop library

    • createLocalUseropStub

      public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalUseropStub(AuxPcodeEmulator<TaintVec> emulator)
      Create a stub userop library for the emulator's threads

      We have no thread-specific userops to add, which means we also have no need for stubs, so here we just return the empty library.

      Specified by:
      createLocalUseropStub in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      Returns:
      the library of stubs

    • createLocalUseropLibrary

      public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalUseropLibrary(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)
      Create a userop library for a given thread

      We have no thread-specific userops to add, so here we just return the empty library.

      Specified by:
      createLocalUseropLibrary in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      thread - the thread
      Returns:
      the userop library

    • createExecutor

      public DefaultPcodeThread.PcodeThreadExecutor<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createExecutor(AuxPcodeEmulator<TaintVec> emulator, DefaultPcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)
      Create an executor for the given thread

      This allows the implementor to override or intercept the logic for individual p-code operations that would not otherwise be possible in the arithmetic, e.g., to print diagnostics on a conditional branch.

      We'd like to instrument conditional branches to check for taint, so we'll need a custom executor. We construct it here.

      Specified by:
      createExecutor in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      thread - the thread
      Returns:
      the executor

    • createSharedState

      public PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createSharedState(AuxPcodeEmulator<TaintVec> emulator, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)
      Create the shared (memory) state of a new emulator

      This is usually composed of pieces using PairedPcodeExecutorStatePiece, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

      To track what variables in the machine state are tainted, we need a taint state. We construct the part for the machine's memory here.

      Specified by:
      createSharedState in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      concrete - the concrete piece
      cb - callbacks to receive emulation events
      Returns:
      the composed state

    • createLocalState

      public PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalState(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)
      Create the local (register) state of a new emulator

      This is usually composed of pieces using PairedPcodeExecutorStatePiece, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

      To track what variables in the machine state are tainted, we need a taint state. We construct the part for a thread's registers and temporary (unique) variables here.

      Specified by:
      createLocalState in interface AuxEmulatorPartsFactory<TaintVec>
      Parameters:
      emulator - the emulator
      thread - the thread
      concrete - the concrete piece
      cb - callbacks to receive emulation events
      Returns:
      the composed state