diff --git a/.gitignore b/.gitignore index 590d725cc..ce26650da 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,5 @@ tests/unit_tests/test_target/config.yaml penguin.sif fw db/events.* -local_packages/* \ No newline at end of file +local_packages/* +*.egg-info/ \ No newline at end of file diff --git a/docs/playbook.md b/docs/playbook.md index 43709cc45..449ca73a1 100644 --- a/docs/playbook.md +++ b/docs/playbook.md @@ -86,7 +86,7 @@ Beyond allowing you to add pseudofiles into a system, penguin also allows you to specify how `read`s, `write`s, and `ioctl`s of these files should be modeled. After adding a pseudofile to a config and running it, you might see -guest applications try to interact with this newly created psueodfile. The +guest applications try to interact with this newly created pseudofile. The `pseudofiles` plugin will collect the details of these accesses in the `pseudofiles_modeled.yaml`. In this file, you'll see keys of device paths with a list of interactions that @@ -99,6 +99,10 @@ following descriptions may be of value. #### Read modeling +**zero**: Read a zero (returns a single zero byte). + +**empty**: Read an empty file (returns empty data). + **default**: Return an empty string with return value `-EINVAL`. **const_buf**: Given some string in `val` model the file as containing that data. @@ -111,6 +115,8 @@ Provide a dictionary in `vals` with keys as an integer offset into the buffer an **from_file**: Given a host (container) file path in `filename` read from that file +**from_plugin**: Read from a custom PyPlugin. Specify the `plugin` name and optionally the `function` to call (defaults to `read`). + #### Write modeling **default**: Return value `-EINVAL` @@ -119,6 +125,8 @@ Provide a dictionary in `vals` with keys as an integer offset into the buffer an **to_file**: Given a host (container) file path in `filename` write to that file +**from_plugin**: Write to a custom PyPlugin. Specify the `plugin` name and optionally the `function` to call (defaults to `write`). + #### IOCTL modeling IOCTLs have a command number and each command can be modeled distinctly. A wildcard `*` can be used as a command number to indicate that all other ioctls should be modeled in a given way. @@ -126,13 +134,13 @@ IOCTLs have a command number and each command can be modeled distinctly. A wildc **return_const**: Return the specified `val` -**return_symex**: Coming soon. +**symex**: Perform symbolic execution on the IOCTL to identify distinct reachable paths. This is an advanced feature that requires the symex plugin to be enabled. ### How to model pseudofiles: -In your config file, you'll insert new keys udner `pseudofiles` for each file you want to model. By specifying a key (which must start with `/dev/` or `/proc/`), you'll +In your config file, you'll insert new keys under `pseudofiles` for each file you want to model. By specifying a key (which must start with `/dev/` or `/proc/`), you'll change the system so that a pseudofile is present at the specified location. If this is all you wish to do, you'll specify the key as having a value of `{}`. -Otherwise, if you'd like to model the behavior of the pseudofile, you'll add one or more subkeys of `read`, `write,` and `ioctl` and specify the model details. +Otherwise, if you'd like to model the behavior of the pseudofile, you'll add one or more subkeys of `read`, `write`, and `ioctl` and specify the model details. To just add `/dev/missing` into the filesystem: diff --git a/docs/plugins.md b/docs/plugins.md index 94e11eca4..074b600b3 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -13,7 +13,7 @@ The following penguin plugins are currently supported. Each is documented below. * [Pseudofiles](#pseudofiles): Model and monitor interactions to devices in `/dev` `/proc` and `/sys` * [Shell](#shell): Track behavior of shell scripts including lines executed * [VPNguin](#vpnguin): Bridge network connections to networked guest processes -* [Zap](#zap): **Currently disabled** Network scanning of guest web applications +* [ZAP](#zap): **Currently disabled** Network scanning of guest web applications ## Coverage This plugin tracks the module and offset block level coverage of all binaries @@ -31,7 +31,7 @@ If an env value is set to the magic string `DYNVALDYNVALDYNVAL` a dynamic analys to detect comparisons between this magic string and any other string will be enabled. The results of this analysis will be stored in `env_cmp.txt` -In a config file, a user may add key-value pairs into the `env` filed to set new +In a config file, a user may add key-value pairs into the `env` field to set new values into the linux environment. Note that a number of required internal variables (e.g., `root=/dev/vda`) will added to the system's arguments _after_ any arguments you specify here. @@ -51,7 +51,7 @@ reported in `iface.log`. Change output of uname syscall. Config Options: - `sysname`: changes operating system name -- `nodename`: changtes network node hostname +- `nodename`: changes network node hostname - `release`: changes the kernel release - `kversion`: changes the kernel version - `machine`: changes the machine hardware name diff --git a/docs/schema_doc.md b/docs/schema_doc.md index 131ba9738..0edf730fd 100644 --- a/docs/schema_doc.md +++ b/docs/schema_doc.md @@ -700,10 +700,10 @@ How to handle writes to the file |__Type__|string| -##### `pseudofiles..write.` Read from a custom PyPlugin +##### `pseudofiles..write.` Write to a custom PyPlugin -###### `pseudofiles..write..model` Write modelling method (read from a custom pyplugin) +###### `pseudofiles..write..model` Write modelling method (write to a custom pyplugin) ||| |-|-| diff --git a/docs/workflow.md b/docs/workflow.md index fcb2cd3c8..a3cf80205 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -73,7 +73,7 @@ The format of autogenerated configuration `./projects/stride/config.yaml` is doc highlighting: `core`: This section indicates project-wide settings such as the architecture. Within this section there are 3 notable options: -* `force_www`: if enabled, the rehosting will agressively attempt to start standard webservers +* `force_www`: if enabled, the rehosting will aggressively attempt to start standard webservers * `strace`: if enabled, every process in the system will have its system calls traced and logged to the output. * `show_output`: if this is set to true, console output will be shown on standard out of penguin. Otherwise console output will be logged into the results directory at `console.log` diff --git a/src/penguin/penguin_config/structure.py b/src/penguin/penguin_config/structure.py index e73c20785..ca3de45b3 100644 --- a/src/penguin/penguin_config/structure.py +++ b/src/penguin/penguin_config/structure.py @@ -442,7 +442,7 @@ class Core(PartialModelMixin, BaseModel): ), dict( discrim_val="from_plugin", - title="Read from a custom PyPlugin", + title="Write to a custom PyPlugin", description=None, fields=( ("plugin", str, Field(title="Name of the loaded PyPlugin")), @@ -631,7 +631,7 @@ class LibInject(PartialModelMixin, BaseModel): Field( None, title="Function names to alias to existing library function shims", - descriptions="Mapping between new names (e.g., my_nvram_get) and existing library function shims (e.g., nvram_get)", + description="Mapping between new names (e.g., my_nvram_get) and existing library function shims (e.g., nvram_get)", ), ]