Stem Docs

Connection Utilities

Connection Utilities

Connection and networking based utility functions.

get_connections - quieries the connections belonging to a given process
get_system_resolvers - provides connection resolution methods that are likely to be available
port_usage - brief description of the common usage for a port

is_valid_ipv4_address - checks if a string is a valid IPv4 address
is_valid_ipv6_address - checks if a string is a valid IPv6 address
is_valid_port - checks if something is a valid representation for a port
is_private_address - checks if an IPv4 address belongs to a private range or not

expand_ipv6_address - provides an IPv6 address with its collapsed portions expanded
get_mask_ipv4 - provides the mask representation for a given number of bits
get_mask_ipv6 - provides the IPv6 mask representation for a given number of bits
stem.util.connection.Resolver(enum)

Method for resolving a process' connections.

New in version 1.1.0.

Resolver Description
PROC /proc contents
NETSTAT netstat command
SS ss command
LSOF lsof command
SOCKSTAT sockstat command under *nix
BSD_SOCKSTAT sockstat command under FreeBSD
BSD_PROCSTAT procstat command under FreeBSD
class stem.util.connection.Connection

Bases: tuple

Connection(local_address, local_port, remote_address, remote_port, protocol)

local_address

Alias for field number 0

local_port

Alias for field number 1

protocol

Alias for field number 4

remote_address

Alias for field number 2

remote_port

Alias for field number 3

stem.util.connection.get_connections(resolver, process_pid=None, process_name=None)[source]

Retrieves a list of the current connections for a given process. The provides a list of Connection instances, which have four attributes...

  • local_address (str)
  • local_port (int)
  • remote_address (str)
  • remote_port (int)
  • protocol (str, generally either 'tcp' or 'udp')

New in version 1.1.0.

Parameters:
  • resolver (Resolver) -- method of connection resolution to use
  • process_pid (int) -- pid of the process to retrieve
  • process_name (str) -- name of the process to retrieve
Returns:

list of Connection instances

Raises:
  • ValueError if using Resolver.PROC or Resolver.BSD_PROCSTAT and the process_pid wasn't provided
  • IOError if no connections are available or resolution fails (generally they're indistinguishable). The common causes are the command being unavailable or permissions.
stem.util.connection.get_system_resolvers(system=None)[source]

Provides the types of connection resolvers likely to be available on this platform.

New in version 1.1.0.

Parameters:system (str) -- system to get resolvers for, this is determined by platform.system() if not provided
Returns:list of Resolver instances available on this platform
stem.util.connection.port_usage(port)[source]

Provides the common use of a given port. For example, 'HTTP' for port 80 or 'SSH' for 22.

New in version 1.2.0.

Parameters:port (int) -- port number to look up
Returns:str with a description for the port, None if none is known
stem.util.connection.is_valid_ipv4_address(address)[source]

Checks if a string is a valid IPv4 address.

Parameters:address (str) -- string to be checked
Returns:True if input is a valid IPv4 address, False otherwise
stem.util.connection.is_valid_ipv6_address(address, allow_brackets=False)[source]

Checks if a string is a valid IPv6 address.

Parameters:
  • address (str) -- string to be checked
  • allow_brackets (bool) -- ignore brackets which form '[address]'
Returns:

True if input is a valid IPv6 address, False otherwise

stem.util.connection.is_valid_port(entry, allow_zero=False)[source]

Checks if a string or int is a valid port number.

Parameters:
  • entry (list,str,int) -- string, integer or list to be checked
  • allow_zero (bool) -- accept port number of zero (reserved by definition)
Returns:

True if input is an integer and within the valid port range, False otherwise

stem.util.connection.is_private_address(address)[source]

Checks if the IPv4 address is in a range belonging to the local network or loopback. These include:

  • Private ranges: 10.*, 172.16.* - 172.31.*, 192.168.*
  • Loopback: 127.*

New in version 1.1.0.

Parameters:address (str) -- string to be checked
Returns:True if input is in a private range, False otherwise
Raises:ValueError if the address isn't a valid IPv4 address
stem.util.connection.expand_ipv6_address(address)[source]

Expands abbreviated IPv6 addresses to their full colon separated hex format. For instance...

>>> expand_ipv6_address('2001:db8::ff00:42:8329')
'2001:0db8:0000:0000:0000:ff00:0042:8329'

>>> expand_ipv6_address('::')
'0000:0000:0000:0000:0000:0000:0000:0000'
Parameters:address (str) -- IPv6 address to be expanded
Raises:ValueError if the address can't be expanded due to being malformed
stem.util.connection.get_mask_ipv4(bits)[source]

Provides the IPv4 mask for a given number of bits, in the dotted-quad format.

Parameters:bits (int) -- number of bits to be converted
Returns:str with the subnet mask representation for this many bits
Raises:ValueError if given a number of bits outside the range of 0-32
stem.util.connection.get_mask_ipv6(bits)[source]

Provides the IPv6 mask for a given number of bits, in the hex colon-delimited format.

Parameters:bits (int) -- number of bits to be converted
Returns:str with the subnet mask representation for this many bits
Raises:ValueError if given a number of bits outside the range of 0-128