Merge pull request Pennyw0rth#321 from Pennyw0rth/marshall-options-fix

Refactor argparse options

Author: Marshall-Hallenbeck

nxc/cli.py

@@ -9,6 +9,7 @@
 from nxc.paths import NXC_PATH
 from nxc.loaders.protocolloader import ProtocolLoader
 from nxc.helpers.logger import highlight
+from nxc.helpers.args import DisplayDefaultsNotNone
 from nxc.logger import nxc_logger, setup_debug_logging
 import importlib.metadata
 
@@ -23,8 +24,29 @@ def gen_cli_args():
         COMMIT = ""
     CODENAME = "nxc4u"
     nxc_logger.debug(f"NXC VERSION: {VERSION} - {CODENAME} - {COMMIT}")
-
-    parser = argparse.ArgumentParser(description=rf"""
+    
+    generic_parser = argparse.ArgumentParser(add_help=False, formatter_class=DisplayDefaultsNotNone)
+    generic_group = generic_parser.add_argument_group("Generic", "Generic options for nxc across protocols")
+    generic_group.add_argument("-t", "--threads", type=int, dest="threads", default=256, help="set how many concurrent threads to use")
+    generic_group.add_argument("--timeout", default=None, type=int, help="max timeout in seconds of each thread")
+    generic_group.add_argument("--jitter", metavar="INTERVAL", type=str, help="sets a random delay between each authentication")
+    
+    output_parser = argparse.ArgumentParser(add_help=False, formatter_class=DisplayDefaultsNotNone)
+    output_group = output_parser.add_argument_group("Output", "Options to set verbosity levels and control output")
+    output_group.add_argument("--verbose", action="store_true", help="enable verbose output")
+    output_group.add_argument("--debug", action="store_true", help="enable debug level information")
+    output_group.add_argument("--no-progress", action="store_true", help="do not displaying progress bar during scan")
+    output_group.add_argument("--log", metavar="LOG", help="export result into a custom file")
+    
+    dns_parser = argparse.ArgumentParser(add_help=False, formatter_class=DisplayDefaultsNotNone)
+    dns_group = dns_parser.add_argument_group("DNS")
+    dns_group.add_argument("-6", dest="force_ipv6", action="store_true", help="Enable force IPv6")
+    dns_group.add_argument("--dns-server", action="store", help="Specify DNS server (default: Use hosts file & System DNS)")
+    dns_group.add_argument("--dns-tcp", action="store_true", help="Use TCP instead of UDP for DNS queries")
+    dns_group.add_argument("--dns-timeout", action="store", type=int, default=3, help="DNS query timeout in seconds")
+    
+    parser = argparse.ArgumentParser(
+        description=rf"""
      .   .
     .|   |.     _   _          _     _____
     ||   ||    | \ | |   ___  | |_  | ____| __  __   ___    ___
@@ -42,62 +64,55 @@ def gen_cli_args():
     {highlight('Version', 'red')} : {highlight(VERSION)}
     {highlight('Codename', 'red')}: {highlight(CODENAME)}
     {highlight('Commit', 'red')}  : {highlight(COMMIT)}
-    """, formatter_class=RawTextHelpFormatter)
-
-    parser.add_argument("-t", type=int, dest="threads", default=256, help="set how many concurrent threads to use (default: 256)")
-    parser.add_argument("--timeout", default=None, type=int, help="max timeout in seconds of each thread (default: None)")
-    parser.add_argument("--jitter", metavar="INTERVAL", type=str, help="sets a random delay between each authentication (default: None)")
-    parser.add_argument("--no-progress", action="store_true", help="Not displaying progress bar during scan")
-    parser.add_argument("--verbose", action="store_true", help="enable verbose output")
-    parser.add_argument("--debug", action="store_true", help="enable debug level information")
-    parser.add_argument("--version", action="store_true", help="Display nxc version")
+    """,
+        formatter_class=RawTextHelpFormatter,
+        parents=[generic_parser, output_parser, dns_parser]
+    )
 
