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() → dict[str, float | dict[str, float]][source]¶

Show the feature vector in a dictionary fashion.

Returns:: The feature vector in a dictionary fashion {key : FeatureValue}

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

get(key: str) → float | dict[str, float] | None[source]¶

Returns the FeatureValue associated to a feature key, None if the feature key doesn’t exists.

Parameters:: key – Name of the feature to retrieve
Returns:: The associated FeatureValue or None.

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:

The sparse feature vector for this collection of features

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

help_msg: str = ''¶: CLI help message

key: str = ''¶: feature name (short)

required_capabilities = 0¶: By default there are no required capabilities

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

help_msg: str = 'Function extractor feature. It inherits FeatureExtractor\n and defines the method :py:meth:`visit_function` that has\n to be implemented by all its inheriting classes.'¶: CLI help message

key: str = ''¶: feature name (short)

required_capabilities = 0¶: By default there are no required capabilities

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

help_msg: str = 'Basic Block extractor feature. It inherits from FeatureExtractor\n and defines the method :py:meth:`visit_basic_block` that has\n to be implemented by all its inheriting classes.'¶: CLI help message

key: str = ''¶: feature name (short)

required_capabilities = 0¶: By default there are no required capabilities

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

help_msg: str = 'Instruction extractor feature. It inherits from FeatureExtractor\n and defines the method :py:meth:`visit_instruction` that has to\n be implemented by all its inheriting classes.'¶: CLI help message

key: str = ''¶: feature name (short)

required_capabilities = 0¶: By default there are no required capabilities

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

help_msg: str = 'Operand extractor feature. It inherits from FeatureExtractor\n and defines the method :py:meth:`visit_operand` that has to be\n implemented by all its inheriting classes.'¶: CLI help message

key: str = ''¶: feature name (short)

required_capabilities = 0¶: By default there are no required capabilities

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