pyplugins.apis.fs module¶

FS API Plugin¶

This module provides the FS plugin for the penguin framework, enabling interaction with the guest filesystem. It exposes methods for reading, writing, and querying files and directories in the guest, and can be used by other plugins to perform filesystem operations.

Features¶

Read files from the guest filesystem.
Write data to files in the guest.
Execute programs in the guest environment.
Supports chunked operations for large files.
Abstracts guest filesystem access for analysis and automation.

Example Usage¶

from penguin import plugins

# Read a file from the guest
content = yield from plugins.fs.read_file("/etc/passwd")

# Write to a file in the guest
yield from plugins.fs.write_file("/tmp/test.txt", "hello world")

# Execute a program in the guest
yield from plugins.fs.exec_program("/bin/ls", argv=["ls", "-l", "/"])

class pyplugins.apis.fs.FS[source]¶

Bases: Plugin

FS Plugin¶

Provides methods for interacting with the guest filesystem, including reading, writing, and listing files and directories.

Methods¶

read_file: Read a file from the guest filesystem.
write_file: Write data to a file in the guest filesystem.
exec_program: Execute a program in the guest environment.

Note¶

All methods are generated and their signatures and types are enforced.

exec_program(exe_path=None, argv=None, envp=None, wait=False)[source]¶

Execute a program in the guest environment.

Parameters¶

exe_pathstr, optional: Path to executable. If not provided, uses argv[0].
argvlist of str, optional: List of arguments (including program name as first arg).
envpdict of str, optional: Dictionary of environment variables.
waitbool, optional: Whether to wait for program to complete.

Returns¶

int: Return code from execution.

Raises¶

Exception: If the program cannot be executed.

Executes a program in the guest using the kernel’s call_usermodehelper function. Optionally waits for completion.

> Note: This method is generated and type-checked.

Parameters:

exe_path (str | None)
argv (list[str] | None)
envp (dict[str, str] | None)
wait (bool)

Return type:

int

read_file(fname, size=None, offset=0)[source]¶

Read a file from the guest filesystem.

Parameters¶

fnamestr: Path to the file in the guest.
sizeint, optional: Size limit. If None, reads entire file.
offsetint, optional: Offset in bytes where to start reading (default: 0).

Returns¶

bytes: The file data as bytes.

Raises¶

Exception: If the file cannot be read.

Reads the specified file from the guest filesystem, optionally limiting the read to a specific size and offset. If size is not specified, the entire file is read in chunks.

> Note: This method is generated and type-checked.

Parameters:

fname (str)
size (int | None)
offset (int)

Return type:

bytes

write_file(fname, data, offset=0)[source]¶

Write data to a file in the guest filesystem.

Parameters¶

fnamestr: Path to the file in the guest.
databytes or str: Data to write to the file.
offsetint, optional: Offset in bytes where to start writing (default: 0).

Returns¶

int: Number of bytes written.

Raises¶

Exception: If the file cannot be written.

Overwrites the file if it exists, or creates it if it does not. Handles large writes in chunks.

> Note: This method is generated and type-checked.

Parameters:

fname (str)
data (bytes | str)
offset (int)

Return type:

int