Visitors

Visitor abstract class

class qbindiff.visitor.Visitor

Bases: Generic[_Graph_T]

Abstract class representing interface that a visitor must implements to work with a Differ object.

abstract property feature_extractors: list[FeatureExtractor]

Returns the list of registered features extractor

abstract register_feature_extractor(fte: FeatureExtractor) → None

Register an instanciated feature extractor on the visitor.

Parameters:

fte – Feature extractor instance

visit(graph: _Graph_T, key_fun: Callable[[Any, int], Any] | None = None) → Iterator[tuple[Any, FeatureCollector]]

Function performing the visit on a Graph object by calling visit_item with a FeatureCollector meant to be filled.

Parameters:

• graph – the Graph to be visited.

• key_fun – a function that takes 2 input arguments, namely the current item and the current iteration number, and returns a unique key for that item. If not specified, the iteration number is used.

Returns:

An iterator over each node of the graph visited that contains the tuple (key_fun(item, i), FeatureCollector)

abstract visit_item(graph: _Graph_T, item: Any, collector: FeatureCollector) → None

Abstract method meant to perform the visit of the item. It receives an environment in parameter that is meant to be filled.

Parameters:

• graph – the graph that is being visited

• item – item to be visited

• collector – FeatureCollector to fill during the visit

NoVisitor

class qbindiff.visitor.NoVisitor

Bases: Visitor[GenericGraph]

Trivial visitor that doesn’t traverse the graph

property feature_extractors: list[FeatureExtractor]

Returns the list of registered features extractor

register_feature_extractor(fte: FeatureExtractor) → None

Register an instanciated feature extractor on the visitor.

Parameters:

fte – Feature extractor instance

visit(graph: GenericGraph, key_fun: Callable[[Any, int], Any] | None = None) → dict[Any, FeatureCollector]

Function performing the visit on a Graph object by calling visit_item with a FeatureCollector meant to be filled.

Parameters:

• graph – the Graph to be visited.

• key_fun – a function that takes 2 input arguments, namely the current item and the current iteration number, and returns a unique key for that item. If not specified, the iteration number is used.

Returns:

An iterator over each node of the graph visited that contains the tuple (key_fun(item, i), FeatureCollector)

abstract visit_item(graph: _Graph_T, item: Any, collector: FeatureCollector) → None

Abstract method meant to perform the visit of the item. It receives an environment in parameter that is meant to be filled.

Parameters:

• graph – the graph that is being visited

• item – item to be visited

• collector – FeatureCollector to fill during the visit

ProgramVisitor

class qbindiff.visitor.ProgramVisitor

Bases: Visitor[Program]

Class aiming at providing a generic program visitor which calls the different feature extractor on the appropriate items.

property feature_extractors

Returns the list of registered features extractor

register_basic_block_feature_callback(callback: Callable) → None

Feature callback at basic block granularity

Parameters:

callback – feature callback

register_feature_extractor(fte: FeatureExtractor) → None

Register an instanciated feature extractor on the visitor.

Parameters:

fte – Feature extractor instance

register_function_feature_callback(callback: Callable) → None

Feature callback at function granularity

Parameters:

callback – feature callback

register_instruction_feature_callback(callback: Callable) → None

Feature callback at function granularity

Parameters:

callback – feature callback

register_operand_feature_callback(callback: Callable) → None

Feature callback at function granularity

Parameters:

callback – feature callback

visit(graph: _Graph_T, key_fun: Callable[[Any, int], Any] | None = None) → Iterator[tuple[Any, FeatureCollector]]

Function performing the visit on a Graph object by calling visit_item with a FeatureCollector meant to be filled.

Parameters:

• graph – the Graph to be visited.

• key_fun – a function that takes 2 input arguments, namely the current item and the current iteration number, and returns a unique key for that item. If not specified, the iteration number is used.

Returns:

An iterator over each node of the graph visited that contains the tuple (key_fun(item, i), FeatureCollector)

visit_basic_block(program: Program, basic_block: BasicBlock, collector: FeatureCollector) → None

Visit the given basic block with the feature extractors registered beforehand.

Parameters:

• program – Program that is being visited

• basic_block – Basic Block to visit

• collector – FeatureCollector to fill

visit_function(program: Program, func: Function, collector: FeatureCollector) → None

Visit the given function with the feature extractors registered beforehand.

Parameters:

• program – Program that is being visited

• func – Function to visit

• collector – FeatureCollector to fill

visit_instruction(program: Program, instruction: Instruction, collector: FeatureCollector) → None

Visit the instruction with the feature extractor registered beforehand.

Parameters:

• program – Program that is being visited

• instruction – Instruction to visit

• collector – FeatureCollector to fill

visit_item(program: Program, item: Any, collector: FeatureCollector) → None

Visit a program item according to its type.

Parameters:

• graph – The program that is being visited

• item – Can be a Function, Instruction etc..

• collector – FeatureCollector to be filled

Returns:

None

visit_operand(program: Program, operand: Operand, collector: FeatureCollector) → None

Visit the given operand with the feature extractor registered beforehand.

Parameters:

• program – Program that is being visited

• operand – Operand

• collector – FeatureCollector to fill