-    dns_parser = parser.add_argument_group("DNS")
-    dns_parser.add_argument("-6", dest="force_ipv6", action="store_true", help="Enable force IPv6")
-    dns_parser.add_argument("--dns-server", action="store", help="Specify DNS server (default: Use hosts file & System DNS)")
-    dns_parser.add_argument("--dns-tcp", action="store_true", help="Use TCP instead of UDP for DNS queries")
-    dns_parser.add_argument("--dns-timeout", action="store", type=int, default=3, help="DNS query timeout in seconds (default: %(default)s)")
+    parser.add_argument("--version", action="store_true", help="Display nxc version")
 
     # we do module arg parsing here so we can reference the module_list attribute below
-    module_parser = argparse.ArgumentParser(add_help=False)
-    mgroup = module_parser.add_mutually_exclusive_group()
+    module_parser = argparse.ArgumentParser(add_help=False, formatter_class=DisplayDefaultsNotNone)
+    mgroup = module_parser.add_argument_group("Modules", "Options for nxc modules")
     mgroup.add_argument("-M", "--module", choices=get_module_names(), action="append", metavar="MODULE", help="module to use")
-    module_parser.add_argument("-o", metavar="MODULE_OPTION", nargs="+", default=[], dest="module_options", help="module options")
-    module_parser.add_argument("-L", "--list-modules", action="store_true", help="list available modules")
-    module_parser.add_argument("--options", dest="show_module_options", action="store_true", help="display module options")
-    module_parser.add_argument("--server", choices={"http", "https"}, default="https", help="use the selected server (default: https)")
-    module_parser.add_argument("--server-host", type=str, default="0.0.0.0", metavar="HOST", help="IP to bind the server to (default: 0.0.0.0)")
-    module_parser.add_argument("--server-port", metavar="PORT", type=int, help="start the server on the specified port")
-    module_parser.add_argument("--connectback-host", type=str, metavar="CHOST", help="IP for the remote system to connect back to (default: same as server-host)")
+    mgroup.add_argument("-o", metavar="MODULE_OPTION", nargs="+", default=[], dest="module_options", help="module options")
+    mgroup.add_argument("-L", "--list-modules", action="store_true", help="list available modules")
+    mgroup.add_argument("--options", dest="show_module_options", action="store_true", help="display module options")
 
-    subparsers = parser.add_subparsers(title="protocols", dest="protocol", description="available protocols")
+    subparsers = parser.add_subparsers(title="Available Protocols", dest="protocol")
 
-    std_parser = argparse.ArgumentParser(add_help=False)
+    std_parser = argparse.ArgumentParser(add_help=False, parents=[generic_parser, output_parser, dns_parser], formatter_class=DisplayDefaultsNotNone)
     std_parser.add_argument("target", nargs="+" if not (module_parser.parse_known_args()[0].list_modules or module_parser.parse_known_args()[0].show_module_options) else "*", type=str, help="the target IP(s), range(s), CIDR(s), hostname(s), FQDN(s), file(s) containing a list of targets, NMap XML or .Nessus file(s)")
