Penguin Documentation

Documentation

• Penguin: Configuration Based Rehosting
  • Obtain target filesystem
  • Generate initial configuration
  • Run rehosting specified by configuration
  • Refine rehosting configuration
  • Examples
• Installation
  • Pull container and install penguin
    • System-wide install:
    • Local install:
  • Local development from source
• Learn more about Penguin
  • Additional documentation
  • Disclaimer
• Penguin Development Guide
  • Installation and ./penguin usage
  • Private dependencies
  • Dependency Development
• Example: Local kernel development
• Local Plugins
  • Example
• Penguin Playbook
  • Init program selection
    • When to change init
    • Potential init programs to choose from
    • How to change init:
  • Pseudofile modeling
    • When to create pseudofile models
    • Potential pseudofiles to add
    • Modeling pseudofiles
    • How to model pseudofiles:
  • Kernel environment variables
    • When to set boot arguments
    • How to set boot arguments:
    • When to set U-Boot Environment variables
  • Advanced debugging
• Penguin Plugins
  • Coverage
  • Env
  • Health
  • Interfaces
  • KernelVersion
  • Lifeguard
  • Mounts
  • NVRAM2
  • Netbinds
  • Nmap
  • Pseudofiles
  • Shell
  • VPNguin
  • ZAP
• Portal
  • What is Portal?
  • How Hypermem Works
  • Memory Region Structure
  • Example: Using Hypermem in a Python Plugin
    • Basic Usage Pattern
    • Advanced Examples
    • The Problem
    • The Original Function (from GPL code)
    • The Solution with Hypermem and Syscall Filtering
    • Using Advanced Filtering to Target Specific Code Paths
    • Benefits of Using Hypermem with Syscall Filtering
    • Result
  • API Reference
    • Reading Memory
    • Writing Memory
    • Process Information
    • File Descriptor Information
  • Real-world Example: IOCTL Interaction Test
  • Understanding the Kernel Implementation
  • Operation Flow
  • Differences from Traditional Memory Access
  • References
• Plugins
  • The Plugin Class
  • Plugin Arguments
  • Plugin File Locations and Discovery
  • The Plugin Manager
    • Plugin Interaction
    • Auto-Loading Plugins
    • Publish/Subscribe Model
• Penguin Configuration
  • core Core configuration options
    • core.arch Architecture of guest
    • core.kernel Path to kernel image
    • core.fs Project-relative path to filesystem tarball
    • core.plugin_path Path to search for PyPlugins
    • core.root_shell Enable root shell
    • core.strace Enable strace
    • core.ltrace Enable ltrace
    • core.gdbserver Programs to run through gdbserver
    • core.force_www Try to force webserver start
    • core.cpu CPU model
    • core.show_output Write serial to stdout
    • core.immutable Enable immutable mode
    • core.network Connect guest to network
    • core.shared_dir Project-relative path of shared directory
    • core.version Config format version
    • core.auto_patching Enable automatic patching
    • core.guest_cmd Enable running commands in the guest
    • core.extra_qemu_args Extra QEMU arguments
    • core.mem Panda Memory Value
    • core.kernel_quiet Whether to include quiet flag in kernel command line
    • core.smp Number of CPUs
    • core.graphics Enable graphics
  • patches Patches
  • env Environment
    • env.<string> Value
  • pseudofiles Pseudo-files
    • pseudofiles.<string> File emulation spec
  • nvram NVRAM
    • nvram.<string> NVRAM value
  • netdevs Network devices
  • uboot_env U-Boot environment
    • uboot_env.<string> Value
  • blocked_signals List of blocked signals
  • lib_inject Injected library configuration
    • lib_inject.aliases Injected library aliases
    • lib_inject.extra Extra injected library code
  • static_files Static files
    • static_files.<string> Static filesystem action
  • plugins Plugins
    • plugins.<string> Plugin
  • network Network Configuration
    • network.external Set up NAT for outgoing connections
• Scripting Plugins in Penguin
  • Key Differences: Plugins vs. Scripts
  • Example: Scripting Plugin
  • Example: Class-based Plugin
  • When to Use Scripting Plugins
  • When to Use Class-based Plugins
• Singularity
  • Building Singularity container
  • Using your Singularity container
• Syscalls Plugin System
  • Overview
  • Quick Start
  • Core Concepts
    • Syscall Events
    • Hook Registration
  • API Reference
    • Decorator Parameters
    • Advanced Filtering with ValueFilter
  • Handler Function Signatures
    • Standard Handlers
    • All-Syscall Handlers
  • SyscallEvent Object
  • SyscallPrototype Object
  • Practical Examples
    • Process Monitoring
    • File Access Monitoring
    • Network Monitoring
    • Return Value Analysis
    • Complex Filtering Example
  • Performance Considerations
    • Hook Granularity
    • Memory Access
    • Filtering Efficiency
  • Error Handling
    • Memory Access Failures
    • Portal Communication
  • Hook Management
    • Dynamic Control
    • Hook Information
  • Integration with Other Plugins
    • With Portal Plugin
    • With OSI Plugin
  • Testing
  • Troubleshooting
    • Common Issues
    • Debugging
  • Best Practices
• Uprobes Plugin System
  • Overview
  • Quick Start
  • Core Concepts
    • Uprobe Events
    • Probe Registration
  • API Reference
    • Decorator Parameters
    • Handler Function Signature
  • pt_regs Object
  • Practical Examples
    • Monitor Function Entry
    • Monitor Function Return
    • Wildcard Library Matching
    • Register on All Libraries Containing a Symbol
    • Offset-based Probes
    • Process and PID Filtering
  • Performance Considerations
  • Error Handling
  • Hook Management
    • Dynamic Control
    • Probe Information
  • Integration with Other Plugins
    • With Portal Plugin
    • With OSI Plugin
  • Testing
  • Troubleshooting
    • Common Issues
    • Debugging
  • Best Practices
• Example Rehosting Workflow
  • Convert firmware blob to root filesystem archive
  • Initialize penguin project from root filesystem archive
    • Static analysis outputs
    • Configuration
  • Run your configuration and collect output:
    • Dynamic analysis results
    • Root shell
    • Network connectivity with VPN
    • Shut down rehosting
  • Update configuration
    • Finding SXID
    • New errors with SXID
    • Adding /dev/dsa
    • IOCTL modeling
    • Webserver starts

API Reference

Packages

• penguin package
  • Subpackages
    • penguin.penguin_config package
  • Submodules
    • penguin.abi_info module
    • penguin.analyses module
    • penguin.arch module
    • penguin.common module
    • penguin.config_patchers module
    • penguin.defaults module
    • penguin.gen_config module
    • penguin.gen_image module
    • penguin.genetic module
    • penguin.graph_search module
    • penguin.graphs module
    • penguin.llm module
    • penguin.manager module
    • penguin.patch_minimizer module
    • penguin.patch_search module
    • penguin.penguin_prep module
    • penguin.penguin_run module
    • penguin.plugin_manager module
    • penguin.q_config module
    • penguin.search_utils module
    • penguin.static_analyses module
    • penguin.utils module
• pengutils package
  • Subpackages
    • pengutils.events package
    • pengutils.utils package
• pyplugins package
  • PyPlugins package
    • Importing in PyPlugins
  • Subpackages
    • pyplugins.actuation package
    • pyplugins.analysis package
    • pyplugins.apis package
    • pyplugins.compat package
    • pyplugins.core package
    • pyplugins.hyper package
    • pyplugins.interventions package
    • pyplugins.loggers package
    • pyplugins.wrappers package