pyplugins.interventions.pseudofiles module¶

Pseudofiles Plugin¶

This plugin creates, manages, and suggests new pseudofiles. It is configurable via the Penguin project config file.

Purpose¶

Registers all pseudofile models as hyperfiles.
Handles read, write, and ioctl commands issued to pseudofiles.
Monitors for access attempts to missing files and suggests adding them as pseudofiles.

Usage¶

Place pseudofile models in the Penguin project config.

Example¶

/dev/mydevice:

read:

model: zero

write:

model: discard

ioctl:

‘*’:: model: return_const val: 0

class pyplugins.interventions.pseudofiles.Pseudofiles[source]¶

Bases: Plugin

Pseudofiles Plugin¶

Creates and manages pseudofiles and guest interactions with them. Also suggests new paths to add to modeled pseudofiles.

Attributes¶

outdirstr: Output directory for logs.
proj_dirstr: Project directory, used to find host files.
confstr: Penguin project config.
verbosebool: If True, enable verbose logger output.
loggingstr: Determines which log output files will be generated. Can be ‘all’, ‘modeled’, ‘missing’, or ‘none’.

Behavior¶

Create hyperfile to replace or create a new file in the guest.
Subscribe to all interactions with that hyperfile, and use configuration models

for read, write, and ioctl commands.

centralized_log(path, event, event_details=None)[source]¶

Log potential pseudofile candidates.

Parameters¶

pathstr: File path.
eventstr: Event which triggered the file to be found as missing or interesting.
event_detailsAny: Additional context, defaults to None.

Returns¶

None

dump_results()[source]¶: Dump all file failures to disk as yaml.

Returns¶

None

fail_detect_ioctl(cpu, fname, cmd)[source]¶

Detect a failed ioctl call via return value.

Parameters¶

cpuAny: CPU context from PANDA.
fnamestr: File path to device.
cmdint: Command number of ioctl.

Returns¶

None

fail_detect_opens(cpu, fname, fd)[source]¶

Triggers on failed open calls.

Parameters¶

cpuAny: CPU context from PANDA.
fnamestr: File path.
fdint: File descriptor.

Returns¶

None

gen_hyperfile_function(filename, details, ftype)[source]¶

Generate correct hyperfile handler.

Parameters¶

filenamestr: Pseudofile path.
detailsdict: Additional pseudofile model information.
ftypestr: Pseudofile type.

Returns¶

function

hyp_enoent(cpu, file)[source]¶

Log files that return ENOENT.

Parameters¶

cpuAny: CPU context from PANDA.
filestr: File path of hyperfile.

Returns¶

None

ioctl_default(filename, cmd, arg, ioctl_details)[source]¶

Given a cmd and arg, return a value.

Parameters¶

filenamestr

Device path.

cmdint

Ioctl command number.

argstr

Optional pointer to buffer.

ioctl_detailsdict

Dictionary structure is cmd -> {‘model’: ‘return_const’|’symex’|’from_plugin’,: ‘val’: X}

Returns¶

int

log_ioctl_failure(path, cmd)[source]¶

Format and write ioctl failures to logs.

Parameters¶

pathstr: File path of device with ioctl failure.
cmdint: Command number of ioctl that failed.

Returns¶

None

populate_hf_config()[source]¶: Populate the hyperfile config dictionary.

Returns¶

None

proc_mtd_check(filename, buffer, length, offset, details=None)[source]¶

The guest is reading /proc/mtd. We should populate this file dynamically based on the /dev/mtd* devices we’ve set up.

These devices have a name in addition to other properties: /dev/mtd0:

name: mymtdname read:

model: return_const buf: “foo”

Parameters¶

filenamestr: Path to mtd file.
bufferint: Pointer to buffer.
lengthint: Length of buffer.
offsetint: Offset into buffer.
detailsAny: Additional context.

Returns¶

tuple

read_const_buf(filename, buffer, length, offset, details=None)[source]¶

Simple peripheral model to return a constant buffer.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device being read from.
detailsAny: Additional device context, including buffer contents.

Returns¶

tuple

read_const_map(filename, buffer, length, offset, details=None)[source]¶

