objects.firmware module

class objects.firmware.Firmware(**kwargs)

Bases: FileObject

Uploaded firmware image representation.

In FACT, we represent an uploaded firmware image as specialized FileObject with supplementary meta data. This class is the root of a virtual path tree with all extracted folders and files as branch- and leaf-instances of the FileObject class:

                          ┌────────────┐
                          │  Firmware  │
                          │(Root Image)│
                          └──────┬─────┘
                                 │
                 ┌───────────────┼───────────────┐
                 │               │               │
                 ▼               ▼               ▼
          ┌────────────┐  ┌────────────┐  ┌────────────┐
          │    /etc    │  │    /var    │  │    ...     │
          │(FileObject)│  │(FileObject)│  │(FileObject)│
          └──────┬─────┘  └──────┬─────┘  └────────────┘
                 │               │
       ┌─────────┴────┐       ┌──┼──┐
       │              │       │  │  │
       ▼              ▼       ▼  ▼  ▼
┌────────────┐ ┌────────────┐   ...
│   passwd   │ │    ...     │
│(FileObject)│ │(FileObject)│
└────────────┘ └────────────┘

For each uploaded firmware, FACT can hold meta data that associates the analyzed image with its corresponding embedded device. This meta data includes the…

device_class,
device vendor,
device_name,
firmware version,
firmware release_date, and
image-contained part.

Additionally, each Firmware can hold user-defined tags that may be used in advanced queries to categorize and filter all firmwares present in the database. It is important to understand that said tags are separately stored from the objects.file.FileObject.analysis_tags, which are propagated by analysis plugins.

device_class: str | None: Device class string identifier. Not all embedded appliances are the same: There are routers, IP cameras, entertainment systems, printers, and a plethora of other classes. # noqa: E501 FACT requires a user to categorize analyzed firmware images by this attribute. While this attribute is mandatory, it can be freely defined during upload.

device_name: str | None

Device name string identifier. Can be freely defined during upload.

This attribute is mandatory and shall never be None.

classmethod from_json(json, root_uid=None)

Parameters:

json (dict) –
root_uid (str | None) –

get_hid()

See objects.file.FileObject.get_hid().

Return type:: str

part: str

Specifies the parts of an embedded system that are contained in this firmware. While this meta data string can be freely defined during firmware upload, FACT provides a preset of frequently used values: complete, kernel, bootloader, and root-fs.

This attribute is optional. The firmware image is assumed to be complete if the assigned/default value is an empty string. # noqa: E501

release_date: str | None

Release date string of this firmware version in ISO 8601 YYYY-MM-DD format. # noqa: E501

This attribute is optional. The release date is assumed to be the start of UNIX epoch time (1970-01-01) if not specificed. # noqa: E501

set_binary(binary)

See objects.file.FileObject.set_binary().

Parameters:: binary (bytes) – binary data of the file object

set_part_name(part)

Setter for self.part_name.

Parameters:: part (str) – part identifier, defaults to complete if empty string is passed.

set_tag(tag)

Set a user-defined tag in the color gray.

Parameters:: tag (str) – Tag identifier

tags: dict[str, TagColor]

User-defined firmware tags for advanced grouping and filtering of firmware images, saved as {‘tag’: helperFunctions.tag.TagColor} dictionary. # noqa: E501 It is important to understand that these tags are separately stored from the objects.file.FileObject.analysis_tags, which are propagated by analysis plugins. # noqa: E501

This attribute is optional, the dict may be empty.

to_json(vfp_parent_filter=None)

Get a FileObject as JSON. vfp_parent_filter can be used to filter the entries with a UID whitelist.

Parameters:: vfp_parent_filter (set[str] | None) –
Return type:: dict

vendor: str | None

Device vendor string identifier.

This attribute is mandatory and shall never be None.

version: str | None

Firmware version string identifier. Can be freely defined during upload.

This attribute is mandatory and shall never be None.