fix: linting errors

Author: anthwal

netcat/netcat.py

@@ -35,12 +35,26 @@ def __init__(self, args, buffer=None) -> None:
         self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
 
     def run(self):
+        """
+        Entry point of the program, checks if the program is in listen mode
+        """
         if self.args.listen:
             self.listen()
         else:
             self.send()
 
     def send(self):
+        """
+        Establishes a connection to a target server and port,
+        sends an initial buffer if provided, and
+        facilitates bidirectional communication by receiving
+        data and allowing user input to send messages
+        in an interactive loop.
+
+        Raises:
+            KeyboardInterrupt: Captures user termination to ensure cleanup and graceful exit.
+
+        """
         self.socket.connect((self.args.target, self.args.port))
         if self.buffer:
             self.socket.send(self.buffer)
@@ -66,6 +80,10 @@ def send(self):
             sys.exit()
 
     def listen(self):
+        """
+        Listens for incoming connection if Program used
+        in listen mode
+        """
         print("listening")
         self.socket.bind((self.args.target, self.args.port))
         self.socket.listen(5)
@@ -76,6 +94,10 @@ def listen(self):
             client_thread.start()
 
     def handle(self, client_socket: socket.socket):
+        """
+        Handler function for incoming types of requests
+        which can be either command shell, upload, or execute
+        """
         if self.args.execute:
             output = execute(self.args.execute)
             client_socket.send(str(output).encode())
@@ -135,11 +157,11 @@ def handle(self, client_socket: socket.socket):
     parser.add_argument("-p", "--port", type=int, default=5555, help="specified port")
     parser.add_argument("-t", "--target", default="192.168.1.203", help="specified IP")
     parser.add_argument("-u", "--upload", help="upload file")
-    args = parser.parse_args()
-    if args.listen:
-        buffer = ""
+    input_args = parser.parse_args()
+    if input_args.listen:
+        BUFFER = ""
     else:
-        buffer = sys.stdin.read()
+        BUFFER = sys.stdin.read()
 
-    nc = NetCat(args, buffer.encode("utf-8"))
+    nc = NetCat(input_args, BUFFER.encode("utf-8"))
     nc.run()

proxies/proxy.py

@@ -9,10 +9,38 @@
 )
 
 
-def hexdump(src: bytes | str, length=16, show=True) -> list | None:
+def hexdump(src: bytes | str, length=16, show=True) -> list:
+    """
+    Generate a hex dump of a given input string or bytes object.
+
+    This function creates a hexadecimal representation of the input with
+    a specified length of bytes per line. It also provides a printable
+    representation of the content alongside the hex dump. Users can opt
+    to display the output directly or return it as a list of strings.
+
+    Parameters:
+    src: bytes | str
+        The input data to be converted to a hex dump. Can be either
+        a 'bytes' object or a string.
+    length: int, optional
+        The number of bytes to display per line in the hex dump.
+        Defaults to 16.
+    show: bool, optional
+        Determines whether to print the hex dump directly. If set to
+        False, the hex dump is returned as a list of strings. Defaults
+        to True.
+
+    Returns:
+    list
+        Returns a list of strings representing the hex dump.
+
+    Raises:
+    TypeError
+        If `src` is not of type bytes or str.
+    """
     if isinstance(src, bytes):
         src = src.decode()
-    results = list()
+    results = []
     for i in range(0, len(src), length):
         word = str(src[i : i + length])
         printable = word.translate(HEX_FILTER)
@@ -22,11 +50,21 @@ def hexdump(src: bytes | str, length=16, show=True) -> list | None:
     if show:
         for line in results:
             print(line)
-    else:
-        return results
+    return results
 
 
 def receive_from(connection: socket) -> bytes:
+    """
+    Receives data from a socket connection until no more data is sent or an
+    exception is raised. The method assembles all received chunks into a
+    single bytes object.
+
+    Args:
+        connection (socket): The socket connection to receive data from.
+
+    Returns:
+        bytes: The complete data received from the socket connection.
+    """
     buffer = b""
     connection.settimeout(10)
     try:
@@ -44,11 +82,37 @@ def receive_from(connection: socket) -> bytes:
 
 
 def request_handler(buffer: bytes) -> bytes:
