Update README.md

Author: michaelweber

README.md

@@ -1,2 +1,33 @@
 # swarmer
-A tool to convert windows registry export files into windows hive files that can be used to replace NTUSER.MAN
+A tool for sneakily adding registry keys without EDR/AV being able to see what's happening **even if you don't have administrator access**.
+
+# How do I use this?
+Say that you have a registry key you want to add to `HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run` so that on startup it pops calc.
+
+First you need to have a registry dump of the `HKCU` key you would like to use. Ideally this should come from the machine you're intending to modify. You can generate one of these by running `reg export HKCU hkcu.reg`. 
+
+Then you should make the changes to the .reg file you want to see. In our example case we can just open the file in notepad and add an extra line like this:
+
+![Adding an entry to pop calc on startup](https://github.com/user-attachments/assets/549f2e47-5572-4f68-8cd1-efab14198f76)
+
+Next you need to use this tool `swarmer.exe` to transform your modified reg file into a binary registry hive. An example invocation would be:
+
+`swarmer.exe hkcu.reg NTUSER.MAN`
+
+Finally you just need to drop `NTUSER.MAN` (it MUST be called this) into your `%USERPROFILE% directory` (something like `C:\Users\MyUserName`).
+
+The next time the account logs in, your registry changes will be loaded.
+
+# Why does this work?
+
+Windows is full of legacy cruft, this is abusing [Windows Mandatory User Profiles](https://learn.microsoft.com/en-us/windows/client-management/client-tools/mandatory-user-profile). Normally you need to be an admin to rename a user's `NTUSER.DAT` to `NTUSER.MAN`, but there's apparently no protections to make sure that someone doesn't just drop a file there with the same name and have that be used instead.
+
+There's a weird "expected" security boundary that generating a binary windows hive on a machine requires administrator access, but in general this is very loosely enforced. `swarmer` (ab)uses the [Offline Registry API](https://learn.microsoft.com/en-us/windows/win32/devnotes/about-the-offline-registry-library) in order to manipulate a binary registry hive as it parses an exported `.reg` file. To quote the description:
+
+> Applications should not use the offline registry functions to bypass the security requirements of the system registry. To load a hive, an application running without the special privileges required by the RegLoadKey function can use the RegLoadAppKey function.
+
+Well obviously we're not going to listen to that, so now we can use the low privilege registry export combined with our `swarmer` tool to create a "privileged" registry binary object which you can just drop into the right spot to override the existing `NTUSER.DAT` registry hive. 
+
+In the process of doing this we won't use ANY traditional Registry Read/Write APIs so ideally EDR shouldn't have great insight into this process - none of this will show up as an actual registry write according to sysinternals procmon. If you're PARTICULARLY paranoid you can also take the .reg file onto a machine you control, use this tool to create the hive binary file, and drop it back on the host. Once you export the registry there's no need to interact with the host until you drop the NTUSER.MAN file.
+
+Technically you don't even need to export the registry, but it's likely dangerous to try to replace an account's registry with something from another machine that doesn't EXACTLY match the windows environment, and that will be tricky to guarantee.