gsudo

Key Advantages of gsudo:

• Shell Integration: Can elevate the current shell or elevate commands using the current shell context.
• User Experience: Supports a Credentials Cache to reduce UAC pop-ups and provides a red # indicator for elevation in CMD.
• Advanced Execution: Supports sudo !! to elevate the last command and provides options to keep new windows open or keep the shell open after elevation.
• Compatibility: Works on Windows 7 SP1 through Windows 11, including support for Win11 Administration Protection.

To avoid repeated UAC (User Account Control) prompts when running multiple elevated commands in sequence, you can leverage the gsudo credentials cache. This allows subsequent commands to run elevated without triggering a new interactive popup.

Sample scripts demonstrating this pattern include:

• many-elevations-using-gsudo-cache.cmd (Batch)
• many-elevations-using-gsudo-cache.ps1 (PowerShell)

To mitigate security risks associated with elevation in the same console, you can force gsudo to elevate commands in a new console window.

To enable this behavior globally, use the gsudo config command to set NewWindow.Force to true.

gsudo config NewWindow.Force true

On WSL, the Linux root user is distinct from Windows Administrator privileges. To perform Windows-level administrative tasks from a WSL terminal, you must elevate the WSL.EXE process using gsudo.

• To elevate WSL commands (Linux-native commands), prepend gsudo to the command.
• To run Windows commands (CMD/Windows-native commands), use the -d flag with gsudo.

# elevate default shell
PC:~$ gsudo 

# run elevated WSL command
PC:~$ gsudo mkdir /mnt/c/Windows/MyFolder

# run elevated Windows command
PC:~$ gsudo -d notepad C:/Windows/System32/drivers/etc/hosts

To make a PowerShell script self-elevating, use a helper function to check the current Windows Principal role. If not elevated, call gsudo to re-run the script's source path with the original arguments.

function Test-IsElevated {
  return (New-Object Security.Principal.WindowsPrincipal(
    [Security.Principal.WindowsIdentity]::GetCurrent()))
    .IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
}

if ((Test-IsElevated) -eq $false) {
  Write-Warning "This script requires local admin privileges. Elevating..."
  gsudo "& '$($MyInvocation.MyCommand.Source)'" $args
  if ($LastExitCode -eq 999 ) {
    Write-error 'Failed to elevate.'
  }
  return
}

# You are elevated. Do admin stuff here.

To enable tab-key auto-completion for parameters and the gsudo !! shortcut (which elevates the last executed command), add the gsudoModule.psd1 to your PowerShell $PROFILE.

Installation: Replace the path below with the actual path to the module on your system.

Import-Module 'C:\path\to\gsudoModule.psd1'

Automated Installation: Run this command to append the import to your profile automatically:

Write-Output "\nImport-Module `"gsudoModule`"" | Add-Content $PROFILE

When gsudo elevates in the same console, a medium-integrity process could potentially drive the high-integrity process (e.g., by sending keystrokes or screen scraping).

To mitigate this risk, you can:

1. Elevate in a new console: Use the -n or --new flag for individual commands to ensure the elevated process runs in a separate window.
2. Use the experimental security setting: Enable SecurityEnforceUacIsolation to make the elevated command run redirected with input redirected to NULL. This makes the command non-interactive and prevents it from being driven by other processes.

To enable the experimental setting, use:

gsudo config SecurityEnforceUacIsolation true

Instead of creating dedicated elevated profiles, you can elevate your existing session or specific commands within a window using gsudo:

• To elevate the entire current shell: Run gsudo by itself. This will invoke your current caller shell (such as CMD or PowerShell) with elevated privileges in the same window.
• To elevate a specific command: Prepend gsudo to the command you wish to run with elevated privileges.

To start a local development server for the documentation, use yarn start. This will open a browser window and support live reloading for most changes.

$ yarn start