Add documentation

documentation/modules/auxiliary/admin/smb/change_password.md

@@ -0,0 +1,75 @@
+## Introduction
+
+Allows changing or resetting users' passwords.
+
+"Changing" refers to situations where you know the value of the existing password, and send that to the server as part of the password modification.
+"Resetting" refers to situations where you may not know the value of the existing password, but by virtue of your permissions over the target account, you can force-change the password without necessarily knowing it.
+
+Note that users can typically not reset their own passwords (unless they have very high privileges).
+
+This module works with existing sessions (or relaying), especially for Reset use cases, wherein the target's password is not required.
+
+## Actions
+
+- `RESET` - Reset the target's password without knowing the existing one (requires appropriate permissions)
+- `RESET_NTLM` - Reset the target's NTLM hash, without knowing the existing password. This will not update kerberos keys.
+- `CHANGE` - Change the password, knowing the existing one.
+- `CHANGE_NTLM` - Change the password to a NTLM hash value, knowing the existing password. This will not update kerberos keys.
+
+## Options
+
+The required options are based on the action being performed:
+
+- When resetting a password, you must specify the `TARGET_USER`
+- When changing a password, you must specify the `SMBUser` and `SMBPass`, even if using an existing session (since the API requires both of these to be specified, even for open SMB sessions)
+- When resetting or changing a password, you must specify `NEW_PASSWORD`
+- When resetting or changing an NTLM hash, you must specify `NEW_NTLM`
+
+**SMBUser**
+
+The username to use to authenticate to the server. Required for changing a password, even if using an existing session.
+
+**The LEAKATTEMPTS Option**
+
+Information leaks are used to ensure stability of the exploit. Sometimes they don't pop on the first try.
+
+**The DBGTRACE Option**
+
+Used to debug, gives extremely verbose information.
+
+**The SMBUser Option**
+
+This is a valid Windows username.
+
+**The SMBPass option**
+
+This can be either the plain text version or the Windows hash.
+
+## Scenarios
+
+**Automatic Target**
+
+There are multiple targets available for exploit/windows/smb/psexec. The Automatic target is the default target. If the  Automatic target detects Powershell on the remote machine, it will try Powershell, otherwise it uses the natvie upload. Each target is explained below.
+
+**Powershell Target**
+
+The Powershell target forces the psexec module to run a Powershell command with a payload embedded in it. Since this approach does not leave anything on disk, it is a very powerful way to evade antivirus. However, older Windows machines might not support Powershell by default.
+
+Because of this, you will probably want to use the Automatic target setting. The automatic mode will check if the target supports Powershell before it tries it; the manually set Powershell target won't do that.
+
+**Native Upload Target**
+
+The Native target will attempt to upload the payload (executable) to SYSTEM32 (which can be modified with the
+SHARE datastore option), and then execute it with psexec.
+
+This approach is generally reliable, but has a high chance of getting caught by antivirus on the target. To counter this, you can try to use a template by setting the EXE::Path and EXE::Template datastore options. Or, you can supply your own custom EXE by setting the EXE::Custom option.
+
+**MOF Upload Target**
+
+The [MOF](https://docs.metasploit.com/docs/development/developing-modules/libraries/how-to-use-wbemexec-for-a-write-privilege-attack-on-windows.html) target technically does not use psexec; it does not explicitly tell Windows to execute anything. All it does is upload two files: the payload (exe) in SYSTEM32 and a managed object
+format file in SYSTEM32\wbem\mof\ directory. When Windows sees the MOF file in that directory, it automatically runs it. Once executed, the code inside the MOF file basically tells Windows to execute our payload in SYSTEM32, and you get a session.
+
+Although it's a neat trick, Metasploit's MOF library only works against Windows XP and Windows Server 2003. And since it writes files to disk, there is also a high chance of getting
+caught by antivirus on the target.
+
+The best way to counter antivirus is still the same. You can either use a different template by setting the EXE::Path and EXE::Template datastore options or you can supply your own custom EXE by setting the EXE::Custom option.