polytracker.taint_dag

taint_dag classes

TDBitmapSection

class polytracker.taint_dag.TDBitmapSection(mem, hdr)

Bases: object

Represents a bitmap section encoded by BitmapSectionBase.

The only configuration currently supported is to have the BucketType template parameter of BitmapSectionBase as uint64_t. It also requires the endianess to not change as the implementation does not handle endianess in any specific way.

__init__(mem, hdr)

enumerate_set_bits()

Enumerates all bits that are set

The index of each bit that is set will be yielded.

TDControlFlowLogSection

class polytracker.taint_dag.TDControlFlowLogSection(mem, hdr)

Bases: object

TDAG Control flow log section

Interprets the control flow log section in a TDAG file. Enables enumeration/random access of items

ENTER_FUNCTION = 0

LEAVE_FUNCTION = 1

TAINTED_CONTROL_FLOW = 2

__init__(mem, hdr)

function_id_mapping(id_to_name_array): This method stores an array used to translate from function id to symbolic names

TDEnterFunctionEvent

class polytracker.taint_dag.TDEnterFunctionEvent(callstack)

Bases: object

Emitted whenever execution enters a function. The callstack member is the callstack right before entering the function, having the function just entered as the last member of the callstack.

__init__(callstack): Callstack after entering function

TDEvent

class polytracker.taint_dag.TDEvent

Bases: Structure

