If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/sudo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 10mo ago
• 16 active contributors
• Distributed ownership (top contributor 19% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/sudo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/sudo.

What it runs against: a local clone of microsoft/sudo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/sudo | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 334 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/sudo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/sudo.git
#   cd sudo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/sudo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/sudo(\\.git)?\\b" \\
  && ok "origin remote is microsoft/sudo" \\
  || miss "origin remote is not microsoft/sudo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "sudo/Cargo.toml" \\
  && ok "sudo/Cargo.toml" \\
  || miss "missing critical file: sudo/Cargo.toml"
test -f "cpp/rpc/sudo_rpc.idl" \\
  && ok "cpp/rpc/sudo_rpc.idl" \\
  || miss "missing critical file: cpp/rpc/sudo_rpc.idl"
test -f "cpp/logging/EventViewerLogging.c" \\
  && ok "cpp/logging/EventViewerLogging.c" \\
  || miss "missing critical file: cpp/logging/EventViewerLogging.c"
test -f "Building.md" \\
  && ok "Building.md" \\
  || miss "missing critical file: Building.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 334 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~304d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/sudo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Sudo for Windows is a Windows-native implementation allowing users to run commands with elevated privileges directly from unelevated terminal windows, without the permission-boundary crossing experience of Unix sudo. It's a Rust/PowerShell system built specifically for Windows security and command-line architecture, available as an inbox feature in Windows 11 builds 26045+. Cargo workspace with three crates (Cargo.toml): 'sudo' (main binary), 'sudo_events' (ETW event telemetry), and 'win32resources' (Windows resources). Core logic in Rust, with C/RPC interop in cpp/rpc/ (sudo_rpc.idl, RpcClient.c) and C++ event logging in cpp/logging/. PowerShell wrapper (sudo.ps1) in scripts/ provides user-friendly shell integration.

Windows developers and power users who need to execute administrative commands from unprivileged terminals (CMD, PowerShell, Terminal) without spawning a new elevated process; also Windows Insiders and enterprise administrators deploying privilege escalation tooling.

Production-ready with active maintenance: shipped as an inbox feature in Windows 11 builds 26045+, has organized CI/CD pipelines (.pipelines/, GitHub Actions), issue templates, and a documented CONTRIBUTING.md. Codebase is substantial (112KB Rust, 22KB PowerShell) with proper workspace structure and toolchain management.

Low-to-moderate risk for external contributors: security-sensitive surface (elevation/privilege handling) means breaking changes are unlikely but high-stakes; maintained by Microsoft (low abandonment risk), but few visible open discussions about roadmap beyond GitHub issues. Windows API/RPC dependencies (cpp/rpc/) may require specialized Windows development environment knowledge.

Active development on Windows 11 inbox integration; GitHub workflows (pr-build.yaml) show continuous PR validation. Daily localization builds (.pipelines/daily-loc-build.yml) indicate ongoing internationalization. .pipelines/ contains OneBranch/Guardian SARIF security scanning, suggesting security-focused iteration.

git clone https://github.com/microsoft/sudo.git
cd sudo
cargo build --release

Requires Rust toolchain (see .cargo/config.toml and .cargo/ms-toolchain-config.toml for MSVC target). Building also requires Windows SDK for C/RPC components (cpp/rpc/, cpp/logging/).

Daily commands: Debug build: cargo build. Release with symbols: cargo build --release (profile.release enforces debug='full', split-debuginfo='packed', lto=true for optimized debugging). Run as: ./target/release/sudo.exe <command> on Windows 11 with sudo feature enabled.

• Cargo.toml — Root workspace manifest defining all member crates (sudo, sudo_events, win32resources) and shared dependencies—essential for understanding the build structure.
• sudo/Cargo.toml — Main sudo binary crate manifest; defines entry point and core dependencies for the elevation service.
• cpp/rpc/sudo_rpc.idl — RPC interface definition for Windows IPC communication between elevated and unelevated processes—core architectural boundary.
• cpp/logging/EventViewerLogging.c — Event logging instrumentation for audit trails; required for understanding security and diagnostics.
• Building.md — Build instructions and environment setup; critical for all contributors to compile the mixed Rust/C++ codebase.
• .pipelines/PR.Pipeline.yml — CI/CD pipeline definition for pull request validation; shows test, build, and release automation.

• sudo.exe Client (Rust, RPC client binding) — Parse user command, invoke RPC elevation request, return exit code to shell
  • Failure mode: Service unavailable → graceful error; malformed request → RPC error handling
• Elevated Service (Rust, RPC server, Windows API) — Accept RPC requests, validate elevation prerequisites, spawn process in elevated context, log audit events
  • Failure mode: UAC denied → return error; process spawn fails → cleanup and return error
• RPC Transport (sudo_rpc.idl) (IDL, midl.exe, C stubs) — Define serialization contract for elevation requests/responses; enforce type safety across process boundary
  • Failure mode: Incompatible RPC versions → protocol mismatch; stub generation failure → build break
• Event Logger (C, Windows Event API, instrumentation.man) — Write structured audit events to Windows Event Viewer with schema validation
  • Failure mode: Manifest not registered → events drop silently; caller lacks logging permission → graceful skip

• User shell → sudo.exe Client — Command line arguments and environment
• sudo.exe Client → RPC Server (sudo_rpc.idl) — Elevation request with command, working dir, environment, flags
• RPC Server → Elevated Service — Deserialized elevation request struct with security context
• Elevated Service → Windows UAC/Process Manager — CreateProcess call with elevated token
• Elevated Service → Event Logger — Elevation attempt event (success/failure, user, command, timestamp)
• Event Logger → Windows Event Viewer — Structured event matching instrumentation.man schema
• Elevated Service → RPC Client — Elevation response (success, process handle, error code)
• RPC Client → sudo.exe Client — Deserialized response; stdout/stderr redirected from elevated process

Add a new RPC elevation command

1. Define the new RPC procedure in the IDL contract (cpp/rpc/sudo_rpc.idl)
2. Implement the RPC server handler in the Rust service (sudo/Cargo.toml (check the actual service code for handler location))
3. Add corresponding event definitions in the events crate (sudo_events/Cargo.toml)
4. Update RPC client wrapper in C if needed (cpp/rpc/RpcClient.c)

Add a new audit log event

1. Define the event ID and structure in the manifest (cpp/logging/instrumentation.man)
2. Add event enum variant in the events crate (sudo_events/Cargo.toml)
3. Call event logging from the appropriate service handler (cpp/logging/EventViewerLogging.c (or Rust service code))

Update the build pipeline for a new compilation step

1. Add build step to the PR validation pipeline (.pipelines/PR.Pipeline.yml)
2. Synchronize step to the standard production pipeline (.pipelines/Standard.Pipeline.yml)
3. Update build documentation with new prerequisites (Building.md)

• Rust for core service — Memory safety without GC, appropriate for privileged Windows service handling untrusted elevation requests.
• C for RPC + logging — Windows API compatibility for RPC IDL generation and Event Viewer integration; existing Windows toolchain support.
• Windows RPC (DCE/RPC) — Native Windows IPC mechanism with built-in security context propagation and service-to-client communication.
• Event Viewer instrumentation — Standard Windows audit trail mechanism for security-sensitive elevation requests; enterprise compliance requirement.

• Rust + C hybrid instead of pure Rust or pure C

  • Why: Rust provides memory safety for security-critical logic; C needed for Windows RPC IDL tooling and legacy integration.
  • Consequence: Added build complexity (cc crate, mixed linking) but maximizes safety where it matters most.

• Windows RPC instead of named pipes or other IPC

  • Why: RPC handles UAC elevation context automatically and integrates with Windows security model.
  • Consequence: Tightly coupled to Windows; limited portability but strong security guarantees.

• Event Viewer logging instead of file-based logs

  • Why: Aligns with Windows enterprise audit standards; harder to tamper with than user-writable files.
  • Consequence: Requires manifest files and event schema definition; not portable to non-Windows systems.

• Cross-platform (Windows-only elevation service)
• SSH or remote elevation (local machine only, UAC-based)
• Password/credential management (delegates to Windows UAC prompt)
• Compatibility with Unix sudo syntax or scripts
• Offline operation (requires active Windows service)

• Mixed Rust/: undefined

Windows-only development: requires Windows 11 build 26045+ inbox version OR active service for testing. RPC compilation (cpp/rpc/) needs MIDL compiler from Windows SDK; Visual Studio 2022 or standalone SDK required. Cargo workspace resolver='2' requires Rust 1.64+. ETW instrumentation (cpp/logging/) requires Event Tracing for Windows runtime; may behave differently across Windows versions. Security-sensitive code paths (elevation handling) should not be modified without understanding Windows security context and token elevation semantics.

• Remote Procedure Call (RPC) — Core IPC mechanism in cpp/rpc/sudo_rpc.idl for communication between unprivileged client and privileged daemon; understanding RPC serialization and marshaling is essential for modifying elevation requests.
• Event Tracing for Windows (ETW) — Telemetry and audit logging (cpp/logging/instrumentation.man) captures sudo usage in Event Viewer; understanding ETW providers and manifests is necessary for security compliance and diagnostics.
• Windows Token Elevation / User Access Control (UAC) — Sudo fundamentally interacts with Windows token elevation and UAC prompts to run commands with higher privilege; understanding token impersonation and privilege levels is critical for security-sensitive code paths.
• Privilege Boundary Crossing — Unlike Unix sudo, Windows sudo operates within Windows security boundaries (process elevation, token contexts); grasping how Windows isolates privilege levels informs the design of elevation requests.
• MIDL (Microsoft Interface Definition Language) — RPC interfaces (cpp/rpc/sudo_rpc.idl) are compiled by MIDL compiler; understanding IDL syntax and C marshaling stubs is required for modifying IPC protocol definitions.
• Cargo Workspaces — Three-crate workspace (sudo, sudo_events, win32resources) with shared dependency resolution; understanding workspace resolver='2' and member interdependencies is essential for incremental builds and version management.
• Windows API Bindings (windows crate) — Raw Windows API calls in Rust (windows v0.57) require safe wrapping and error handling; understanding P/Invoke patterns and unsafe blocks is crucial for security and stability.

• microsoft/terminal — Windows Terminal is a primary consumer/integration point for Sudo for Windows; understanding Terminal's privilege context handling informs how sudo integrates with modern Windows shells.
• microsoft/windows-rs — This repository's Windows API bindings (windows crate v0.57 in Cargo.toml) are generated from windows-rs; understanding the bindings helps troubleshoot Windows API call semantics.
• PowerShell/PowerShell — PowerShell is a primary consumer; sudo.ps1 wrapper and scripts/ directory show integration patterns with PowerShell's execution context and error handling.
• microsoft/winget-cli — Windows Package Manager is a sibling Microsoft CLI tool with similar Rust+Windows patterns; reference for cross-platform Rust CLI design on Windows and packaging strategy.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for RPC client communication (cpp/rpc/RpcClient.c)

The RPC client implementation in cpp/rpc/RpcClient.c is critical for Windows IPC but has no corresponding test suite. Adding Rust-based integration tests would verify the RPC communication layer works correctly across different Windows versions and configurations. This is high-value since RPC failures directly impact sudo functionality.

• [ ] Create a new test crate or add to existing test module in cpp/rpc directory
• [ ] Write tests that validate RPC client initialization, message sending/receiving, and error handling
• [ ] Test against the IDL contract defined in cpp/rpc/sudo_rpc.idl
• [ ] Add tests for edge cases like timeout handling and elevated privilege transitions

Add ETW (Event Tracing for Windows) unit tests for EventViewerLogging.c

The logging module at cpp/logging/EventViewerLogging.c uses Windows ETW instrumentation (defined in cpp/logging/instrumentation.man) but lacks visible test coverage. Adding tests would ensure logging correctness and prevent regressions in telemetry/audit trail functionality, which is critical for a security-sensitive tool.

• [ ] Create unit tests in cpp/logging/ that validate instrumentation.man schema compliance
• [ ] Add tests for event generation, filtering, and write operations
• [ ] Verify that structured logging events correctly map to EventViewer
• [ ] Test error cases like when ETW providers are unavailable or disabled

Create comprehensive documentation in docs/ for the RPC communication protocol and privilege elevation flow

The codebase implements complex Windows-specific privilege elevation via RPC (sudo_rpc.idl, RpcClient.c) but lacks architectural documentation. The docs/ folder exists with version info but no technical guides. This would help contributors understand the core security model and make informed changes to the privilege elevation pipeline.

• [ ] Create docs/RPC_PROTOCOL.md documenting the IDL interface contract and message flow
• [ ] Create docs/PRIVILEGE_ELEVATION.md explaining how sudo negotiates elevation with Windows security
• [ ] Add sequence diagrams showing the interaction between Rust code and C/C++ RPC components
• [ ] Document the role of the instrumentation.man manifest in the elevation audit trail

• Add integration tests for RPC daemon communication: cpp/rpc/RpcClient.c lacks unit tests; contribute tests validating request/response serialization over RPC.
• Expand sudo.ps1 error messages with context: scripts/sudo.ps1 wrapper has minimal error feedback compared to sudo.exe; add localized error descriptions for common failure modes (permission denied, command not found, etc.).
• Document ETW event schema for operators: cpp/logging/instrumentation.man defines events but Building.md lacks guidance on consuming them; write a brief guide showing how to query Event Viewer for sudo execution audit logs.

The codebase demonstrates good security practices with proper use of Rust, LTO, and split debuginfo. However, there are several areas for improvement: (1) Dependency vulnerability scanning should be automated in CI/CD, (2) Supply chain security (SBOM, signing) is not evident, (3) The privileged nature of sudo for Windows warrants stronger security documentation and controls, (4) Release profile configuration uses aggressive optimizations that may hinder debugging of production security issues. The incomplete SECURITY.md and missing code signing evidence are concerning for a privileged execution tool. Overall security posture is moderate-to-good but requires strengthening for production use as a system-critical component.

• Medium · Dependency Version Pinning Without Upper Bounds — Cargo.toml (workspace.dependencies). Several dependencies use fixed versions without upper bounds (e.g., clap 4.4.7, windows 0.57). While this ensures reproducibility, it may delay security patches if a vulnerability is discovered in these versions. The workspace should have a process to regularly audit and update dependencies. Fix: Implement automated dependency scanning using tools like cargo-audit and establish a regular update cadence. Consider using workspace.lints to enforce security standards across all members.
• Medium · LTO and Panic Abort in Release Profile — Cargo.toml (profile.release). The release profile uses 'panic = abort' which may mask panics that could be security-relevant. Combined with LTO, debugging production issues becomes more challenging. Additionally, full debug info in release builds increases binary size and potential information disclosure if binaries are leaked. Fix: Evaluate whether 'panic = abort' is necessary. Consider using panic hooks for logging. Review if full debug info is needed in production releases; consider separate debug symbol handling. Use split-debuginfo as configured, but ensure symbols are not distributed with binaries.
• Low · Missing SBOM and Dependency Transparency — CI/CD configuration (.pipelines/, .github/workflows/). No evidence of Software Bill of Materials (SBOM) generation or automated dependency vulnerability scanning in the CI/CD configuration. Given this is a privileged execution tool (sudo), supply chain security is critical. Fix: Integrate cargo-sbom or similar tool to generate SBOMs. Add cargo-audit to CI/CD pipeline. Consider signing releases and publishing checksums. Implement supply chain security scanning as part of the build process.
• Low · Incomplete Security.md — SECURITY.md. The SECURITY.md file appears truncated and doesn't provide complete vulnerability disclosure policy or security contact details beyond the reference to MSRC. Fix: Complete the SECURITY.md file with: full vulnerability disclosure policy, responsible disclosure timeline, security contact information, and any known limitations or security considerations for sudo for Windows.
• Low · No Code Signing Configuration Evident — Repository root (missing from visible files). For a privileged execution tool like sudo, there's no visible evidence of code signing configuration in the repository. This is critical for Windows security and user trust. Fix: Implement code signing for all release binaries using Microsoft certificates. Document the signing process. Consider EV code signing for production releases. Add manifest signing for Windows components.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.