Auto-Argparse for smb{client,server} (#4313)

Author: gpotter2

doc/scapy/layers/smb.rst

@@ -92,6 +92,15 @@ You might be wondering if you can pass the ``HashNT`` of the password of the use
 
 If you pay very close attention, you'll notice that in this case we aren't using the :class:`~scapy.layers.spnego.SPNEGOSSP` wrapper. You could have used ``ssp=SPNEGOSSP([t.ssp(1)])``.
 
+.. note::
+
+    It is also possible to start the :class:`~scapy.layers.smbclient.smbclient` directly from the OS, using the following::
+
+        $ python3 -m scapy.layers.smbclient server1.domain.local [email protected]
+    
+    Use ``python3 -m scapy.layers.smbclient -h`` to see the list of available options.
+
+
 Programmatically
 ________________
 
@@ -201,17 +210,17 @@ It's also accessible as the ``ins`` attribute of a ``SMB_SOCKET``, or the ``sock
 SMB 2/3 server
 --------------
 
-Scapy provides a SMB 2/3 server Automaton: :class:`~scapy.layers.smbclient.SMB_Server`
+Scapy provides a SMB 2/3 server Automaton: :class:`~scapy.layers.smbserver.SMB_Server`
 
 .. image:: ../graphics/smb/smb_server.png
    :align: center
 
-Once again, Scapy provides high level :class:`~scapy.layers.smbclient.smbserver` class that allows to spawn a SMB server.
+Once again, Scapy provides high level :class:`~scapy.layers.smbserver.smbserver` class that allows to spawn a SMB server.
 
-High-Level :class:`~scapy.layers.smbclient.smbserver`
+High-Level :class:`~scapy.layers.smbserver.smbserver`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :class:`~scapy.layers.smbclient.smbserver` class allows to spawn a SMB server serving a selection of shares.
+The :class:`~scapy.layers.smbserver.smbserver` class allows to spawn a SMB server serving a selection of shares.
 A share is identified by a ``name`` and a ``path`` (+ an optional description called ``remark``).
 
 **Start a SMB server with NTLM auth for 2 users:**
@@ -271,10 +280,19 @@ A share is identified by a ``name`` and a ``path`` (+ an optional description ca
         ),
     )
 
-Low-Level :class:`~scapy.layers.smbclient.SMB_Server`
+.. note::
+
+    It is possible to start the :class:`~scapy.layers.smbserver.smbserver` (albeit only in unauthenticated mode) directly from the OS, using the following::
+
+        $ python3 -m scapy.layers.smbserver --port 12345
+
+    Use ``python3 -m scapy.layers.smbserver -h`` to see the list of available options.
+
+
+Low-Level :class:`~scapy.layers.smbserver.SMB_Server`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To change the functionality of the :class:`~scapy.layers.smbclient.SMB_Server`, you shall extend the server class (which is an automaton) and provide additional custom conditions (or overwrite existing ones).
+To change the functionality of the :class:`~scapy.layers.smbserver.SMB_Server`, you shall extend the server class (which is an automaton) and provide additional custom conditions (or overwrite existing ones).
 
 .. code:: python
 

scapy/layers/smbclient.py

@@ -450,7 +450,7 @@ def send_data(self, d):
 
 class SMB_SOCKET(SuperSocket):
     """
-    High-level wrapper over SMB_Client.smblink that provides some basic SMB
+    Mid-level wrapper over SMB_Client.smblink that provides some basic SMB
     client functions, such as tree connect, directory query, etc.
     """
 
@@ -827,19 +827,19 @@ class smbclient(CLIUtil):
 
     def __init__(
         self,
-        target,
-        UPN=None,
-        password=None,
+        target: str,
+        UPN: str = None,
+        password: str = None,
+        guest: bool = False,
+        kerberos: bool = True,
+        kerberos_required: bool = False,
+        HashNt: str = None,
+        port: int = 445,
+        timeout: int = 2,
+        debug: int = 0,
         ssp=None,
-        guest=False,
-        kerberos=True,
-        kerberos_required=False,
-        HashNt=None,
         ST=None,
         KEY=None,
-        port=445,
-        timeout=2,
-        debug=0,
         cli=True,
     ):
         if cli:
@@ -1196,7 +1196,7 @@ def _lfs_complete(self, arg, cond):
         eltpar, eltname = self._parsepath(arg, remote=False)
         eltpar = self.localpwd / eltpar
         return [
-            self.normalize_path(eltpar / x)
+            str(x.relative_to(self.localpwd))
             for x in eltpar.glob("*")
             if (x.name.lower().startswith(eltname.lower()) and cond(x))
         ]
