mimilib Reference Guide
mimilib is built as a Windows DLL that exposes a collection of security instrumentation entry points for authentication, networking, and debugging components. The export list shows the callable surfaces that Windows will bind when the library is registered as a Security Support Provider, password filter, DHCP/DNS plug-in, WinDbg extension, credential provider shim, or helper DLL invoked through rundll32.【F:mimilib/mimilib.def†L1-L29】 Each exported routine writes detailed traces to disk via the shared logging helpers in utils.c, which format Unicode data, hex-encode binary blobs, and normalize SIDs so the captured information stays readable.【F:mimilib/utils.c†L8-L48】 The sections below document how to build, deploy, and use every command-style export, the arguments they accept, and the flags that tailor their behaviour.
mimikatz.sln in Visual Studio, select the desired architecture, and run Build → Build Solution to produce mimilib.dll alongside the main executable.【F:README.md†L107-L110】_build_.cmd warnings about mimidrv if you do not have the WinDDK installed—the driver is optional and does not affect mimilib output.【F:README.md†L110-L110】Why:
mimiliblinks tightly with Windows security subsystems, so you must compile it with the matching Visual Studio toolsets that understand those headers and calling conventions.
Because mimilib is not a standalone executable, each export must be registered with the Windows feature it targets:
startW) – Copy mimilib.dll to a writable location and run rundll32 mimilib.dll,startW "<command line>" to spawn a child process under a restricted token. This entry point accepts the command line as its sole argument and uses CreateRestrictedToken to strip privileges before delegating to CreateProcessAsUser, providing a quick way to sandbox a payload.【F:mimilib/kappfree.c†L8-L31】 Use it when you want to observe or log behaviour under limited rights without creating an explicit local account.%SystemRoot%\System32 and add mimilib to the Security Packages list (typically via HKLM\SYSTEM\CurrentControlSet\Control\Lsa). Windows will call SpLsaModeInitialize, which returns a function table whose SpAcceptCredentials hook logs every domain, username, logon type, and password captured by LSASS into kiwissp.log.【F:mimilib/kssp.c†L8-L60】 Deploy this when you need full credential telemetry during interactive or service logons.InitializeChangeNotify / PasswordChangeNotify) – Register mimilib under HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages to have PasswordChangeNotify invoked after a password change. The function appends the relative ID, account name, and plaintext or hashed password to kiwifilter.log.【F:mimilib/kfilt.c†L8-L27】 Use it to audit account hygiene or to intercept domain password rotations.DhcpServerCalloutEntry) – Copy mimilib.dll beside the DHCP server binaries and declare it in the server callout DLL list. The entry point dynamically chains to any existing callout, saves the original DhcpNewPktHook, and replaces it with kdhcp_DhcpNewPktHook. That hook drops requests from the VMware and Hyper-V OUI ranges defined in macToBlack, returning DHCP_DROP_INVALID to silently ignore them.【F:mimilib/kdhcp.c†L8-L56】 Enable this filter when you want to blacklist lab hypervisor MAC prefixes from receiving leases.DnsPluginInitialize / DnsPluginQuery) – Register the DLL via the DNS Server’s plug-in configuration. The query callback just logs each requested name and record type to kiwidns.log while returning success.【F:mimilib/kdns.c†L8-L29】 Use it to inventory live DNS traffic without modifying resolution.NPLogonNotify / NPGetCaps) – Place the DLL where the Multiple Provider Router can load it and add an entry under HKLM\SYSTEM\CurrentControlSet\Control\NetworkProvider\Order. NPLogonNotify records each interactive logon (domain, username, password) to kiwinp.log, then suppresses any logon script, while NPGetCaps reports credential-manager capabilities so the provider is invoked during logon.【F:mimilib/knp.c†L8-L44】 Choose this path when you need early credential capture in workstation sessions.Msv1_0SubAuthenticationRoutine) – Register the DLL as a sub-authentication package (e.g., under HKLM\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0). Each logon attempt is logged to kiwisub.log; if the NT hash matches the hard-coded value for the password Waza1234/admin or the user reaches four bad attempts, the routine escalates the primary group to Domain Admins (RID 512) before returning success.【F:mimilib/ksub.c†L13-L38】 Deploy this when testing sub-auth package abuse or reproducing Golden Ticket-style privilege tweaks.DllGetClassObject / DllCanUnloadNow) – Import and register the COM class IDs shown below to have Windows instantiate mimilib instead of the default password provider. The shim patches GetCredentialAt and GetSerialization so that decrypted credentials from the UI are written to kcredentialprovider.log before being passed back to Windows.【F:mimilib/kcredentialprovider.c†L13-L318】 Use this when you need to intercept Winlogon credentials without patching LogonUI.exe directly.ExtensionApiVersion, WinDbgExtensionDllInit, coffee, mimikatz) – Copy the DLL into WinDbg’s extension search path and run !mimikatz or !coffee. Initialization prints guided usage for both kernel and user mode and caches the target build number for symbol resolution.【F:mimilib/sekurlsadbg/kwindbg.c†L18-L200】 Use these commands during live debugging of LSASS to dump logon sessions and credentials.The credential provider registration script is embedded directly in the source for convenience—you can import the following .reg file to enable the shim and delete the same keys to remove it.【F:mimilib/kcredentialprovider.c†L13-L47】
mimilib exposes two WinDbg commands:
| Command | Arguments | Description | Why use it |
|---|---|---|---|
!coffee |
none | Prints an ASCII-art coffee cup to verify the extension loaded correctly.【F:mimilib/sekurlsadbg/kwindbg.c†L78-L81】 | Quick smoke test that symbol resolution and DLL loading succeeded. |
!mimikatz |
none | Enumerates LSASS logon sessions, displays metadata (LUID, session, logon server, SID), dumps credential material for each security package listed in packages[], outputs KRBTGT keys, trust information, and DPAPI backup keys.【F:mimilib/sekurlsadbg/kwindbg.c†L58-L200】【F:mimilib/sekurlsadbg/kwindbg.c†L118-L200】 |
Performs an in-debugger version of sekurlsa::logonpasswords without running the full mimikatz EXE—ideal when you already have a kernel or user-mode debugger attached. |
The behaviour of !mimikatz is governed by bitwise flags defined in kwindbg.h:
KUHL_SEKURLSA_CREDS_DISPLAY_CREDENTIAL and its PRIMARY / CREDENTIALKEY mask choose whether decrypted MSV credentials or DPAPI master keys are printed.【F:mimilib/sekurlsadbg/kwindbg.h†L15-L23】 Use these when you only care about one credential type.KUHL_SEKURLSA_CREDS_DISPLAY_KERBEROS_10, KEY_LIST, CREDMANPASS, PINCODE, and KERBEROS_10_1607 toggle Kerberos ticket decryption, key lists, Credential Manager blobs, smart card PINs, and Windows 10 1607+ ISO container decoding respectively.【F:mimilib/sekurlsadbg/kwindbg.h†L24-L28】 Enable the relevant flag to expand !mimikatz output for the package you are investigating.KUHL_SEKURLSA_CREDS_DISPLAY_NODECRYPT suppresses calls to LsaUnprotectMemory, allowing you to inspect encrypted buffers; WPASSONLY hides passwords and only shows metadata; DOMAIN prints domain names even when not decrypted; and SSP marks supplemental credentials captured from SSP packages.【F:mimilib/sekurlsadbg/kwindbg.h†L30-L33】 Use these to tailor output for forensic cleanliness or when decryption APIs are unavailable in your debugging context.Internally the package-specific callbacks select the appropriate combination of these flags based on the Windows build, so most users can run !mimikatz with no arguments. Advanced users can extend the extension to honour custom command-line switches by checking these flag constants.
Every component writes to a dedicated UTF-16 log file in the working directory:
kiwissp.log – LSASS credential captures from KiwiSSP.【F:mimilib/kssp.c†L38-L51】kiwifilter.log – Password change notifications.【F:mimilib/kfilt.c†L13-L27】kiwidns.log – DNS queries intercepted by the plug-in.【F:mimilib/kdns.c†L18-L29】kiwinp.log – Network provider logon data.【F:mimilib/knp.c†L8-L22】kiwisub.log – MSV1_0 sub-authentication decisions.【F:mimilib/ksub.c†L13-L38】kcredentialprovider.log – Winlogon credential serialization dumps.【F:mimilib/kcredentialprovider.c†L55-L117】kiwidns.log, kiwifilter.log, and other loggers rely on klog_password to detect whether the data is human-readable or binary and adapt the output format accordingly.【F:mimilib/utils.c†L20-L39】Why: Consolidating logs makes it easy to correlate events across subsystems and to feed the output into further analysis or exfiltration tooling.
Using mimilib requires administrative control over the host and should be limited to authorised testing environments. Many exports alter sensitive authentication flows (for example, ksub escalates group membership and the credential provider shim stores plaintext passwords). Always explain to stakeholders why you are enabling a component and disable it promptly after testing.