-    std_parser.add_argument("-id", metavar="CRED_ID", nargs="+", default=[], type=str, dest="cred_id", help="database credential ID(s) to use for authentication")
-    std_parser.add_argument("-u", metavar="USERNAME", dest="username", nargs="+", default=[], help="username(s) or file(s) containing usernames")
-    std_parser.add_argument("-p", metavar="PASSWORD", dest="password", nargs="+", default=[], help="password(s) or file(s) containing passwords")
-    std_parser.add_argument("--ignore-pw-decoding", action="store_true", help="Ignore non UTF-8 characters when decoding the password file")
-    std_parser.add_argument("-k", "--kerberos", action="store_true", help="Use Kerberos authentication")
-    std_parser.add_argument("--no-bruteforce", action="store_true", help="No spray when using file for username and password (user1 => password1, user2 => password2")
-    std_parser.add_argument("--continue-on-success", action="store_true", help="continues authentication attempts even after successes")
-    std_parser.add_argument("--use-kcache", action="store_true", help="Use Kerberos authentication from ccache file (KRB5CCNAME)")
-    std_parser.add_argument("--log", metavar="LOG", help="Export result into a custom file")
-    std_parser.add_argument("--aesKey", metavar="AESKEY", nargs="+", help="AES key to use for Kerberos Authentication (128 or 256 bits)")
-    std_parser.add_argument("--kdcHost", metavar="KDCHOST", help="IP Address of the domain controller. If omitted it will use the domain part (FQDN) specified in the target parameter")
-
-    fail_group = std_parser.add_mutually_exclusive_group()
-    fail_group.add_argument("--gfail-limit", metavar="LIMIT", type=int, help="max number of global failed login attempts")
-    fail_group.add_argument("--ufail-limit", metavar="LIMIT", type=int, help="max number of failed login attempts per username")
-    fail_group.add_argument("--fail-limit", metavar="LIMIT", type=int, help="max number of failed login attempts per host")
+    credential_group = std_parser.add_argument_group("Authentication", "Options for authenticating")
+    credential_group.add_argument("-u", "--username", metavar="USERNAME", dest="username", nargs="+", default=[], help="username(s) or file(s) containing usernames")
+    credential_group.add_argument("-p", "--password", metavar="PASSWORD", dest="password", nargs="+", default=[], help="password(s) or file(s) containing passwords")
+    credential_group.add_argument("-id", metavar="CRED_ID", nargs="+", default=[], type=str, dest="cred_id", help="database credential ID(s) to use for authentication")
+    credential_group.add_argument("--ignore-pw-decoding", action="store_true", help="Ignore non UTF-8 characters when decoding the password file")
+    credential_group.add_argument("--no-bruteforce", action="store_true", help="No spray when using file for username and password (user1 => password1, user2 => password2)")
+    credential_group.add_argument("--continue-on-success", action="store_true", help="continues authentication attempts even after successes")
+    credential_group.add_argument("--gfail-limit", metavar="LIMIT", type=int, help="max number of global failed login attempts")
+    credential_group.add_argument("--ufail-limit", metavar="LIMIT", type=int, help="max number of failed login attempts per username")
+    credential_group.add_argument("--fail-limit", metavar="LIMIT", type=int, help="max number of failed login attempts per host")
+
+    kerberos_group = std_parser.add_argument_group("Kerberos", "Options for Kerberos authentication")
+    kerberos_group.add_argument("-k", "--kerberos", action="store_true", help="Use Kerberos authentication")
+    kerberos_group.add_argument("--use-kcache", action="store_true", help="Use Kerberos authentication from ccache file (KRB5CCNAME)")
+    kerberos_group.add_argument("--aesKey", metavar="AESKEY", nargs="+", help="AES key to use for Kerberos Authentication (128 or 256 bits)")
+    kerberos_group.add_argument("--kdcHost", metavar="KDCHOST", help="FQDN of the domain controller. If omitted it will use the domain part (FQDN) specified in the target parameter")
+    
+    server_group = std_parser.add_argument_group("Servers", "Options for nxc servers")
+    server_group.add_argument("--server", choices={"http", "https"}, default="https", help="use the selected server")
+    server_group.add_argument("--server-host", type=str, default="0.0.0.0", metavar="HOST", help="IP to bind the server to")
+    server_group.add_argument("--server-port", metavar="PORT", type=int, help="start the server on the specified port")
+    server_group.add_argument("--connectback-host", type=str, metavar="CHOST", help="IP for the remote system to connect back to")    
 
     p_loader = ProtocolLoader()
     protocols = p_loader.get_protocols()
 
     try:
         for protocol in protocols:
             protocol_object = p_loader.load_protocol(protocols[protocol]["argspath"])
-            subparsers = protocol_object.proto_args(subparsers, std_parser, module_parser)
+            subparsers = protocol_object.proto_args(subparsers, [std_parser, module_parser])
     except Exception as e:
         nxc_logger.exception(f"Error loading proto_args from proto_args.py file in protocol folder: {protocol} - {e}")
 

nxc/helpers/args.py

@@ -0,0 +1,10 @@
+from argparse import ArgumentDefaultsHelpFormatter, SUPPRESS, OPTIONAL, ZERO_OR_MORE
+
+class DisplayDefaultsNotNone(ArgumentDefaultsHelpFormatter):
+    def _get_help_string(self, action):
+        help_string = action.help
+        if "%(default)" not in action.help and action.default is not SUPPRESS:
+            defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
+            if (action.option_strings or action.nargs in defaulting_nargs) and action.default:  # Only add default info if it's not None
+                help_string += " (default: %(default)s)"  # NORUFF
+        return help_string

nxc/protocols/ftp/proto_args.py

