Merge pull request #1 from PhrozenIO/dev

This version includes global improvements to the code, structure, and logic. The most notable addition is support for input/output redirection through reverse shell, allowing interaction with an interactive spawned process without needing access to the desktop (e.g., via SSH or WinRM).

README.md

@@ -1,100 +1,109 @@
-# PowerRunAsSystem
+**PowerRunAsSystem** is a PowerShell script, also available as an installable module through the PowerShell Gallery, designed to impersonate the **NT AUTHORITY/SYSTEM** user and execute commands or launch interactive processes without relying on third-party tools. It achieves this using only native Windows build-in features.
 
-Run application as system with interactive system process support (active Windows session)
+Traditionally, elevating privileges to the SYSTEM user from an administrator account requires using tools like [PsExec from Sysinternals](https://learn.microsoft.com/en-us/sysinternals/downloads/psexec) or creating a custom service. With PowerRunAsSystem, you can accomplish the same goal using the built-in Windows Task Scheduler, eliminating the need for external utilities.
 
-This technique doesn't rely on any external tools and doesn't require a Microsoft Service.
+This tool allows you to:
 
-It spawns an `NT Authority/System` process using the Microsoft Windows Task Scheduler then upgrade to Interactive System Process using cool WinApi's (Run in Active Windows Session)
+* Impersonate the SYSTEM user in the current terminal session
+* Run non-interactive commands as SYSTEM
+* Launch a new interactive process as SYSTEM (tied to the active terminal session)
 
-![demo](https://user-images.githubusercontent.com/2520298/155295069-3c916877-e5c9-4e8d-a6dd-f13cb3d15f52.png)
+In cases where graphical access to the machine is unavailable, you can redirect the input/output of the spawned SYSTEM process to a listener (e.g., a Netcat listener) for interaction.
 
----
+> It’s important to note that administrative privileges are required to spawn a SYSTEM process in a standard configuration. Ensure that you either access a remote terminal (e.g., SSH or WinRM) with administrative rights or open a new terminal with elevated privileges (Run as Administrator).
 
-## Install
+## Exported Functions
 
-You can install this module very easily using PowerShell Gallery:
+* `Invoke-SystemCommand`
+* `Invoke-InteractiveSystemProcess`
+* `Invoke-ImpersonateSystem`
+* `Invoke-RevertToSelf`
+
+## Installation
+
+### PowerShell Gallery (Recommended)
+
+The following commands for the installation process may require privileges (e.g., Administrative rights, appropriate Execution Policy settings). Ensure that you understand and meet these requirements before proceeding.
 
 ```powershell
 Install-Module -Name PowerRunAsSystem
+Import-Module -Name PowerRunAsSystem
 ```
 
-You might need to execute bellow command to allow unsigned script to be executed:
+### Importing as a Script
 
 ```powershell
-Set-ExecutionPolicy -ExecutionPolicy Unrestricted
+IEX(Get-Content .\PowerRunAsSystem.ps1 -Raw -Encoding UTF8)
 ```
 
-If you don't want to use PowerShell Gallery, you can install and import this module manually and/or use it as script.
-
 ## Usage
 
-⚠️ All commands requires **Administrator Privilege**. 
+### `Invoke-SystemCommand`
 
-### Invoke-SystemCommand
+Spawn a new process as the SYSTEM user via Task Scheduler. Note that the SYSTEM process will not be tied to the active terminal session, meaning it won’t be interactive. This is useful for quickly running commands as SYSTEM without needing direct interaction with the process.
 
-```PowerShell
-Invoke-SystemCommand -Execute "powershell.exe" -Argument "whoami \| Out-File C:\result.txt"
-```
+#### ⚙️ Available Arguments
 
-Create a new process (default: `powershell.exe`) running under the context of `NT AUTHORITY/SYSTEM` in Microsoft Windows session id `0`
+| Parameter               | Type             | Default                                        | Description                |
+|-------------------------|------------------|------------------------------------------------|----------------------------|
+| Application             | String           | powershell.exe                                 | Program to execute         |
+| Argument                | String           | -Command "whoami \| Out-File C:\result.txt"    | Optional program arguments |
 
-⚠️ Notice: Session id `0` is not directly accessible through your active desktop, any process running under another session than the active one wont be visible. If you want to spawn a new SYSTEM process under active session, use `Invoke-InteractiveSystemPowerShell` command instead.
+⚠️ You cannot run this function if current thread is impersonating another user. Use `Invoke-RevertToSelf` first.
 
-##### ⚙️ Supported Options:
+### `Invoke-InteractiveSystemProcess`
 
-| Parameter               | Type             | Default                                        | Description  |
-|-------------------------|------------------|------------------------------------------------|--------------|
-| Execute                 | String           | powershell.exe                                 | Program to execute as SYSTEM (Session `0`)  |
-| Argument                | String           | -Command "whoami \| Out-File C:\result.txt"    | Optional argument to run with program |
+Spawn a new interactive process as the SYSTEM user, which will be tied to the active terminal session and, if selected, visible on the current desktop.
 
-⚠️ You cannot run this function if current thread is impersonating another user. Use `Invoke-RevertToSelf` first.
+This can be particularly useful in scenarios where an interactive SYSTEM process is needed. For instance, when using [Arcane Server](https://github.com/PhrozenIO/ArcaneServer), running it as an interactive SYSTEM process allows you to capture both the desktop and LogonUI/UAC prompts.
 
----
+![Interactive System Process](images/InteractiveSystem.png)
 
-### Invoke-InteractiveSystemPowerShell
+#### ⚙️ Available Arguments
 
-```PowerShell
-Invoke-InteractiveSystemPowerShell
-```
+| Parameter               | Type             | Default                                        | Description                      |
+|-------------------------|------------------|------------------------------------------------|----------------------------------|
+| CommandLine             | String           | powershell.exe                                 | The complete command line to execute. |
+| Hide                    | Switch           | None                                           | If present, the process is not visible. |
+| RedirectKind            | Choice           | None                                           | If the process input/output needs to be redirected to an external source (as discussed below)… |
+| Address                 | String           | None                                           | Used if the **RedirectKind** is set (as described below). |
+| Port                    | Int (R: 0-65535) | None                                           | Used if the **RedirectKind** is set (as described below). |
 
-Create a new **PowerShell** instance running under the context of `NT AUTHORITY/SYSTEM` and visible on your desktop (active session)
+#### Advanced Usage : RedirectKind Flag
 
-⚠️ You cannot run this function if current thread is impersonating another user. Use `Invoke-RevertToSelf` first.
+##### `None` (Default)
 
-### Invoke-ImpersonateSystem
+No specific redirection is used; the process is spawned normally. To interact with the process, you must do so through the desktop.
 
-```PowerShell
-Invoke-ImpersonateSystem
-```
+##### `Reverse`
 
-Impersonate **SYSTEM User** on current thread (current PowerShell thread) using **ImpersonateNamedPipeClient** technique.
+The `stdout`, `stderr`, and `stdin` of the process are redirected to a network socket in reverse mode (client -> server). This setup enables interaction with the spawned process without requiring access to the desktop, which is particularly useful when the process is initiated from an SSH or WinRM session.
 
-After impersonating user, you can use `Invoke-ImpersonatedProcess` to spawn an interactive process as SYSTEM.
+Example:
 
-### Invoke-ImpersonatedProcess
+Create a new Netcat listener (adapt the command according to your operating system and version of Netcat):
+````bash
+nc -l 4444
+````
 
-```PowerShell
-Invoke-ImpersonatedProcess
-```
+Then, spawn your interactive SYSTEM process:
 
-Create a new **PowerShell** instance running under the context of `NT AUTHORITY/SYSTEM` and visible on your desktop (active session)
+````powershell
+Invoke-InteractiveSystemProcess -RedirectKind "Reverse" -Address "127.0.0.1" -Port 4444
+````
 
-##### ⚙️ Supported Options:
+Enjoy your SYSTEM shell 🐚
 
-| Parameter               | Type             | Default                                        | Description  |
-|-------------------------|------------------|------------------------------------------------|--------------|
-| CommandLine             | String           | powershell.exe                                 | Program to execute as SYSTEM (Active Session)  |
+![Reverse Interactive SYSTEM Shell](images/ReverseInteractive.png)
 
-### Invoke-RevertToSelf
+### `Invoke-ImpersonateSystem`
 
-```PowerShell
-Invoke-RevertToSelf
-```
+Impersonate the SYSTEM user within the current terminal session.
 
-Stop impersonating user.
+![RevertToSelf](images/ImpersonateSystem.png)
 
-⚠️ You cannot run this function if you are not currently impersonating a user. Use `Invoke-ImpersonateSystem` first.
+### `Invoke-RevertToSelf`
 
-## Future Ideas
+Stop user impersonation
 
-- Redirect Stdin and Stdout/Stderr to caller (Administrator <--> System).
+![RevertToSelf](images/RevertToSelf.png)