@@ -1471,3 +1471,8 @@ def rm_complete(self, file):
         if self._require_share(silent=True):
             return []
         return self._fs_complete(file)
+
+
+if __name__ == "__main__":
+    from scapy.utils import AutoArgparse
+    AutoArgparse(smbclient)

scapy/layers/smbserver.py

@@ -1698,9 +1698,9 @@ class smbserver:
     def __init__(
         self,
         shares=None,
-        iface=None,
-        port=445,
-        verb=2,
+        iface: str = None,
+        port: int = 445,
+        verb: int = 2,
         # SMB arguments
         ssp=None,
         **kwargs,
@@ -1744,3 +1744,8 @@ def close(self):
         if self.srv:
             self.srv.shutdown(socket.SHUT_RDWR)
             self.srv.close()
+
+
+if __name__ == "__main__":
+    from scapy.utils import AutoArgparse
+    AutoArgparse(smbserver)

scapy/utils.py

@@ -13,6 +13,7 @@
 from itertools import zip_longest
 
 import array
+import argparse
 import collections
 import decimal
 import difflib
@@ -3544,6 +3545,101 @@ def loop(self, debug: int = 0) -> None:
                         print("Output processor failed with error: %s" % ex)
 
 
+def AutoArgparse(func: DecoratorCallable) -> None:
+    """
+    Generate an Argparse call from a function, then call this function.
+
+    Notes:
+
+    - for the arguments to have a description, the sphinx docstring format
+      must be used. See
+      https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html
+    - the arguments must be typed in Python (we ignore Sphinx-specific types)
+      untyped arguments are ignored.
+    - only types that would be supported by argparse are supported. The others
+      are omitted.
+    """
+    argsdoc = {}
+    if func.__doc__:
+        # Sphinx doc format parser
+        m = re.match(
+            r"((?:.|\n)*?)(\n\s*:(?:param|type|raises|return|rtype)(?:.|\n)*)",
+            func.__doc__.strip(),
+        )
+        if not m:
+            desc = func.__doc__.strip()
+        else:
+            desc = m.group(1)
+            sphinxargs = re.findall(
+                r"\s*:(param|type|raises|return|rtype)\s*([^:]*):(.*)",
+                m.group(2),
+            )
+            for argtype, argparam, argdesc in sphinxargs:
+                argparam = argparam.strip()
+                argdesc = argdesc.strip()
+                if argtype == "param":
+                    if not argparam:
+                        raise ValueError(":param: without a name !")
+                    argsdoc[argparam] = argdesc
+    else:
+        desc = ""
+    # Now build the argparse.ArgumentParser
+    parser = argparse.ArgumentParser(
+        prog=func.__name__,
+        description=desc,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    # Process the parameters
+    positional = []
+    for param in inspect.signature(func).parameters.values():
+        if not param.annotation:
+            continue
+        parname = param.name
+        paramkwargs = {}
+        if param.annotation is bool:
+            if param.default is True:
+                parname = "no-" + parname
+                paramkwargs["action"] = "store_false"
+            else:
+                paramkwargs["action"] = "store_true"
+        elif param.annotation in [str, int, float]:
+            paramkwargs["type"] = param.annotation
+        else:
+            continue
+        if param.default != inspect.Parameter.empty:
+            if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                positional.append(param.name)
+                paramkwargs["nargs"] = '?'
+            else:
+                parname = "--" + parname
+            paramkwargs["default"] = param.default
+        else:
+            positional.append(param.name)
+        if param.kind == inspect.Parameter.VAR_POSITIONAL:
+            paramkwargs["action"] = "append"
+        if param.name in argsdoc:
+            paramkwargs["help"] = argsdoc[param.name]
+        parser.add_argument(parname, **paramkwargs)  # type: ignore
+    # Now parse the sys.argv parameters
+    params = vars(parser.parse_args())
+    # Act as in interactive mode
+    conf.logLevel = 20
+    from scapy.themes import DefaultTheme
+    conf.color_theme = DefaultTheme()
+    # And call the function
+    try:
+        func(
+            *[params.pop(x) for x in positional],
+            **{
+                (k[3:] if k.startswith("no_") else k): v
+                for k, v in params.items()
+            }
+        )
+    except AssertionError as ex:
+        print("ERROR: " + str(ex))
+        parser.print_help()
+
+
 #######################
 #   PERIODIC SENDER   #
 #######################