@@ -1,9 +1,12 @@
-def proto_args(parser, std_parser, module_parser):
-    ftp_parser = parser.add_parser("ftp", help="own stuff using FTP", parents=[std_parser, module_parser])
-    ftp_parser.add_argument("--port", type=int, default=21, help="FTP port (default: 21)")
+from nxc.helpers.args import DisplayDefaultsNotNone
 
-    cgroup = ftp_parser.add_argument_group("FTP Access", "Options for enumerating your access")
-    cgroup.add_argument("--ls", metavar="DIRECTORY", nargs="?", const=".", help="List files in the directory, ex: --ls or --ls Directory")
-    cgroup.add_argument("--get", metavar="FILE", help="Download a file, ex: --get fileName.txt")
-    cgroup.add_argument("--put", metavar=("LOCAL_FILE", "REMOTE_FILE"), nargs=2, help="Upload a file, ex: --put inputFileName.txt outputFileName.txt")
+
+def proto_args(parser, parents):
+    ftp_parser = parser.add_parser("ftp", help="own stuff using FTP", parents=parents, formatter_class=DisplayDefaultsNotNone)
+    ftp_parser.add_argument("--port", type=int, default=21, help="FTP port")
+
+    cgroup = ftp_parser.add_argument_group("File Operations", "Options for enumerating and interacting with files on the target")
+    cgroup.add_argument("--ls", metavar="DIRECTORY", nargs="?", const=".", help="List files in the directory")
+    cgroup.add_argument("--get", metavar="FILE", help="Download a file")
+    cgroup.add_argument("--put", metavar=("LOCAL_FILE", "REMOTE_FILE"), nargs=2, help="Upload a file")
     return parser

nxc/protocols/ldap/proto_args.py

@@ -1,7 +1,10 @@
-def proto_args(parser, std_parser, module_parser):
-    ldap_parser = parser.add_parser("ldap", help="own stuff using LDAP", parents=[std_parser, module_parser])
+from nxc.helpers.args import DisplayDefaultsNotNone
+
+
+def proto_args(parser, parents):
+    ldap_parser = parser.add_parser("ldap", help="own stuff using LDAP", parents=parents, formatter_class=DisplayDefaultsNotNone)
     ldap_parser.add_argument("-H", "--hash", metavar="HASH", dest="hash", nargs="+", default=[], help="NTLM hash(es) or file(s) containing NTLM hashes")
-    ldap_parser.add_argument("--port", type=int, choices={389, 636}, default=389, help="LDAP port (default: 389)")
+    ldap_parser.add_argument("--port", type=int, default=389, help="LDAP port")
     ldap_parser.add_argument("--no-smb", action="store_true", help="No smb connection")
 
     dgroup = ldap_parser.add_mutually_exclusive_group()
@@ -31,6 +34,6 @@ def proto_args(parser, std_parser, module_parser):
     bgroup = ldap_parser.add_argument_group("Bloodhound Scan", "Options to play with Bloodhoud")
     bgroup.add_argument("--bloodhound", action="store_true", help="Perform a Bloodhound scan")
     bgroup.add_argument("-ns", "--nameserver", help="Custom DNS IP")
-    bgroup.add_argument("-c", "--collection", help="Which information to collect. Supported: Group, LocalAdmin, Session, Trusts, Default, DCOnly, DCOM, RDP, PSRemote, LoggedOn, Container, ObjectProps, ACL, All. You can specify more than one by separating them with a comma. (default: Default)'")
+    bgroup.add_argument("-c", "--collection", default="Collection", help="Which information to collect. Supported: Group, LocalAdmin, Session, Trusts, Default, DCOnly, DCOM, RDP, PSRemote, LoggedOn, Container, ObjectProps, ACL, All. You can specify more than one by separating them with a comma")
 
     return parser

nxc/protocols/mssql/proto_args.py

@@ -1,8 +1,11 @@
-def proto_args(parser, std_parser, module_parser):
-    mssql_parser = parser.add_parser("mssql", help="own stuff using MSSQL", parents=[std_parser, module_parser])
+from nxc.helpers.args import DisplayDefaultsNotNone
+
+
+def proto_args(parser, parents):
+    mssql_parser = parser.add_parser("mssql", help="own stuff using MSSQL", parents=parents, formatter_class=DisplayDefaultsNotNone)
     mssql_parser.add_argument("-H", "--hash", metavar="HASH", dest="hash", nargs="+", default=[], help="NTLM hash(es) or file(s) containing NTLM hashes")