class Kind(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ENTRY = 0

EXIT = 1

classmethod __contains__(value)

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members.

classmethod __getitem__(name): Return the member matching name.

classmethod __iter__(): Return members in definition order.

classmethod __len__(): Return the number of members (no aliases)

__init__(*args, **kwargs)

fnidx: Structure/Union member

kind: Structure/Union member

TDEventsSection

class polytracker.taint_dag.TDEventsSection(mem, hdr)

Bases: object

__init__(mem, hdr)

TDFDHeader

class polytracker.taint_dag.TDFDHeader

Bases: Structure

Python representation of the SourceEntry from taint_source.h

__init__(*args, **kwargs)

fd: Structure/Union member

invalid_fd()

invalid_size()

name_offset: Structure/Union member

size: Structure/Union member

TDFile

class polytracker.taint_dag.TDFile(file: BinaryIO)

Bases: object

__init__(file: BinaryIO) → None

decode_node(label: int) → TDNode

property events: Iterator[TDEvent]

input_labels() → Iterator[int]: Enumerates all taint labels that are input labels (source taint)

property label_count

property nodes: Iterator[TDNode]

read_event(offset: int) → TDEvent

read_fd_headers() → Iterator[Tuple[Path, TDFDHeader]]

read_fn_headers() → Iterator[Tuple[str, TDFnHeader]]

read_node(label: int) → int

property sinks: Iterator[TDSink]

TDFileMeta

class polytracker.taint_dag.TDFileMeta

Bases: Structure

TDAG File metadata.

File header describing the overall layout of the TDAG file. Corresponds to OutputFile::FileMeta in outputfile.h

__init__(*args, **kwargs)

magic: Structure/Union member

section_count: Structure/Union member

tdag: Structure/Union member

TDFnHeader

class polytracker.taint_dag.TDFnHeader

Bases: Structure

__init__(*args, **kwargs)

name_offset: Structure/Union member

TDFunctionsSection

class polytracker.taint_dag.TDFunctionsSection(mem, hdr)

Bases: object

__init__(mem, hdr)

TDInfo

class polytracker.taint_dag.TDInfo(argument_parser: ArgumentParser)

Bases: Command

__init__(argument_parser: ArgumentParser)

extension_types: List[Type[CommandExtension]] | None = None: An auto-populated list of eny extensions to this command.

extensions: List[CommandExtension]

property full_name: str

help: str = 'print trace file information': Help string for this command.

name: str = 'info': The name of this plugin.

parent: 'Plugin' | None: The parent of this plugin, if it is a sub-plugin.

parent_parsers: Tuple[ArgumentParser, ...] = (): An optional sequence of parent argument parsers from which to parse options.

run(args)

Callback for when the command is run.

Parameters:: args – The result of parsing the commandline arguments set up by Command.__init_arguments__().

subcommand_types: List[Type[Subcommand]] | None = None: An auto-populated list of subcommands of this command.

subcommands: List[Subcommand]

subparser: Any | None = None: A subparser, auto-populated if subcommand_types is not None.

TDLabelSection

class polytracker.taint_dag.TDLabelSection(mem, hdr)

Bases: object

TDAG Labels section

Interprets the stored taint nodes section in a TDAG file. Corresponds to Labels in labels.h.

__init__(mem, hdr)

count()

read_raw(label)

TDLeaveFunctionEvent

class polytracker.taint_dag.TDLeaveFunctionEvent(callstack)

Bases: object

Emitted whenever execution leaves a function. The callstack member is the callstack right before leaving the function, having the function about to leave as the last member of the callstack.

__init__(callstack): Callstack before leaving function

TDNode

class polytracker.taint_dag.TDNode(affects_control_flow: bool = False)

Bases: object

__init__(affects_control_flow: bool = False)

TDProgramTrace

class polytracker.taint_dag.TDProgramTrace(file: BinaryIO)

Bases: ProgramTrace

__init__(file: BinaryIO) → None

access_sequence() → Iterator[TaintAccess]: Yields the taint accesses in this trace, in order.

property basic_blocks: Iterable[BasicBlock]: The static basic blocks operated on by the trace.

property cfg: DiGraph[BasicBlock]: The static control flow graph associated with this trace.

cfg_roots() → Iterable[BasicBlock]

property entrypoint: FunctionInvocation | None: Returns the entrypoint to this trace (i.e., its first FunctionInvocation, typically main).

file_offset(node: TaintForestNode) → ByteOffset: The file offset associated with a taint forest node

property function_cfg: DiGraph[Function]

function_trace() → Iterator[FunctionEntry]

Iterates over all of the FunctionEntry events in this trace.

This is equivalent to:

iter(event for event in self if isinstance(event, FunctionEntry))

property functions: Iterable[Function]: The static functions operated on by the trace.

get_event(uid: int) → TraceEvent: Gets a trace event by its ID.

get_function(name: str) → Function

Looks up a function by its name.

Raises:: KeyError – if a function of that name was not executed in the trace

has_event(uid: int) → bool: Returns whether an event with the given ID exists in this trace.

has_function(name: str) → bool: Returns whether a function of the given name was executed in this trace.

input_properties(source: Input) → InputProperties

property inputs: Iterator[Input]: The taint sources operated on in this trace.

inputs_affecting_control_flow() → Taints: Returns the set of byte offsets that affected control flow

is_cfg_connected() → bool: Calculates whether the trace’s control flow graph is connected.

static load(tdpath: str | Path) → TDProgramTrace: loads a trace from a .tdag file emitted by an instrumented binary

next_function_entry(after: FunctionEntry | None = None) → FunctionEntry | None: Returns the next function entry, or None if none exists

property num_accesses: int: The number of taint accesses in this trace.

num_basic_block_entries() → int: Returns the number of basic block entries in this trace.

num_function_calls() → int: Returns the number of function calls in this trace.

num_function_calls_that_touched_taint() → int

property output_taints: Iterator[TDTaintOutput]: Iterates over all of the outputs written in the trace

property outputs: Iterable[Input] | None: The taint syncs written to in this trace.

property taint_forest: TaintForest: The taint forest associated with this trace.

taints(nodes: Iterable[TaintForestNode]) → Taints

TDRangeNode

class polytracker.taint_dag.TDRangeNode(first: int, last: int, affects_control_flow: bool = False)

Bases: TDNode

__init__(first: int, last: int, affects_control_flow: bool = False)

TDSectionMeta

class polytracker.taint_dag.TDSectionMeta

Bases: Structure

TDAG Section metadata.

Section header describing a particular section in the TDAG file. Corresponds to OutputFile::SectionMeta in outputfile.h

__init__(*args, **kwargs)

align: Structure/Union member

offset: Structure/Union member

size: Structure/Union member

tag: Structure/Union member

TDSink

class polytracker.taint_dag.TDSink

Bases: Structure

Python representation of the SinkLogEntry from sink.h

__init__(*args, **kwargs)

fdidx: Structure/Union member

label: Structure/Union member

offset: Structure/Union member

TDSinkSection

class polytracker.taint_dag.TDSinkSection(mem, hdr)

Bases: object

TDAG Sinks section

Interprets the sink entries section in a TDAG file. Corresponds to TaintSinkBase in sink.h.

__init__(mem, hdr)

enumerate()

TDSourceIndexSection

class polytracker.taint_dag.TDSourceIndexSection(mem, hdr)

Bases: TDBitmapSection

Represents the source index section.

It is a bitmap of all labels that are source taints.

__init__(mem, hdr)

enumerate_set_bits()

Enumerates all bits that are set

The index of each bit that is set will be yielded.

TDSourceNode

class polytracker.taint_dag.TDSourceNode(idx: int, offset: int, affects_control_flow: bool = False)

Bases: TDNode

__init__(idx: int, offset: int, affects_control_flow: bool = False)

TDSourceSection

class polytracker.taint_dag.TDSourceSection(mem, hdr)

Bases: object

TDAG Taint Sources section.

Interprets the Taint Sources section in a TDAG file. Corresponds to Sources in sources.h.

__init__(mem, hdr)

enumerate()

TDStringSection

class polytracker.taint_dag.TDStringSection(mem, hdr)

Bases: object

TDAG String Table section

Interprets the String Table section in a TDAG file. Corresponds to StringTableBase in string_table.h.

__init__(mem, hdr)

read_string(offset)

TDTaintForest

class polytracker.taint_dag.TDTaintForest(trace: TDProgramTrace)

Bases: TaintForest

__init__(trace: TDProgramTrace) → None

create_node(label: int) → TDTaintForestNode

get_node(label: int, source: Input | None = None) → TDTaintForestNode

get_synth_node_label() → int

nodes() → Iterator[TDTaintForestNode]: Iterates over the nodes in order of decreasing label

to_graph() → DAG[TaintForestNode]

TDTaintForestNode

class polytracker.taint_dag.TDTaintForestNode(forest: TDTaintForest, label: int, source: Input | None, affected_control_flow: bool = False, parent_labels: Tuple[int, int] | None = None)

Bases: TaintForestNode

__init__(forest: TDTaintForest, label: int, source: Input | None, affected_control_flow: bool = False, parent_labels: Tuple[int, int] | None = None)

is_canonical() → bool

property parent_labels: Tuple[int, int] | None

property parent_one: TDTaintForestNode | None

property parent_two: TDTaintForestNode | None

TDTaintOutput

class polytracker.taint_dag.TDTaintOutput(source: Input, output_offset: int, label: int)

Bases: TaintOutput

__init__(source: Input, output_offset: int, label: int)

Parameters:

output_offset – offset within the output file
label – The taint label of the output

taints() → Taints

TDTaintedControlFlowEvent

class polytracker.taint_dag.TDTaintedControlFlowEvent(callstack, label)

Bases: object

Emitted whenever a control flow change is influenced by tainted data. The label that influenced the control flow is available in the label member. Current callstack (including the function the control flow happened in) is available in the callstack member.

__init__(callstack, label)

TDUnionNode

class polytracker.taint_dag.TDUnionNode(left: int, right: int, affects_control_flow: bool = False)

Bases: TDNode

__init__(left: int, right: int, affects_control_flow: bool = False)

TDUntaintedNode

class polytracker.taint_dag.TDUntaintedNode

Bases: TDNode

__init__()