Added documentation

p0dalirius · Jun 2, 2024 · 509ed1e · 509ed1e
1 parent fb80132
commit 509ed1e
Show file tree

Hide file tree

Showing 27 changed files with 13,108 additions and 238 deletions.
diff --git a/documentation/index.html b/documentation/index.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./smbclientng.html"/>
+</head>
+</html>
diff --git a/documentation/search.js b/documentation/search.js
diff --git a/documentation/smbclientng.html b/documentation/smbclientng.html
diff --git a/documentation/smbclientng/core.html b/documentation/smbclientng/core.html
diff --git a/documentation/smbclientng/core/CommandCompleter.html b/documentation/smbclientng/core/CommandCompleter.html
diff --git a/documentation/smbclientng/core/Config.html b/documentation/smbclientng/core/Config.html
diff --git a/documentation/smbclientng/core/InteractiveShell.html b/documentation/smbclientng/core/InteractiveShell.html
diff --git a/documentation/smbclientng/core/LocalFileIO.html b/documentation/smbclientng/core/LocalFileIO.html
diff --git a/documentation/smbclientng/core/Module.html b/documentation/smbclientng/core/Module.html
diff --git a/documentation/smbclientng/core/ModuleArgumentParser.html b/documentation/smbclientng/core/ModuleArgumentParser.html
diff --git a/documentation/smbclientng/core/SMBSession.html b/documentation/smbclientng/core/SMBSession.html
diff --git a/documentation/smbclientng/core/utils.html b/documentation/smbclientng/core/utils.html
diff --git a/documentation/smbclientng/modules.html b/documentation/smbclientng/modules.html
diff --git a/documentation/smbclientng/modules/Find.html b/documentation/smbclientng/modules/Find.html
diff --git a/run-tests.py b/run-tests.py
diff --git a/smbclientng/__main__.py b/smbclientng/__main__.py
@@ -52,6 +52,22 @@ def parseArgs():
 
 
 def main():
+    """
+    Main function to execute the smbclient-ng tool.
+
+    This function handles the command-line arguments, initializes the SMB session,
+    and starts the interactive shell. It also manages the authentication process
+    using either password or hashes, and sets up the session configuration based
+    on the provided command-line options.
+
+    If Kerberos authentication is specified, it ensures that the KDC host is provided.
+    It exits with an error message if necessary conditions are not met for the session
+    to start properly.
+
+    The function also handles debug mode outputs and exits cleanly, providing feedback
+    about the session termination if debug mode is enabled.
+    """
+
     options = parseArgs()
 
     # Parse hashes

diff --git a/smbclientng/core/Config.py b/smbclientng/core/Config.py
@@ -8,6 +8,21 @@
 
 
 class Config(object):
+    """
+    Configuration handler for smbclientng.
+
+    This class manages the configuration settings for the smbclientng tool, including debug and color output settings.
+    It provides a structured way to access and modify these settings throughout the application.
+
+    Attributes:
+        _debug (bool): Flag to enable or disable debug mode.
+        _no_colors (bool): Flag to enable or disable colored output, depending on the platform.
+
+    Methods:
+        debug: Property to get or set the debug mode.
+        no_colors: Property to get or set the colored output preference.
+    """
+
     def __init__(self, debug=False, no_colors=None):
         self._debug = debug
 

diff --git a/smbclientng/core/InteractiveShell.py b/smbclientng/core/InteractiveShell.py
@@ -608,6 +608,8 @@ def command_use(self, arguments, command):
     # Private functions =======================================================
 
     def __load_modules(self):
+
+
         self.modules.clear()
 
         modules_dir = os.path.normpath(os.path.dirname(__file__) + os.path.sep + ".." + os.path.sep + "modules")
@@ -640,6 +642,17 @@ def __load_modules(self):
             self.commandCompleterObject.commands["module"]["subcommands"] = list(self.modules.keys())
 
     def __prompt(self):
+        """
+        Prints the command prompt for the interactive shell.
+
+        This method constructs and returns the command prompt string based on the current state of the SMB session.
+        The prompt indicates the connection status with a visual symbol and displays the current working directory
+        or the SMB share path. The prompt appearance changes based on whether colors are enabled in the configuration.
+
+        Returns:
+            str: The formatted command prompt string.
+        """
+
         self.smbSession.ping_smb_session()
         if self.smbSession.connected:
             if self.config.no_colors:

diff --git a/smbclientng/core/ModuleArgumentParser.py b/smbclientng/core/ModuleArgumentParser.py
@@ -8,9 +8,32 @@
 import argparse
 import sys
 
+
 class ModuleArgumentParser(argparse.ArgumentParser):