+    """
+    Handles incoming binary packets, processes the data, and modifies the buffer
+    before sending it back.
+
+    This function takes a binary data buffer as input, modifies or processes the
+    information contained within, and returns the updated binary buffer as output.
+
+    Args:
+        buffer: Binary data to be modified and processed.
+
+    Returns:
+        Modified binary buffer after processing.
+    """
     # perform packet modifications
     return buffer
 
 
 def response_handler(buffer: bytes) -> bytes:
+    """
+    Processes and modifies the response packet data.
+
+    The function takes raw packet data as input, applies any
+    modifications required, and returns the modified packet data
+    as output.
+
+    Args:
+        buffer (bytes): The raw packet data to be processed.
+
+    Returns:
+        bytes: The modified packet data.
+    """
     # perform packet modifications
     return buffer
 
@@ -59,19 +123,41 @@ def proxy_handler(
     remote_port: int,
     receive_first: bool,
 ) -> None:
+    """
+    Handles the proxy connection by relaying data between a local client and a remote server.
+
+    This function establishes a connection with the remote host and optionally receives data first,
+    then continuously transfers data between the local client and the remote server while applying
+    custom request and response handlers. The function is designed for bidirectional data transfer
+    until one or both connections are closed.
+
+    Parameters:
+    client_socket: socket
+        The socket representing the local client connection.
+    remote_host: str
+        The hostname or IP address of the remote server to connect to.
+    remote_port: int
+        The port number of the remote server.
+    receive_first: bool
+        A flag indicating whether to receive data from the remote server before starting
+        the bidirectional data transfer.
+
+    Returns:
+    None
+    """
     remote_socket = socket(AF_INET, SOCK_STREAM)
     remote_socket.connect((remote_host, remote_port))
 
     if receive_first:
         remote_buffer = receive_from(remote_socket)
         if len(remote_buffer):
-            print("[<==] Received %d bytes from remote." % len(remote_buffer))
+            print(f"[<==] Received {len(remote_buffer)} bytes from remote.")
             hexdump(remote_buffer)
 
     while True:
         local_buffer = receive_from(client_socket)
         if len(local_buffer):
-            print("[<==] Received %d bytes from local." % len(local_buffer))
+            print(f"[<==] Received {len(local_buffer)} bytes from local.")
             hexdump(local_buffer)
 
             local_buffer = request_handler(local_buffer)
@@ -80,7 +166,7 @@ def proxy_handler(
 
         remote_buffer = receive_from(remote_socket)
         if len(remote_buffer):
-            print("[<==] Received %d bytes from remote." % len(remote_buffer))
+            print(f"[<==] Received {len(remote_buffer)} bytes from remote.")
             hexdump(remote_buffer)
 
             remote_buffer = response_handler(remote_buffer)
@@ -101,21 +187,24 @@ def server_loop(
     remote_port: int,
     receive_first: bool,
 ):
+    """
+    Main server loop, binds to the local host and port and starts the server
+    """
     server = socket(AF_INET, SOCK_STREAM)
     try:
         server.bind((local_host, local_port))
     except Exception as e:
-        print("[!!] Failed to listen on %s:%d" % (local_host, local_port))
+        print(f"[!!] Failed to listen on {local_host}:{local_port}")
         print("[!!] Check for other listening sockets or correct permissions.")
         print(e)
         exit(0)
 
-    print("[*] Listening on %s:%d" % (local_host, local_port))
+    print(f"[*] Listening on {local_host}:{local_port}")
     server.listen(5)
     while True:
         client_socket, addr = server.accept()
         # print out the local connection information
-        print("> Received incoming connection from %s:%d" % (addr[0], addr[1]))
+        print(f"> Received incoming connection from {addr[0]}:{addr[1]}")
 
         proxy_thread = Thread(
             target=proxy_handler,
@@ -125,6 +214,7 @@ def server_loop(
 
 
 def main():
+    """Main function of the proxy, parses the command line arguments and starts the server"""
     if len(argv[1:]) != 5:
         print("Usage: proxies/proxy.py [localhost] [localport]", end=" ")
         print("[remotehost] [remoteport] [receive_first]")
@@ -139,10 +229,7 @@ def main():
 
     receive_first = argv[5]
 
-    if "True" in receive_first:
-        receive_first = True
-    else:
-        receive_first = False
+    receive_first = bool(receive_first)
 
     server_loop(local_host, local_port, remote_host, remote_port, receive_first)