analysis.plugin.plugin

exception analysis.plugin.plugin.AnalysisFailedError

Bases: Exception

class analysis.plugin.plugin.AnalysisPluginV0(metadata)

Bases: object

An abstract class that all analysis plugins must inherit from.

Analysis plugins should not depend on FACT_core code where they mustn’t.

Parameters:

metadata (MetaData) –

class MetaData(*args, **kwargs)

Bases: BaseModel

A class containing all metadata that describes the plugin

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

Schema: Type
dependencies: List

A list of all plugins that this plugin depends on

description: str

The plugins description.

mime_blacklist: list

List of mimetypes that should not be processed

mime_whitelist: list

List of mimetypes that should be processed

name: str

Name of the plugin

system_version: Optional[str] = None

The version of the backing analysis system. E.g. for yara plugins this would be the yara version.

timeout: int = 300

The analysis in not expected to take longer than timeout seconds on any given file and will be aborted if the timeout is reached.

version: semver.Version

The version of the plugin. It MUST be a semver version. Here is a quick summary how semver relates to plugins. * MAJOR: The plugin schema changed. * MINOR: The schema didn’t change but might contain more data. * PATCH: A bug was fixed e.g. a crash on some files.

Note that any version change leads to rescheduling the analysis. But backwards compatible results will still be shown in the frontend.

Schema = ~Schema
abstract analyze(file_handle, virtual_file_path, analyses)

Analyze a file. May return None if nothing was found.

Parameters:

  • file_handle (io.FileIO) – io.FileIO instance of the file to be analyzed

  • virtual_file_path (dict) – The virtual file paths, see FileObject

  • analyses (dict[str, pydantic.BaseModel]) – A dictionary of dependent analysis

Returns:

The analysis if anything was found.

Return type:

Optional[Schema]

final get_analysis(file_handle, virtual_file_path, analyses)
Parameters:

  • file_handle (io.FileIO) –

  • virtual_file_path (dict) –

  • analyses (dict[str, dict]) –

Return type:

dict

get_tags(result, summary)

Returns a list of tags to be added to the firmware.

Parameters:

  • result (Schema) – The result of the analysis as returned by analyze().

  • summary (list[str]) – The summary of the analysis as returned by summarize().

Returns:

A list of tags.

Return type:

list[Tag]

summarize(result)

The summary is an optional list of categories in which the result can be grouped. In the FACT_core frontend if you view the analysis of a container the summary is used to group files included in it.

Some examples of summaries are:

  • ["BusyBox 1.29.3", "Linux Kernel 4.9.250", "SQLite 3.8.11.1"] (From the software_components plugin)

  • ["application/zip", "text/plain"] (From the file_type plugin)

Will only be called if analyze did not return None.

Parameters:

result (Schema) – The analysis as returned by analyze()

Return type:

list[str]

class analysis.plugin.plugin.Tag(*args, **kwargs)

Bases: BaseModel

A dataclass for tags that is more convenient than dictionaries. The structure of the dict is defined in the docs for objects.FileObject.analysis_tags.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

Any

color: str

The color of the tag See helperFunctions.tag.TagColor.

name: str

The name of the tag.

propagate: bool = False

Whether or not the tag should be shown in parent files.

value: str

Additional information In FACT_core this is shown as tooltip