Q3 Rcon CLI - single file, zero dependencies

rcon.py

#!/usr/bin/env python3

# MIT License
#
# Copyright (c) 2025 Onyx and Iris
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

"""
rcon.py

This script provides functionality to interact with a remote server using the RCON (Remote Console) protocol.

It includes classes to encode and decode RCON packets, send commands to the server, and handle responses.
The script also provides a command-line interface for sending RCON commands to a server.

Classes:
    Packet: Base class for RCON packets.
    Request: Class to encode a request packet for RCON communication.
    ResponseBuilder: Class to build and decode a response packet from multiple fragments.

Functions:
    send(sock: socket.socket, request: Request, host: str, port: int, cmd: str) -> str:
        Sends an RCON command to the server and returns the response.
    parse_args() -> argparse.Namespace:
        Parses command-line arguments.
    main():
        Main function to handle command-line arguments and interact with a remote server using RCON protocol.

Usage:
    To send a single command to the server:
        python rcon.py --host <server_host> --port <server_port> --password <rcon_password> <command>

    To use interactive mode:
        python rcon.py --host <server_host> --port <server_port> --password <rcon_password> --interactive
"""

import argparse
import re
import socket


class Packet:
    MAGIC = bytearray([0xFF, 0xFF, 0xFF, 0xFF])


class Request(Packet):
    """
    Class used to encode a request packet for remote console (RCON) communication.

    Attributes:
        password (str): The password used for authentication with the RCON server.

    Methods:
        _header() -> bytes:
            Generates the header for the RCON packet.

        encode(cmd: str) -> bytes:
            Encodes the command into a byte string suitable for sending to the RCON server.
            Args:
                cmd (str): The command to be sent to the RCON server.
            Returns:
                bytes: The encoded command as a byte string.
    """

    def __init__(self, password: str):
        self.password = password

    def _header(self) -> bytes:
        return Packet.MAGIC + b"rcon"

    def encode(self, cmd: str) -> bytes:
        return self._header() + f" {self.password} {cmd}".encode()


class ResponseBuilder(Packet):
    """
    Class used to build and decode a response packet from multiple fragments.

    Attributes:
        _fragments (bytearray): A bytearray to store the concatenated fragments.

    Methods:
        _header() -> bytes:
            Returns the header bytes that each fragment should start with.

        is_valid_fragment(fragment: bytes) -> bool:
            Checks if the given fragment starts with the expected header.

        add_fragment(fragment: bytes):
            Adds a fragment to the internal storage after removing the header.

        build() -> str:
            Decodes and returns the concatenated fragments as a string.
    """

    def __init__(self):
        self._fragments = bytearray()

    def _header(self) -> bytes:
        return Packet.MAGIC + b"print\n"

    def is_valid_fragment(self, fragment: bytes) -> bool:
        return fragment.startswith(self._header())

    def add_fragment(self, fragment: bytes):
        self._fragments.extend(fragment.removeprefix(self._header()))

    def build(self) -> str:
        return self._fragments.decode()


def send(sock: socket.socket, request: Request, host: str, port: int, cmd: str) -> str:
    """
    Send a single RCON (Remote Console) command to the server and return the response.

    This function sends a command to a game server using the RCON protocol over a UDP socket.
    It waits for the server's response, collects it in fragments if necessary, and returns the complete response.

    Args:
        sock (socket.socket): The UDP socket object used to send and receive data.
        request (Request): An instance of the Request class used to encode the command.
        host (str): The hostname or IP address of the server.
        port (int): The port number on which the server is listening.
        cmd (str): The RCON command to be sent to the server.

    Returns:
        str: The complete response from the server after processing all received fragments.

    Raises:
        socket.timeout: If the socket times out while waiting for a response from the server.
    """
    sock.sendto(request.encode(cmd), (host, port))

    response_builder = ResponseBuilder()
    while True:
        try:
            data, _ = sock.recvfrom(4096)
        except socket.timeout:
            break

        if response_builder.is_valid_fragment(data):
            response_builder.add_fragment(data)

    return response_builder.build()


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument("--host", default="localhost")
    parser.add_argument("--port", type=int, default=27960)
    parser.add_argument("--password", default="secret")
    parser.add_argument("--timeout", type=float, default=0.2)
    parser.add_argument("--interactive", action="store_true")
    parser.add_argument("cmd", nargs="?", default="status")
    args = parser.parse_args()
    return args


def main():
    """
    Main function to handle command-line arguments and interact with a remote server using RCON protocol.
    This function parses command-line arguments, creates a UDP socket, and sends requests to a remote server.
    It supports both interactive and non-interactive modes.
    In non-interactive mode, it sends a single command to the server and prints the response.
    In interactive mode, it continuously prompts the user for commands until the user quits by entering 'Q'.
    Args:
        None
    Returns:
        None
    """

    def cleaned_response(resp: str) -> str:
        return re.sub(r"\^[0-9]", "", resp)

    args = parse_args()

    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
        sock.settimeout(args.timeout)

        request = Request(args.password)

        if not args.interactive:
            if resp := send(sock, request, args.host, args.port, args.cmd):
                print(cleaned_response(resp))
            return

        while cmd := input("cmd: ").strip():
            if cmd == "Q":
                break

            if resp := send(sock, request, args.host, args.port, cmd):
                print(cleaned_response(resp))


if __name__ == "__main__":
    main()

chmod +x this script and run it directly like so:

Example usage:

./rcon.py --port=28960 --password="$RCON_PASSWORD" --i

Then place it somewhere like /usr/bin/local if you want it to be discoverable.

You can send single rcon command as well, for example:

./rcon.py --port=28960 --password="$RCON_PASSWORD" g_gametype