Read data and returns tuple of buffer and size.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device file.
detailsAny: Additional device context.

Returns¶

tuple

read_const_map_file(filename, buffer, length, offset, details=None)[source]¶

Create a file on the host using the specified pad, size, vals When we read from the guest, we read from the host file.

Parameters¶

filenamestr: File path of device.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device.
detailsAny: Additional device context.

Returns¶

tuple

read_default(filename, buffer, length, offset, details=None)[source]¶

read_empty(filename, buffer, length, offset, details=None)[source]¶

Simple peripheral model to return an empty buffer.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device being read from.
detailsAny: Additional device context.

Returns¶

tuple

read_from_file(filename, buffer, length, offset, details=None)[source]¶

Read from host file.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device.
detailsAny: Additional device context.

Returns¶

tuple

read_one(filename, buffer, length, offset, details=None)[source]¶

Simple peripheral model to return a read of ‘1’.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device being read from.
detailsAny: Additional device context.

Returns¶

tuple

read_zero(filename, buffer, length, offset, details=None)[source]¶

Simple peripheral model inspired by firmadyne/firmae. Just return 0. If we’ve seen a write to this device, mix that data in with 0s padding around it.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to fill with 0s.
lengthint: Length of read.
offsetint: Offset into device being read from.
detailsAny: Additional device context.

Returns¶

tuple

symex_ioctl_return(regs, proto, syscall, fd, cmd, arg)[source]¶

Replace ioctl return value to signal that we should start symbolic execution.

Parameters¶

regsPtRegsWrapper: CPU registers.
protoAny: Protocol or plugin-specific context.
syscallint: Syscall number.
fdint: File descriptor.
cmdint: Ioctl command number.
argint: Optional additional pointer to a buffer in memory.

Returns¶

None

uninit()[source]¶: Uninitialize plugin and update logs for a final time.

Returns¶

None

write_default(filename, buffer, length, offset, contents, details=None)[source]¶

Store the contents for this file print(f”{filename} writes {length} bytes at {offset}: {contents[:100]}”)

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to read from.
lengthint: Length of read.
offsetint: Offset into device.
detailsAny: Additional device context.

Returns¶

int

write_discard(filename, buffer, length, offset, contents, details=None)[source]¶

TODO: make this actually discard - not sure where it’s used right now and default is a better model in general

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to write to.
lengthint: Length of read.
offsetint: Offset into device.
detailsAny: Additional device context.

Returns¶

int

write_to_file(filename, buffer, length, offset, contents, details=None)[source]¶

Write to host file.

Parameters¶

filenamestr: File path of pseudofile/peripheral.
bufferint: Pointer to buffer to read from.
lengthint: Length of read.
offsetint: Offset into device.
detailsAny: Additional device context.

Returns¶

tuple

pyplugins.interventions.pseudofiles.get_total_counts(d)[source]¶

Get the sum of all “count” values of a nested dictionary

Parameters¶

ddict: Dictionary with values to count.

Returns¶

int

pyplugins.interventions.pseudofiles.ignore_cmd(ioctl)[source]¶

Ignore TTY ioctls, see ioctls.h for T*, TC*, and TIO* ioctls

Parameters¶

ioctlint: Ioctl command number.

Returns¶

bool

pyplugins.interventions.pseudofiles.ignore_ioctl_path(path)[source]¶

Filter out ioctl paths that are irrelevant to rehosting.

Parameters¶

pathstr: File path.

Returns¶

bool

pyplugins.interventions.pseudofiles.make_rwif(details, fn_ref)[source]¶

pyplugins.interventions.pseudofiles.path_interesting(path)[source]¶

Determines if a path is likely to contain a good candidate for pseudofiles.

Parameters¶

pathstr: File path.

Returns¶

bool

pyplugins.interventions.pseudofiles.proc_interesting(path)[source]¶

Determines if a process is relevant to overall rehosting.

Parameters¶

pathstr: File path.

Returns¶

bool

pyplugins.interventions.pseudofiles.sort_file_failures(d)[source]¶

Get a sorted version of the file failures dictionary.

Parameters¶

ddict: Dictionary to sort.

Returns¶

dict