socksio library

Warnings

• gotcha socksio explicitly does not perform any network I/O. Users must integrate `socksio`'s `send()` and `receive()` methods with their own socket or network transport layer (e.g., `asyncio`, `trio`, `socket`). This is a common source of confusion if expecting a full client.
  Fix: Implement custom I/O logic using standard library `socket` or an asynchronous framework like `asyncio` to read from and write to the network based on `socksio`'s output and input.
• gotcha The library's scope is limited to the SOCKS proxy negotiation handshake. Once the `ConnectionState.OPEN` state is reached, `socksio` is no longer involved, and subsequent application data must be handled directly by the user's code via the established connection.
  Fix: After the SOCKS handshake, transition your I/O loop to send and receive application-specific data directly over the underlying network connection, bypassing `socksio`.
• gotcha Protocol violations or unexpected server responses will raise exceptions (e.g., `BadSocksConnectionState`, `MalformedSocks5Reply`). Robust applications must catch and handle these errors to manage connection failures gracefully.
  Fix: Wrap calls to `conn.receive()` and `conn.send()` in `try...except` blocks to catch specific `socksio` exceptions and handle them appropriately, such as logging the error and closing the connection.

Install

• pip install socksio Install stable version

Imports

• Socks5Connection

  from socksio import Socks5Connection

• Socks5AuthMethods

  from socksio import Socks5AuthMethods

• SOCKS5_NO_AUTH

  from socksio import SOCKS5_NO_AUTH

• ConnectionState

  from socksio import ConnectionState

• BadSocksConnectionState

  from socksio import BadSocksConnectionState

Quickstart

This quickstart demonstrates the core functionality of `socksio` by simulating a SOCKS5 proxy handshake. It shows how to initialize a connection, send client data, receive simulated server responses, and observe the state transitions. Remember that `socksio` handles only the protocol state machine, not actual network I/O.

from socksio import Socks5Connection, Socks5AuthMethods, SOCKS5_NO_AUTH, ConnectionState

# This example demonstrates the SOCKS5 state machine, it does not perform actual network I/O.
# In a real application, 'client_greeting_data' would be written to a socket,
# and 'server_greeting_response' would be read from that socket.

# 1. Initialize a SOCKS5 connection to a target host and port.
target_host = "example.com"
target_port = 80
conn = Socks5Connection(target_host, target_port)
print(f"Initial state: {conn.state}") # Expected: ConnectionState.INIT

# 2. Client sends greeting with supported authentication methods.
# For SOCKS5, common is NO_AUTH.
client_greeting_data = conn.send(Socks5AuthMethods([SOCKS5_NO_AUTH]))
print(f"\nClient sends greeting ({len(client_greeting_data)} bytes): {client_greeting_data.hex()}")
print(f"State after sending greeting: {conn.state}") # Expected: ConnectionState.WAITING_FOR_AUTH_METHOD_SELECTION

# 3. Simulate server response to greeting.
# A SOCKS5 server typically responds with version (0x05) and selected method (0x00 for NO_AUTH).
server_greeting_response = b'\x05\x00'
conn.receive(server_greeting_response)
print(f"\nServer responds to greeting ({len(server_greeting_response)} bytes): {server_greeting_response.hex()}")
print(f"State after receiving greeting response: {conn.state}") # Expected: ConnectionState.AUTH_SUCCESS

# 4. Client sends connection request.
# The `send()` method generates the connect request based on target_host/port.
client_connect_data = conn.send()
print(f"\nClient sends connect request ({len(client_connect_data)} bytes): {client_connect_data.hex()}")
print(f"State after sending connect request: {conn.state}") # Expected: ConnectionState.WAITING_FOR_CONNECT_REPLY

# 5. Simulate server response to connection request.
# A successful SOCKS5 connect reply for IPv4 would be:
# 0x05 (version) 0x00 (success) 0x00 (reserved) 0x01 (IPv4 address type)
# followed by bound address (4 bytes, e.g., 127.0.0.1) and bound port (2 bytes, e.g., 80)
server_connect_response = b'\x05\x00\x00\x01\x7f\x00\x00\x01\x00\x50' # 127.0.0.1:80
conn.receive(server_connect_response)
print(f"\nServer responds to connect request ({len(server_connect_response)} bytes): {server_connect_response.hex()}")
print(f"Final state: {conn.state}") # Expected: ConnectionState.OPEN

if conn.is_connected:
    print("\nSOCKS5 handshake successfully completed (simulated).")
    print(f"Bound address: {conn.bound_address}, Bound port: {conn.bound_port}")
else:
    print("\nSOCKS5 handshake failed (simulated).")