Connection Utilities¶
Connection and networking based utility functions.
Module Overview:
download - download from a given url
get_connections - quieries the connections belonging to a given process
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
address_to_int - provides an integer representation of an IP address
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.
Changed in version 1.4.0: Added NETSTAT_WINDOWS.
Changed in version 1.6.0: Added BSD_FSTAT.
Deprecated since version 1.6.0: The SOCKSTAT connection resolver is proving to be unreliable (ticket 23057), and will be dropped in the 2.0.0 release unless fixed.
Resolver Description PROC /proc contents NETSTAT netstat NETSTAT_WINDOWS netstat command under Windows SS ss command LSOF lsof command SOCKSTAT sockstat command under *nix BSD_SOCKSTAT sockstat command under FreeBSD BSD_PROCSTAT procstat command under FreeBSD BSD_FSTAT fstat command under OpenBSD
-
class
stem.util.connection.
Connection
[source]¶ Bases:
stem.util.connection.Connection
Network connection information.
Changed in version 1.5.0: Added the is_ipv6 attribute.
Variables: - local_address (str) – ip address the connection originates from
- local_port (int) – port the connection originates from
- remote_address (str) – destionation ip address
- remote_port (int) – destination port
- protocol (str) – protocol of the connection (‘tcp’, ‘udp’, etc)
- is_ipv6 (bool) – addresses are ipv6 if true, and ipv4 otherwise
-
stem.util.connection.
download
(url, timeout=None, retries=None)[source]¶ Download from the given url.
New in version 1.8.0.
Parameters: - url (str) – uncompressed url to download from
- timeout (int) – timeout when connection becomes idle, no timeout applied if None
- retires (int) – maximum attempts to impose
Returns: bytes content of the given url
Raises: DownloadTimeout
if our request timed outDownloadFailed
if our request fails
-
stem.util.connection.
get_connections
(resolver=None, process_pid=None, process_name=None)[source]¶ Retrieves a list of the current connections for a given process. This provides a list of
Connection
. Note that addresses may be IPv4 or IPv6 depending on what the platform supports.New in version 1.1.0.
Changed in version 1.5.0: Made our resolver argument optional.
Changed in version 1.5.0: IPv6 support when resolving via proc, netstat, lsof, or ss.
Parameters: - resolver (Resolver) – method of connection resolution to use, if not provided then one is picked from among those that should likely be available for the system
- process_pid (int) – pid of the process to retrieve
- process_name (str) – name of the process to retrieve
Returns: list of
Connection
instancesRaises: - ValueError if neither a process_pid nor process_name is 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.
system_resolvers
(system=None)[source]¶ Provides the types of connection resolvers likely to be available on this platform.
New in version 1.1.0.
Changed in version 1.3.0: Renamed from get_system_resolvers() to system_resolvers(). The old name still works as an alias, but will be dropped in Stem version 2.0.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.
address_to_int
(address)[source]¶ Provides an integer representation of a IPv4 or IPv6 address that can be used for sorting.
New in version 1.5.0.
Parameters: address (str) – IPv4 or IPv6 address Returns: int representation of the 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' >>> expand_ipv6_address('::ffff:5.9.158.75') '0000:0000:0000:0000:0000:ffff:0509:9e4b'
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
-
stem.util.connection.
get_system_resolvers
(system=None)¶ Provides the types of connection resolvers likely to be available on this platform.
New in version 1.1.0.
Changed in version 1.3.0: Renamed from get_system_resolvers() to system_resolvers(). The old name still works as an alias, but will be dropped in Stem version 2.0.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