Chrysalide

Module pychrysalide.analysis.scan

Documentation

This module provide all the features useful for scanning binary contents.

Sub modules

pychrysalide.analysis.scan.patterns

Classes

ContentScanner
EngineBackend
RegisteredItem
ScanContext
ScanExpression
ScanNamespace
ScanOptions
TokenModifier

Methods

find_token_modifiers_for_name(name)

Provide the registered instance of a pattern modifier linked to a given name provided as a key string.

The returned instance is an object inherited from TokenModifier or None if no instance was found for the provided name.

register_token_modifier(inst)

This instance will be used as singleton and has to be a subclass of TokenModifier.

Class ContentScanner

A ContentScanner object provides support for rules processing against binary contents.

Instances can be created using one of the following constructors:

ContentScanner(text=str)
ContentScanner(filename=str)

Where text is a string for the rules definitions and filename an alternative string for a path pointing to a definition file.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.ContentScanner

Methods

analyze(self, options, content)

Run a scan against a binary content.

The content argument is a BinContent object pointing to data to analyze.

The method returns a ScanContext object tracking all the scan results.

convert_to_json(self, context)

Output a scan results as JSON data.

The context argument is a ScanContext instance provided by a previous call to self.analyze(). This context stores all the scan results.

The method returns JSON data as a string value, or None in case of failure.

convert_to_text(self, context)

Output a scan results as text.

The context argument is a ScanContext instance provided by a previous call to self.analyze(). This context stores all the scan results.

The method returns a string value, or None in case of failure.

Attributes

filename

Provide the access path to the source file of the rules' definition, or None if these rules have not been loaded from memory.

Class EngineBackend

An EngineBackend object is the root class of all scan algorithm looking for data patterns.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.patterns.EngineBackend

Known subclasses:

Class RegisteredItem

The RegisteredItem class defines the basics for evaluation items involved into content scanning.

Instances can be created using the following constructor:

RegisteredItem()

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.RegisteredItem

Known subclass: pychrysalide.analysis.scan.ScanNamespace

Methods

resolve(self, target, ctx=None, scope=None)

Resolve a name into a scan item.

The target name is the only mandatory parameter and has to point to only one item. The ctx argument points to an optional useful storage for resolution lookup, as a ScanContext instance. The args list defines an optional list of arguments, as ScanExpression instances, to use for building the resolved item. The final flag states if the scanning process is about to conclude or not.

The result is an object inheriting from RegisteredItem or None if the resolution operation failed.

Attributes

name

Name linked to the registered item.

The result should be a string, or None for the root namespace.

Class ScanContext

A ScanContext object tracks results of a run analysis process against binary contents.

Instances can be created using the following constructor:

ScanContext()

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.ScanContext

Methods

has_match_for_rule(self, name)

Provide the match status for a given scan rule.

The name argument points to the registered rule to query.

The method returns the scan final status as a boolean: True in case of match, False otherwise.

mark_scan_as_done(self)

Note that the analysis operations are finished.

Attributes

is_scan_done

Tell if the analysis operations are finished.

The result is a boolean: True if the scan is marked as done, False otherwise.

Class ScanExpression

A ScanExpression is an abstract object which defines an expression involved in data matching when running a scan.

Calls to the __init__ constructor of this abstract object expect the following arguments as keyword parameters:

state: initial state of reduction for the expression, as a ScanReductionState value.

The following methods have to be defined for new classes:

_cmp_rich().

The object can be compared using rich methods (like <= or !=).

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.ScanExpression

Implements: pychrysalide.glibext.ComparableItem

Methods

_cmp_rich(self, other, op)

Abstract method used to compare the expression against another one.

The second other instance is built from the same type as self. The op argument points to a RichCmpOperation mode describing the expected comparison.

The result is a boolean status or None if the comparison process is undefined.

Attributes

state

Current state of the expression, relative to the reduction process, as a ScanReductionState value.

Constants

ScanReductionState

State of a scanexpression during the reduction process.

0	= 0
1	= 1
2	= 2
3	= 3

Class ScanNamespace

ScanNamespace defines a group of properties and functions for a given scan theme.

Instances can be created using the following constructor:

ScanNamespace(name)

Where name is a string providing the name of the new namespace.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.RegisteredItem
           ╰── pychrysalide.analysis.scan.ScanNamespace

Methods

register_item(self, item)

Include an item into a namespace.

The item argument has to be a RegisteredItem instance.

The function returns a boolean value translating the operation status: True in case of success, False for a failure.

Class ScanOptions

The ScanOptions class stores all parameters used to tune a scanning process.

Instances can be created using the following constructor:

ScanOptions()

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.ScanOptions

Attributes

backend_for_data

Type of the selected scan algorithm.

print_json

Define if the process summary is output into a JSON format at the end of the scan or not.

print_stats

Control the output of final statistics afer a scan.

print_strings

Define if the matching patterns are printed with found offset at the end of the scan or not.

Class TokenModifier

An TokenModifier object is the root class of all modifiers for byte patterns.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.analysis.scan.patterns.TokenModifier

Known subclasses:

Methods

transform(self, data)

Transform data from a byte pattern for an incoming scan.

The data has to be provided as bytes.

The method returns a tuple of transformed data as bytes, or None in case of error.

Attributes

name

Call name for the modifier.

The result is a string.