+    """
+    A custom argument parser for handling module-specific command-line arguments in the smbclientng application.
+
+    This class extends the argparse.ArgumentParser and provides custom error handling specific to the needs of smbclientng modules.
+    It is designed to provide clear and user-friendly command-line interfaces for various modules within the smbclientng suite.
+
+    Attributes:
+        None
+
+    Methods:
+        error(message: str):
+            Overrides the default error handling to provide a more informative error message and display the help text.
+    """
 
     def error(self, message):
+        """
+        Overrides the default error handling of argparse.ArgumentParser to provide a custom error message and help display.
+
+        This method is called when ArgumentParser encounters an error. It writes the error message to stderr,
+        displays the help message, and then exits the program with a status code of 2.
+
+        Args:
+            message (str): The error message to be displayed.
+        """
+
         sys.stderr.write('[!] Error: %s\n' % message)
-        self.print_help()
-        #sys.exit(2)
+        self.print_help()
diff --git a/smbclientng/core/utils.py b/smbclientng/core/utils.py
@@ -12,9 +12,27 @@
 import stat
 
 
-# Extracted from p0dalirius/sectools library
-# Src: https://github.com/p0dalirius/sectools/blob/7bb3f5cb7815ad4d4845713c8739e2e2b0ea4e75/sectools/windows/crypto.py#L11-L24
 def parse_lm_nt_hashes(lm_nt_hashes_string):
+    """
+    Parse the input string containing LM and NT hash values and return them separately.
+
+    This function takes a string containing LM and NT hash values, typically separated by a colon (:).
+    It returns the LM and NT hash values as separate strings. If only one hash value is provided, it is
+    assumed to be the NT hash and the LM hash is set to its default value. If no valid hash values are
+    found, both return values are empty strings.
+
+    Args:
+        lm_nt_hashes_string (str): A string containing LM and NT hash values separated by a colon.
+
+    Returns:
+        tuple: A tuple containing two strings (lm_hash_value, nt_hash_value).
+               - lm_hash_value: The LM hash value or its default if not provided.
+               - nt_hash_value: The NT hash value or its default if not provided.
+    
+    Extracted from p0dalirius/sectools library
+    Src: https://github.com/p0dalirius/sectools/blob/7bb3f5cb7815ad4d4845713c8739e2e2b0ea4e75/sectools/windows/crypto.py#L11-L24
+    """
+
     lm_hash_value, nt_hash_value = "", ""
     if lm_nt_hashes_string is not None:
         matched = re.match("([0-9a-f]{32})?(:)?([0-9a-f]{32})?", lm_nt_hashes_string.strip().lower())
@@ -44,6 +62,7 @@ def b_filesize(l):
     Returns:
         str: A string representing the file size in a more readable format, including the appropriate unit.
     """
+
     units = ['B','kB','MB','GB','TB','PB']
     for k in range(len(units)):
         if l < (1024**(k+1)):
@@ -67,6 +86,7 @@ def unix_permissions(entryname):
              three groups of 'r', 'w', 'x' (read, write, execute permissions) for owner, group,
              and others respectively.
     """
+
     mode = os.lstat(entryname).st_mode
     permissions = []
 
@@ -182,6 +202,17 @@ def windows_ls_entry(entry, config, pathToPrint=None):
 
 
 def local_tree(path, config):
+    """
+    This function recursively lists the contents of a directory in a tree-like format.
+
+    Parameters:
+        path (str): The path to the directory to list.
+        config (object): Configuration settings which may affect the output, such as whether to use colors.
+
+    Returns:
+        None: This function does not return anything but prints the directory tree to the console.
+    """
+
     def recurse_action(base_dir="", path=[], prompt=[]):
         bars = ["│   ", "├── ", "└── "]
 

diff --git a/smbclientng/modules/Find.py b/smbclientng/modules/Find.py
@@ -24,6 +24,18 @@ class Find(Module):
     description = "Search for files in a directory hierarchy"
 
     def parseArgs(self, arguments):
+        """
+        Parses the command line arguments provided to the module.
+
+        This method initializes the argument parser with the module's name and description, and defines all the necessary arguments that the module accepts. It then parses the provided command line arguments based on these definitions.
+
+        Args:
+            arguments (str): A string of command line arguments.
+
+        Returns:
+            ModuleArgumentParser.Namespace | None: The parsed arguments as a Namespace object if successful, None if there are no arguments or help is requested.
+        """
+
         parser = ModuleArgumentParser(prog=self.name, description=self.description)
 
         # Adding positional arguments

diff --git a/smbclientng/tests/__init__.py b/smbclientng/tests/__init__.py
diff --git a/smbclientng/tests/common.py b/smbclientng/tests/common.py
diff --git a/smbclientng/tests/run-tests.py b/smbclientng/tests/run-tests.py
diff --git a/smbclientng/tests/test_SMBSession.py b/smbclientng/tests/test_SMBSession.py