added comment lines

Signed-off-by: termanix <50464194+termanix@users.noreply.github.com>

Author: termanix

nxc/modules/change-password.py

@@ -42,7 +42,9 @@ def options(self, context, module_options):
             sys.exit(1)
 
     def authenticate(self, context, connection, protocol, anonymous=False):
+        # Authenticate to the target using DCE/RPC with either user credentials or a null session. Establishes a connection and binds to the SAMR service.
         try:
+            # Map to the SAMR endpoint on the target
             string_binding = epm.hept_map(connection.host, samr.MSRPC_UUID_SAMR, protocol=protocol)
             rpctransport = transport.DCERPCTransportFactory(string_binding)
             rpctransport.setRemoteHost(connection.host)
@@ -62,6 +64,7 @@ def authenticate(self, context, connection, protocol, anonymous=False):
                 )
                 context.log.info(f"Connecting as {connection.domain}\\{connection.username}")
 
+            # Connect to the DCE/RPC endpoint and bind to the SAMR service
             dce = rpctransport.get_dce_rpc()
             dce.connect()
             context.log.info("[+] Successfully connected to DCE/RPC")
@@ -79,6 +82,7 @@ def on_login(self, context, connection):
 
         new_lmhash, new_nthash = "", ""
 
+        # Parse new hash values if provided
         if self.newhash:
             try:
                 new_lmhash, new_nthash = self.newhash.split(":")
@@ -89,6 +93,7 @@ def on_login(self, context, connection):
             self.anonymous = False
             self.dce = self.authenticate(context, connection, protocol="ncacn_np", anonymous=self.anonymous)
         except Exception as e:
+            # Handle specific errors like password expiration or must be change
             if "STATUS_PASSWORD_MUST_CHANGE" in str(e) or "STATUS_PASSWORD_EXPIRED" in str(e):
                 context.log.warning("Password must be changed. Trying with null session.")
                 self.anonymous = True
@@ -100,29 +105,33 @@ def on_login(self, context, connection):
                 raise
 
         try:
+            # Perform the SMB SAMR password change
             self._smb_samr_change(context, connection, target_username, target_domain, self.oldhash, self.newpass, new_nthash)
         except Exception as e:
             context.log.error(f"Password change failed: {e}")
 
     def _smb_samr_change(self, context, connection, target_username, target_domain, oldHash, newPassword, newHash):
         try:
             if not self.anonymous:
-                server_handle = samr.hSamrConnect(self.dce, connection.host + "\x00")["ServerHandle"]
+                # Connect to the target server and retrieve handles
+                server_handle = samr.hSamrConnect(self.dce, connection.host + "\x00")["ServerHandle"]  # Does not work for null session auth.
                 domain_sid = samr.hSamrLookupDomainInSamServer(self.dce, server_handle, target_domain)["DomainId"]
                 domain_handle = samr.hSamrOpenDomain(self.dce, server_handle, domainId=domain_sid)["DomainHandle"]
                 user_rid = samr.hSamrLookupNamesInDomain(self.dce, domain_handle, (target_username,))["RelativeIds"]["Element"][0]
                 user_handle = samr.hSamrOpenUser(self.dce, domain_handle, userId=user_rid)["UserHandle"]
 
                 if self.reset:
+                    # Change the password with new password hash
                     samr.hSamrSetNTInternal1(self.dce, user_handle, newPassword, newHash)
                     context.log.success(f"Successfully changed password for {target_username}")
                 else:
-                    
+                    # Change the password with new password
                     samr.hSamrUnicodeChangePasswordUser2(
                         self.dce, "\x00", target_username, self.oldpass, newPassword, "", ""
                     )
                     context.log.success(f"Successfully changed password for {target_username}")
             else:
+                # Handle anonymous/null session password change
                 self.mustchangePassword(target_username, target_domain, self.oldpass, newPassword, "", oldHash, "", newHash)
         except Exception as e:
             context.log.fail(f"SMB-SAMR password change failed: {e}")
@@ -131,11 +140,14 @@ def _smb_samr_change(self, context, connection, target_username, target_domain,
 
     def mustchangePassword(self, target_username, targetDomain, oldPassword, newPassword, oldPwdHashLM, oldPwdHashNT, newPwdHashLM, newPwdHashNT):
         if newPassword and oldPassword:
+            # Change password using old and new plaintext passwords
             samr.hSamrUnicodeChangePasswordUser2(self.dce, "\x00", target_username, oldPassword, newPassword, "", "")
             self.context.log.success(f"Successfully changed password for {target_username}")
         elif newPassword and oldPwdHashNT: 
+            # Change password using hash for authentication
             samr.hSamrUnicodeChangePasswordUser2(self.dce, "\x00", target_username, oldPassword, newPassword, "", oldPwdHashNT)
             self.context.log.success(f"Successfully changed password for {target_username}")
         else:
+            # Use NT internal function to set new password or hash
             samr.hSamrSetNTInternal1(self.dce, target_username, newPassword, newPwdHashNT)
             self.context.log.success(f"Successfully changed password for {target_username}")