pyplugins.hyper.shell module

Shell Coverage Plugin

This module implements the Shell Coverage (BBCov) plugin for the Penguin hypervisor environment. It tracks shell script execution coverage, traces, and environment variable usage by listening to hypercall events from the guest. The plugin writes coverage, trace, and environment information to CSV files for later analysis.

Usage

The plugin is loaded by the Penguin framework and responds to “igloo_shell” events.

Output Files

  • shell_cov.csv: Coverage data (filename, line number, pid)

  • shell_cov_trace.csv: Trace data (filename:lineno, contents)

  • shell_env.csv: Environment variable data (filename, lineno, pid, envs)

Arguments

  • outdir: Output directory for generated CSV files.

  • fs: Path to the tar archive containing the filesystem.

  • verbose: If set, enables debug logging.

Classes

  • BBCov: Main plugin class for handling shell coverage and environment logging.

class pyplugins.hyper.shell.BBCov(panda)[source]

Bases: Plugin

BBCov is a plugin that logs shell script coverage, traces, and environment variable usage.

Arguments: - outdir (str): Output directory for generated CSV files. - fs (str): Path to the tar archive containing the filesystem. - verbose (bool): Enables debug logging if True.

Parameters:

panda (Any)

igloo_shell_cb(cpu, hc_type, argptr, length)[source]

Callback for handling igloo_shell hypercall events.

Parameters: - cpu (Any): The CPU object. - hc_type (int): Hypercall type. - argptr (int): Pointer to arguments in guest memory. - length (int): Number of arguments.

Returns: None

Parameters:

  • cpu (Any)

  • hc_type (int)

  • argptr (int)

  • length (int)

Return type:

None

log_env_args(cpu, argv)[source]

Log environment variable information for a shell script line.

Parameters: - cpu (Any): The CPU object. - argv (list): List of argument pointers.

Returns: None

Parameters:

  • cpu (Any)

  • argv (list)

Return type:

None

log_line_no(cpu, argv)[source]

Log coverage information for a shell script line.

Parameters: - cpu (Any): The CPU object. - argv (list): List of argument pointers.

Returns: None

Parameters:

  • cpu (Any)

  • argv (list)

Return type:

None

try_read_int(cpu, ptr)[source]

Attempt to read an integer from guest memory.

Parameters: - cpu (Any): The CPU object. - ptr (int): Pointer to the integer in guest memory.

Returns: - Optional[int]: The integer read, or None if not available.

Parameters:

  • cpu (Any)

  • ptr (int)

Return type:

int | None

try_read_string(cpu, ptr)[source]

Attempt to read a string from guest memory.

Parameters: - cpu (Any): The CPU object. - ptr (int): Pointer to the string in guest memory.

Returns: - Optional[str]: The string read, or None if not available.

Parameters:

  • cpu (Any)

  • ptr (int)

Return type:

str | None