How gerardog/gsudo works
Main Components
• Command-Line Interface (CLI) Layer: This is the entry point. The executable (gsudo.exe) and its corresponding aliases (e.g., “sudo”) provide the user interface. This layer processes command-line arguments (for both CMD and PowerShell), handling options such as “-n” (new window), “-w” (wait), and the “!!” repeat command.
• Command Parser & Dispatcher: Within the “src/gsudo/Commands” and “src/gsudo/Helpers” directories, the commands get parsed and dispatched. This component interprets the intended operation (e.g., elevation request, credentials cache activation, etc.) and directs the workflow.
• Elevation & Privilege Management Unit: Handles elevation logic (including UAC pop-up triggering and credential caching) and interacts with Windows’ native APIs. Look in “src/gsudo/ElevationRequest.cs”, “src/gsudo/Tokens”, and “src/gsudo/CredentialsCache” for these functionalities.
• Process Creation & Host Management: The project organizes elevated process handling through “ProcessHosts” (found in “src/gsudo/ProcessHosts”) and renders output via “ProcessRenderers”. This layer manages launching a new elevated shell or running commands in the current console.
• Native Integration & Pseudo Console: The “Native” and “PseudoConsole” folders contain wrappers for making native Windows API calls to handle tasks such as console management and token handling.
• Build, Packaging, and Deployment: The “build” directory contains PowerShell scripts (build, test, sign, release for Chocolatey, Nuget, and Scoop packaging) which indicate a CI/CD pipeline with GitHub workflows. These components build and distribute the tool.
• Testing & Documentation: The “src/gsudo.Tests”, “src/gsudo.Wrappers.Tests”, “docs”, and “sample-scripts” directories show how the project is validated, documented, and how usage examples are provided.
Relationships and Data Flow
• The input goes to the Command Parser, which inspects the arguments (and, if needed, picks up environment settings from configuration files).
• Depending on the command, the tool either:
– Launches an elevated process by invoking the Process Creation Unit
– Triggers the credential cache manager for repeated permissions elevation,
– Or dispatches a command to run in the current shell.
• The Elevation Unit interacts with Windows’ UAC mechanisms, optionally interfacing with native modules (in “Native” and “PseudoConsole”) to perform tasks like launching a new window or directly rendering output.
• Build and packaging components tie into external package managers and deployment scripts (Chocolatey, Nuget, Scoop) as seen in the “build” directory.
Architectural Patterns and Key Design Principles
• Layered Architecture: Separation between the CLI interface, command parsing, elevation logic, and process control layers.
• Modularity: Individual directories for Commands, Helpers, Native integrations, and Process Management suggest a modular design.
• Cross-Shell and Multipurpose Support: The design ensures support for multiple shells (CMD, PowerShell, WSL, etc.) with specific wrappers and helper functions.
• Extensibility: The inclusion of tests, sample scripts, and clear separation of concerns indicates an architecture that is designed for easy extension and integration with various Windows elevation scenarios.
Technologies and Frameworks
• .NET (targeting net9.0 as per the README) and usage of NativeAOT for fast startup and reduced memory.
• Use of PowerShell scripting for build automation and command testing.
• Integration with Windows native APIs through interop calls in “Native” modules.
• GitHub Actions for CI (workflows in the .github folder) and various packaging technologies (Chocolatey, Nuget, and Scoop).