penguin.utils module

penguin.utils

Utility functions and classes for the Penguin emulation environment.

This module provides helpers for file hashing, weighted lists, atomic counters, filesystem and kernel management, plugin analysis loading, and mitigation provider discovery.

class penguin.utils.AtomicCounter(initial=0)

Bases: object

Parameters:

initial (int)

decrement()

Atomically decrement the counter.

Returns:

The new value.

Return type:

int

get()

Get the current value atomically.

Returns:

The current value.

Return type:

int

increment()

Atomically increment the counter.

Returns:

The new value.

Return type:

int

penguin.utils.REAL_run_command_with_output(cmd, stdout_file, stderr_file)

Run a command and write output to files.

Parameters:

• cmd (list[str]) – Command as a list of arguments.

• stdout_file (str) – Path to stdout file.

• stderr_file (str) – Path to stderr file.

Returns:

Tuple of (error_msg, stderr) or (None, None) on success.

Return type:

tuple[Optional[str], Optional[str]]

class penguin.utils.WeightedItem(item, weight)

Bases: object

Parameters:

• item (Any)

• weight (float)

class penguin.utils.WeightedList

Bases: object

insert(weight, item)

Insert an item with a given weight.

Parameters:

• weight (float) – The weight for the item.

• item (Any) – The item to insert.

Return type:

None

pop()

Pop the item with the highest weight.

Returns:

Tuple of (weight, item) or (None, None) if empty.

Return type:

tuple[Optional[float], Optional[Any]]

penguin.utils.construct_empty_fs(path)

Construct an empty filesystem archive at the given path.

Parameters:

path (str) – Path to create the archive.

Return type:

None

penguin.utils.get_arch_dir(config)

Get the full architecture directory path.

Parameters:

config (dict[str, Any]) – Configuration dictionary.

Returns:

Directory path string.

Return type:

str

penguin.utils.get_arch_subdir(config)

Get the architecture subdirectory name for the given config.

Parameters:

config (dict[str, Any]) – Configuration dictionary.

Returns:

Architecture subdirectory string.

Return type:

str

penguin.utils.get_available_kernel_versions()

Scan /igloo_static/kernels and return a list of available kernel versions as tuples of integers, e.g., [(5, 15, 0), (6, 1, 55)]

Returns:

List of kernel version tuples.

Return type:

list[tuple[int, …]]

penguin.utils.get_driver_kmod_path(config)

Get the path to the driver kernel module.

Parameters:

config (dict[str, Any]) – Configuration dictionary.

Returns:

Path string.

Return type:

str

penguin.utils.get_file_hash(filepath)

Compute the MD5 hash of a file.

Parameters:

filepath (str) – Path to the file.

Returns:

Hex digest string.

Return type:

str

penguin.utils.get_kernel(conf, proj_dir)

Get the kernel path for the given configuration and project directory.

Parameters:

• conf (dict) – Configuration dictionary.

• proj_dir (str) – Project directory.

Returns:

Path to the kernel file.

Return type:

str

Raises:

ValueError – If kernel cannot be found or multiple kernels found.

penguin.utils.get_mitigation_providers(config)

Given a config, pull out all the enabled mitigation providers, load them and return a dict of {ANALYSIS_TYPE: analysis class object}

Skip plugins that are disabled in config. Raise an error if version of a plugin mismatches the config version.

Parameters:

config (dict) – Configuration dictionary.

Returns:

Dictionary mapping ANALYSIS_TYPE to analysis class object.

Return type:

dict[str, Any]

Raises:

ValueError – On version mismatch.

penguin.utils.get_mount_type(path)

Get the filesystem type of the mount at the given path.

Parameters:

path (str) – Path to check.

Returns:

Filesystem type string or None.

Return type:

str or None

penguin.utils.get_penguin_kernel_version(conf)

Extract kernel version tuple from conf[‘core’][‘kernel’].

Expected path format:

/igloo_static/kernels/<VERSION>/<kernel_filename>

<VERSION> may have a suffix (e.g., 6.1.55-custom); the suffix after the first ‘-’ is ignored. Only leading dot-separated numeric components are returned.

Parameters:

conf (dict) – Configuration dictionary.

Returns:

Tuple of integers representing the version, e.g., (6, 1, 55)

Return type:

tuple[int, …]

Raises:

ValueError – If the version cannot be determined.

penguin.utils.hash_image_inputs(proj_dir, conf)

Create a hash of all the inputs of the image creation process.

In the new build process this is just the preinit script and the modification time of the base filesystem (since we don’t control its contents).

We specifically do NOT include the busybox binary in this hash despite its potential effect on the image because we expect them to be fairly standard at least over the very small number of lines.

Parameters:

• proj_dir (str) – Project directory.

• conf (dict[str, Any]) – Configuration dictionary.

Returns:

Hex digest string.

Return type:

str

penguin.utils.read_output_files(stdout_file, stderr_file)

Read the contents of stdout and stderr files.

Parameters:

• stdout_file (str) – Path to stdout file.

• stderr_file (str) – Path to stderr file.

Returns:

Tuple of (stdout_data, stderr_data).

Return type:

tuple[str, str]

penguin.utils.run_command_with_output(cmd, ignore1, ignore2)

Run a command and capture stdout/stderr.

Parameters:

• cmd (list[str]) – Command as a list of arguments.

• ignore1 (Any) – Ignored.

• ignore2 (Any) – Ignored.

Returns:

Tuple of (None, None) on success, or (-1, “”, error_msg) on exception.

Return type:

tuple[Any, Any]