docs: elevation in new window

docs/docs/credentials-cache.md

@@ -40,7 +40,9 @@ gsudo command3 # Elevation without popup
 gsudo cache off # (or gsudo -k) Ends the cache session. Next elevation will show a UAC popup.
 ```
 
-- **Disabled:** Every elevation request shows a UAC popup. Attempts to start a Cache Session throws error. 
+- **Disabled:** Every elevation request shows a UAC popup. Attempts to start a Cache Session throws error.
+
+---
 
 Use `gsudo cache on|off` to start/stop a cache session manually (i.e. allow/disallow elevation of the current process with no additional UAC popups).
 

docs/docs/intro.md

@@ -20,15 +20,14 @@ It is designed so it is easy to install, easy to use, and feels familiar with ot
 ### Features
 
 - It is a proper `sudo for windows`:
-  - Executes the desired command with elevated permissions.
+  - Executes the desired command with elevated permissions (or as another user).
   - Elevated commands are shown in the current user-level console. No new window. (Unless you specify `-n`)
   - Full console support: Colors, full keyboard, auto-completion, etc.
   - Supports I/O redirection.
   - Handles Ctrl-C properly
   - Supports worldwide encodings & codepages
 - Uses the current shell to interpet the command to elevate:
-  - `gsudo {command}` uses a new instance of the invoking shell to elevate the command.
-
+  - `gsudo {command}` uses a new instance of the invoking shell to elevate the command.  
     For example, in PowerShell `gsudo mkdir x` becames `pwsh -c "mkdir x"`, while in CMD it becames `cmd /c "mkdir x"`.
   - Supported Shells:
     - [CMD](usage)
@@ -38,9 +37,7 @@ It is designed so it is easy to install, easy to use, and feels familiar with ot
     - Yori
     - Take Command
     - NuShell
-
-- If no command is specified, it starts an elevated shell.
-
+- If no command is specified, it starts an elevated shell. 
 - [Credentials cache](#credentials-cache): `gsudo` can elevate many times showing only one UAC pop-up if the user opts-in to enable the cache.
 - Supports being used on scripts:
   - Returns the command exit code (`%errorlevel%`). If `gsudo` fails to elevate, the exit code will be 999.

docs/docs/security.md

@@ -51,40 +51,31 @@ And, in my opinion, it's not doing the best possible job:
 - You waste important time by switching between elevated and unelevated windows. You must manually carry your command and context to the elevated window, each time, back and forth.
 - ... or you suffer from "elevation fatigue". For example, you elevate a whole console beforehand, and you do all your stuff there, likely running non-admin or untrusted stuff as admin.
 
-**In conclusion:** Same-desktop UAC is a vulnerable convenience feature, and so is `gsudo`. In any case, **the only thing that protects you from malware is you and your AntiVirus.**.
+**In conclusion:** 
+
+- Same-desktop UAC is a vulnerable convenience feature, and so is `gsudo`. In any case, **the only thing that protects you from malware is you and your Antivirus.**.
 
 ## What are the risks of running gsudo?
 
-gsudo could be used as an attack vector for escalation of privileges:
+gsudo could be used as an attack vector for escalation of privileges. Using antivirus software and avoiding running untrusted software
 
-- **Abusing an elevation made with gsudo:** A medium integrity process could drive the gsudo-elevated process: 
+- **Abusing an elevation made with gsudo:**
+
+  A medium integrity process could drive the gsudo-elevated process. 
 
   When gsudo elevates **in the same console**, it creates a connection between a medium and a high integrity process. A malicious process (at medium integrity) can then drive the medium integrity console: sending keystrokes to the high integrity app, or scrapping its screen.
 
   In my opinion, this is a mild risk that you are already exposed when using UAC in default mode. In the end, your only protection is your AV.
 
   Ways to avoid this risk:
-  - Elevating on a new console, using `-n`/`--new`.
-  - Proposed new feature `ForceNewWindow`, to add a config setting where all elevations are done in new windows, so no isolation is broken. Tracked here: [#97](https://github.com/gerardog/gsudo/issues/97) (and up for grabs)
-  - Experimental: `SecurityEnforceUacIsolation`
+  - Elevating on a new console either per-command (using `-n`/`--new`) or force it using [config setting `NewWindow.Force`](tips/elevation-in-new-window.md).
+  - Experimental setting `SecurityEnforceUacIsolation`:
   makes the elevated command run redirected, w/input redirected to `NULL`. Hence it will be non-interactive, so nobody will be able to drive it. Enable with `gsudo config SecurityEnforceUacIsolation true`
 
-- **Abusing an active `gsudo Credentials Cache` to elevate a process silently**:
+- **Abusing an active `gsudo's Credentials Cache` to elevate a process silently**:
 
    The `Credentials Cache` allows many elevations with only one UAC popup. But there is a reason why the cache is disabled by default.
 
    When the cache is active, it allows elevation from one invoker process and its children, which are running at the unprotected medium integrity level. A malicious process also at medium level can inject it's code into an allowed process and make it call gsudo to request elevation silently.
 
    You avoid this risk by default, by not enabling the credentials cache.
-
-**TLDR;** Both `UAC` and `gsudo` are vulnerable convenience features. Both rely on your ability to avoid malware, or your antivirus ability to stop it.
-
-<!--
-
-Or configurations:
-
-**SecurityEnforceUacIsolation=true:** This is piped mode with a hack where the Input is closed, making theoretically impossible for an unelevated process to drive the elevated world. I don't have real proof that this is less exploitable than the default, hence I never publicily documented this setting.
-
-**ForceNewWindow:** An idea (spec still pending), to add a config setting where all elevations are done in new windows, so no isolation is broken. If I/O is redirected, the result may be streamed to the unelevated. This is still only and idea because the user experience would probably be .
-
--->

docs/docs/tips/elevation-in-new-window.md

@@ -0,0 +1,33 @@
+---
+#sidebar_position: 6
+title: Force elevation in new window
+#hide_title: true
+---
+
+As mentioned in [Security Considerations](../security.md#what-are-the-risks-of-running-gsudo), elevation in the same console exposes a mild risk. You can avoid it altogether by elevating in a new console window, for example by adding the `--new` or `-n` switch.
+
+In gsudo v2, a new setting was introduced to force elevations in a new window. To enable it simply run:
+
+``` powershell
+gsudo config NewWindow.Force true
+```
+
+The problem with this approach is that some elevations complete too quickly and the new window may close abruptly. So to leave time to verify the window result, combine it with one of the following new switches:
+
+- `--KeepWindow`: After running a command in a new console, ask for keypress before closing the console/window.
+- `--KeepShell`: After running a command, keep the elevated shell open.
+
+You set one of those switches permanently by using the following setting:
+
+``` powershell
+gsudo config NewWindow.CloseBehaviour [ KeepShellOpen | PressKeyToClose | OsDefault ]
+```
+
+Valid values are:
+  - **KeepShellOpen**: Forces `--keepShell`. Keep the elevated shell open after running the command.
+  ![KeepShellOpen](../static/img/../../../static/img/NewWindow.CloseBehaviour.KeepShellOpen.png)
+
+  - **PressKeyToClose**: Forces `--keepWindow`. Asks for a keypress before closing the window.  
+  ![PressKeyToClose](../static/img/../../../static/img/NewWindow.CloseBehaviour.PressKeyToClose.png)
+
+  - **OsDefault**: (default) Launch the command and let the operating system close it or keep it according to the system defaults (typically the window will close).