-    mssql_parser.add_argument("--port", default=1433, type=int, metavar="PORT", help="MSSQL port (default: 1433)")
-    mssql_parser.add_argument("--mssql-timeout", help="SQL server connection timeout, default is %(default)s seconds", type=int, default=5)
+    mssql_parser.add_argument("--port", default=1433, type=int, metavar="PORT", help="MSSQL port")
+    mssql_parser.add_argument("--mssql-timeout", help="SQL server connection timeout", type=int, default=5)
     mssql_parser.add_argument("-q", "--query", dest="mssql_query", metavar="QUERY", type=str, help="execute the specified query against the MSSQL DB")
 
     dgroup = mssql_parser.add_mutually_exclusive_group()
@@ -23,7 +26,7 @@ def proto_args(parser, std_parser, module_parser):
     psgroup.add_argument("--no-encode", action="store_true", default=False, help="Do not encode the PowerShell command ran on target")
 
     tgroup = mssql_parser.add_argument_group("Files", "Options for put and get remote files")
-    tgroup.add_argument("--put-file", nargs=2, metavar=("SRC_FILE", "DEST_FILE"), help="Put a local file into remote target, ex: whoami.txt C:\\Windows\\Temp\\whoami.txt")
-    tgroup.add_argument("--get-file", nargs=2, metavar=("SRC_FILE", "DEST_FILE"), help="Get a remote file, ex: C:\\Windows\\Temp\\whoami.txt whoami.txt")
+    tgroup.add_argument("--put-file", nargs=2, metavar=("SRC_FILE", "DEST_FILE"), help="Put a local file into remote target, ex: whoami.txt C:\\\\Windows\\\\Temp\\\\whoami.txt")
+    tgroup.add_argument("--get-file", nargs=2, metavar=("SRC_FILE", "DEST_FILE"), help="Get a remote file, ex: C:\\\\Windows\\\\Temp\\\\whoami.txt whoami.txt")
 
     return parser

nxc/protocols/rdp/proto_args.py

@@ -1,8 +1,11 @@
-def proto_args(parser, std_parser, module_parser):
-    rdp_parser = parser.add_parser("rdp", help="own stuff using RDP", parents=[std_parser, module_parser])
+from nxc.helpers.args import DisplayDefaultsNotNone
+
+
+def proto_args(parser, parents):
+    rdp_parser = parser.add_parser("rdp", help="own stuff using RDP", parents=parents, formatter_class=DisplayDefaultsNotNone)
     rdp_parser.add_argument("-H", "--hash", metavar="HASH", dest="hash", nargs="+", default=[], help="NTLM hash(es) or file(s) containing NTLM hashes")
-    rdp_parser.add_argument("--port", type=int, default=3389, help="Custom RDP port")
-    rdp_parser.add_argument("--rdp-timeout", type=int, default=5, help="RDP timeout on socket connection, defalut is %(default)ss")
+    rdp_parser.add_argument("--port", type=int, default=3389, help="RDP port")
+    rdp_parser.add_argument("--rdp-timeout", type=int, default=5, help="RDP timeout on socket connection")
     rdp_parser.add_argument("--nla-screenshot", action="store_true", help="Screenshot RDP login prompt if NLA is disabled")
 
     dgroup = rdp_parser.add_mutually_exclusive_group()
@@ -11,7 +14,7 @@ def proto_args(parser, std_parser, module_parser):
 
     egroup = rdp_parser.add_argument_group("Screenshot", "Remote Desktop Screenshot")
     egroup.add_argument("--screenshot", action="store_true", help="Screenshot RDP if connection success")
-    egroup.add_argument("--screentime", type=int, default=10, help="Time to wait for desktop image, default is %(default)ss")
-    egroup.add_argument("--res", default="1024x768", help='Resolution in "WIDTHxHEIGHT" format. Default: "1024x768"')
+    egroup.add_argument("--screentime", type=int, default=10, help="Time to wait for desktop image")
+    egroup.add_argument("--res", default="1024x768", help="Resolution in WIDTHxHEIGHT format")
 
     return parser