pyplugins.analysis.netbinds module

NetBinds Plugin (netbinds.py) for Penguin

This module provides the NetBinds plugin, which monitors and records all network bind events within the guest during emulation. It tracks both IPv4 and IPv6 binds, logs detailed information about each bind, and publishes ‘on_bind’ events for other plugins to react to new network services.

Features

• Subscribes to low-level bind/setup/release events for IPv4 and IPv6 sockets.

• Tracks and deduplicates all bind events, including process name, IP version, socket type, IP, and port.

• Logs bind details and summary statistics to CSV files in the output directory.

• Publishes ‘on_bind’ events for other plugins (such as VPN, Nmap, FetchWeb) to consume.

• Optionally shuts down emulation when a web service (port 80) is bound, if configured.

Arguments

• shutdown_on_www (bool, optional): If True, shut down emulation when a bind occurs on port 80.

Plugin Interface

• Publishes ‘on_bind’ events with (sock_type, ipvn, ip, port, procname) for other plugins to consume.

• Does not subscribe to other plugin events, but listens to low-level system events.

• Writes bind logs and summaries to files in the output directory.

Overall Purpose

The NetBinds plugin provides a comprehensive record of all network services started by the guest, enabling automation, analysis, and integration with other actuation plugins.

class pyplugins.analysis.netbinds.NetBinds

Bases: Plugin

give_list()

Return the current list of tracked binds.

Returns:

list: A list of dictionaries, each representing a tracked bind.

on_bind(cpu, procname, is_ipv4, is_stream, port, sin_addr)

Handle a completed bind event, log details, publish event, and optionally shut down.

Args:

cpu: The CPU core where the event occurred. procname: The name of the process that performed the bind. is_ipv4: Boolean indicating if this is an IPv4 bind. is_stream: Boolean indicating if this is a stream (TCP) bind. port: The port number being bound, in host byte order. sin_addr: The IP address being bound, in network byte order.

Return type:

None

on_ipv4_bind(cpu, port, is_steam)

Handle IPv4 bind event, trigger on_bind and clear pending state.

Args:

cpu: The CPU core where the event occurred. port: The port number being bound, in host byte order. is_steam: Boolean indicating if this is a stream (TCP) bind.

Return type:

None

on_ipv4_release(cpu, ip_port, is_stream)

Handle IPv4 socket release event, remove bind from tracking.

Args:

cpu: The CPU core where the event occurred. ip_port: The IP:port string of the released socket. is_stream: Boolean indicating if this was a stream (TCP) socket.

Return type:

None

on_ipv4_setup(cpu, procname, sin_addr)

Handle IPv4 socket setup event, record pending bind state.

Args:

cpu: The CPU core where the event occurred. procname: The name of the process attempting the bind. sin_addr: The IPv4 address being bound, in network byte order.

Return type:

None

on_ipv6_bind(cpu, port, is_steam)

Handle IPv6 bind event, trigger on_bind and clear pending state.

Args:

cpu: The CPU core where the event occurred. port: The port number being bound, in host byte order. is_steam: Boolean indicating if this is a stream (TCP) bind.

Return type:

None

on_ipv6_release(cpu, ip_port, is_stream)

Handle IPv6 socket release event, remove bind from tracking.

Args:

cpu: The CPU core where the event occurred. ip_port: The IP:port string of the released socket. is_stream: Boolean indicating if this was a stream (TCP) socket.

Return type:

None

on_ipv6_setup(cpu, procname, sinaddr_addr)

Handle IPv6 socket setup event, record pending bind state.

Args:

cpu: The CPU core where the event occurred. procname: The name of the process attempting the bind. sinaddr_addr: The memory address where the IPv6 address is stored.

Return type:

None

remove_bind(ip, port, sock_type)

Remove a bind from the internal tracking list.

Args:

ip: The IP address of the bind to remove. port: The port number of the bind to remove. sock_type: The type of socket (TCP or UDP) of the bind to remove.

Return type:

None

report_bind_info(time_delta, procname, ipvn, sock_type, ip, port)

Log bind details and summary statistics to disk.

Args:

time_delta: The time since emulation start when the bind occurred. procname: The name of the process that performed the bind. ipvn: The IP version (4 or 6) of the bind. sock_type: The type of socket (TCP or UDP). ip: The IP address being bound. port: The port number being bound.

Return type:

None

track_bind(procname, ipvn, sock_type, ip, port, time)

Track a bind event in the internal list for later analysis.

Args:

procname: The name of the process that performed the bind. ipvn: The IP version (4 or 6) of the bind. sock_type: The type of socket (TCP or UDP). ip: The IP address being bound. port: The port number being bound. time: The time since emulation start when the bind occurred.

Return type:

None