pyplugins.actuation.vpn module

VPN Plugin (vpn.py) for Penguin

This module provides the VPN plugin, which enables vsock-based VPN bridging between the emulated guest and the host. It manages port mappings, source IP spoofing, and dynamic forwarding of guest network services to the host.

Features

  • Launches and manages host-side VPN and vsock bridge processes.

  • Handles port mappings from guest to host, including privileged ports and user-defined mappings.

  • Supports source IP spoofing for guest services.

  • Dynamically bridges guest network binds to the host and exposes them.

  • Logs and tracks active network bridges and listeners.

  • Cleans up VPN processes on exit.

Arguments

  • log (bool, optional): Enable logging of VPN traffic.

  • pcap (bool, optional): Enable PCAP capture of VPN traffic.

  • verbose (bool, optional): Enable verbose logging.

  • IGLOO_VPN_PORT_MAPS (str, optional): Comma-separated port mapping rules.
    This variable allows explicit mapping of guest services to host ports. The format is:

    <proto>:<host_port>:<guest_ip>:<guest_port>

    For example:

    IGLOO_VPN_PORT_MAPS=”TCP:80:192.168.0.1:80,udp:20002:192.168.0.1:20002”

    This maps TCP port 80 on the host to TCP port 80 on the guest at 192.168.0.1, and UDP port 20002 on the host to UDP port 20002 on the guest at 192.168.0.1. If not provided as an argument, the plugin will look for it in the environment variables. If neither is set, default port mapping logic is used.

  • spoof (dict, optional): Source IP spoofing configuration.

  • conf (dict): Configuration dictionary for the emulation environment.

Plugin Interface

  • Registers for the “on_bind” event to dynamically bridge guest network binds.

  • Publishes “on_bind” events for other plugins to react to new host-exposed services.

  • Writes bridge information to a CSV file in the output directory.

Overall Purpose

The VPN plugin enables flexible, dynamic, and secure exposure of guest network services to the host, supporting advanced features like port mapping and source IP spoofing, and integrates with the Penguin plugin system for event-driven networking.

class pyplugins.actuation.vpn.VPN(panda)[source]

Bases: Plugin

bridge(sock_type, ip, guest_port, procname, ipvn)[source]

Bridge a guest socket to the host, set up event and return host port.

Args:

sock_type (str): Socket type. ip (str): Guest IP address. guest_port (int): Guest port. procname (str): Process name. ipvn (int): IP version.

Returns:

int: Host port mapped to the guest socket.

Parameters:

  • sock_type (str)

  • ip (str)

  • guest_port (int)

  • procname (str)

  • ipvn (int)

Return type:

int

ensure_dev_has_ip(ip, dev, ipvn)[source]

Ensure the specified device has the given IP address.

Args:

ip (str): IP address to assign. dev (str): Device name. ipvn (int): IP version (4 or 6).

Raises:

RuntimeError: If unable to query or assign the IP address.

Parameters:

  • ip (str)

  • dev (str)

  • ipvn (int)

Return type:

None

launch_host_vpn(CID, socket_path, uds_path, log=False, pcap=False)[source]

Launch vhost-device-vsock and VPN on host.

Args:

CID (int): Context ID for vsock. socket_path (str): Path to the vsock socket. uds_path (str): Path to the Unix domain socket for QEMU. log (bool, optional): Enable logging of VPN traffic. pcap (bool, optional): Enable PCAP capture of VPN traffic.

Parameters:

  • CID (int)

  • socket_path (str)

  • uds_path (str)

  • log (bool)

  • pcap (bool)

Return type:

None

map_bound_socket(sock_type, ip, guest_port, procname)[source]

Map a guest socket to a host port, handling privileged ports and collisions.

Args:

sock_type (str): Socket type. ip (str): Guest IP address. guest_port (int): Guest port. procname (str): Process name.

Returns:

int: Host port mapped to the guest socket.

Parameters:

  • sock_type (str)

  • ip (str)

  • guest_port (int)

  • procname (str)

Return type:

int

on_bind(sock_type, ipvn, ip, port, procname)[source]

Handle a new bind event from the guest, set up bridges and publish events.

Args:

sock_type (str): Socket type (e.g., ‘tcp’, ‘udp’). ipvn (int): IP version (4 or 6). ip (str): Guest IP address. port (int): Guest port. procname (str): Process name binding the port.

Parameters:

  • sock_type (str)

  • ipvn (int)

  • ip (str)

  • port (int)

  • procname (str)

Return type:

None

uninit()[source]

Cleanup and terminate VPN and vsock bridge processes.

Return type:

None

pyplugins.actuation.vpn.guest_cmd(cmd)[source]

Run a command in the guest using guesthopper.

Args:

cmd (str): Command to run in the guest.

Returns:

subprocess.CompletedProcess: Result of the command execution.

Parameters:

cmd (str)

Return type:

CompletedProcess

pyplugins.actuation.vpn.kill_vpn()[source]

Kill all running VPN processes registered in running_vpns.

Return type:

None