Feature extraction API

Describes the interface to the objects that each feature must use to store the data.

FeatureCollector

class qbindiff.features.extractor.FeatureCollector[source]

Bases: object

The FeatureCollector is in charge of aggregate all the features values so that it can compute the vector embedding. FeatureExtractor objects receive the collector as argument of the visit functions, and have to register theirs own result to it. The feature score can either be a number or a dict.

add_dict_feature(key: str, value: dict[str, float]) None[source]

Add a feature value in the collector if the value is a dictionary of string to float.

Parameters:
  • key – name of the feature adding the value

  • value – Feature value to add

add_feature(key: str, value: float) None[source]

Add a feature value in the collector. Features are responsible to call this function to register a value with its own name.

Parameters:
  • key – name of the feature adding the value

  • value – float value to be added in the collector

feature_vector() None[source]

Show the feature vector associated to the node

full_keys() dict[str, set[str]][source]

Returns a dict in which keys are the keys of the features and values are the subkeys. If a Feature directly maps to a float value, the set will be empty.

e.g: {feature_key1: [], feature_key2: [], …, feature_keyN: [subkey1, …], …}

Returns:

dictionary mapping feature keys to their subkeys if any

to_sparse_vector(dtype: type, main_key_list: list[str]) csr_array[source]

Transform the collection to a sparse feature vector.

Parameters:
  • dtype – dtype of the sparse vector

  • main_key_list – A list of main keys that act like a filter: only those keys are considered when building the vector.

Returns:

FeatureExtractor

class qbindiff.features.extractor.FeatureExtractor(weight: float = 1.0)[source]

Bases: object

Base class that represent a feature extractor which sole contraints are to define a unique key and a function call that is to be called by the visitor.

Parameters:

weight – weight to apply to this feature

key: str = ''

feature name (short)

property weight: float

Weight applied to the feature

FunctionFeatureExtractor

class qbindiff.features.extractor.FunctionFeatureExtractor(weight: float = 1.0)[source]

Bases: FeatureExtractor

Function extractor feature. It inherits FeatureExtractor and defines the method visit_function() that has to be implemented by all its inheriting classes.

Parameters:

weight – weight to apply to this feature

key: str = ''

feature name (short)

visit_function(program: Program, function: Function, collector: FeatureCollector) None[source]

Function being called by the visitor when encountering a function in the program. Inheriting classes of the implement the feature extraction in this method.

Parameters:
  • program – Program being visited

  • function – Function object being visited

  • collector – collector in which to save the feature value.

property weight: float

Weight applied to the feature

BasicBlockFeatureExtractor

class qbindiff.features.extractor.BasicBlockFeatureExtractor(weight: float = 1.0)[source]

Bases: FeatureExtractor

Basic Block extractor feature. It inherits from FeatureExtractor and defines the method visit_basic_block() that has to be implemented by all its inheriting classes.

Parameters:

weight – weight to apply to this feature

key: str = ''

feature name (short)

visit_basic_block(program: Program, basicblock: BasicBlock, collector: FeatureCollector) None[source]

Function being called by the visitor when encountering a basic block in the program. Classes inheriting have to implement this method.

Parameters:
  • program – program being visited

  • basicblock – basic block being visited

  • collector – collector in which to save the feature value

property weight: float

Weight applied to the feature

InstructionFeatureExtractor

class qbindiff.features.extractor.InstructionFeatureExtractor(weight: float = 1.0)[source]

Bases: FeatureExtractor

Instruction extractor feature. It inherits from FeatureExtractor and defines the method visit_instruction() that has to be implemented by all its inheriting classes.

Parameters:

weight – weight to apply to this feature

key: str = ''

feature name (short)

visit_instruction(program: Program, instruction: Instruction, collector: FeatureCollector) None[source]

Function being called by the visitor when encountering an instruction in the program. Classes inheriting have to implement this method.

Parameters:
  • program – program being visited

  • instruction – instruction being visited

  • collector – collector in which to save the feature value

property weight: float

Weight applied to the feature

OperandFeatureExtractor

class qbindiff.features.extractor.OperandFeatureExtractor(weight: float = 1.0)[source]

Bases: FeatureExtractor

Operand extractor feature. It inherits from FeatureExtractor and defines the method visit_operand() that has to be implemented by all its inheriting classes.

Parameters:

weight – weight to apply to this feature

key: str = ''

feature name (short)

visit_operand(program: Program, operand: Operand, collector: FeatureCollector) None[source]

Function being called by the visitor when encountering an operand in the program. Classes inheriting have to implement this method.

Parameters:
  • program – program being visited

  • operand – operand being visited

  • collector – collector in which to save the feature value

property weight: float

Weight applied to the feature