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/trifectatechfoundation/sudo-rs 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 the board

• Last commit 1d ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits

_{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 trifectatechfoundation/sudo-rs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/trifectatechfoundation/sudo-rs.

What it runs against: a local clone of trifectatechfoundation/sudo-rs — 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 trifectatechfoundation/sudo-rs | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of trifectatechfoundation/sudo-rs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/trifectatechfoundation/sudo-rs.git
#   cd sudo-rs
#
# 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 trifectatechfoundation/sudo-rs and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "src/bin/sudo.rs" \\
  && ok "src/bin/sudo.rs" \\
  || miss "missing critical file: src/bin/sudo.rs"
test -f "src/bin/su.rs" \\
  && ok "src/bin/su.rs" \\
  || miss "missing critical file: src/bin/su.rs"
test -f "src/sudo/cli/mod.rs" \\
  && ok "src/sudo/cli/mod.rs" \\
  || miss "missing critical file: src/sudo/cli/mod.rs"
test -f "src/common/context.rs" \\
  && ok "src/common/context.rs" \\
  || miss "missing critical file: src/common/context.rs"
test -f "src/pam/mod.rs" \\
  && ok "src/pam/mod.rs" \\
  || miss "missing critical file: src/pam/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/trifectatechfoundation/sudo-rs"
  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-rs is a memory-safe reimplementation of the Unix sudo and su commands in Rust, replacing the original C-based sudo with a safer alternative that eliminates entire classes of memory vulnerabilities. It provides privilege escalation and command execution with identical user-facing behavior to traditional sudo, but with the memory safety guarantees of Rust—no buffer overflows, use-after-free, or undefined behavior possible in the core implementation. Single-crate monolith (src/) containing modular subsystems: src/apparmor.rs handles AppArmor enforcement, src/ contains PAM integration, sudoers parsing, and privilege escalation logic. Compiled into three binaries: sudo, su, and visudo (editor for sudoers files). Build configuration in Cargo.toml with optional features for PAM variants (pam-login), AppArmor enforcement, gettext localization, and unstable remote sudoers fetching.

System administrators, Linux distribution maintainers, and security-conscious DevOps teams who need sudo functionality but want to eliminate memory safety vulnerabilities in a security-critical component. Contributors include security researchers and Rust systems programmers maintaining a production-grade privilege escalation tool used in distros like Ubuntu 25.10, Fedora, and Arch Linux.

Production-ready and actively maintained. The project has completed two professional security audits (August 2023 for v0.2.0 and August 2025 for v0.2.8), is packaged in major Linux distributions (Ubuntu, Fedora, Arch, Debian), and maintains a detailed changelog and security policy. Latest version is 0.2.13 with regular updates and a responsive issue tracker, indicating healthy ongoing development.

Low technical risk but infrastructure-critical: the project has minimal dependencies (only libc and glob), undergoes professional security audits, and implements Rust's strict safety guarantees. Risks are operational rather than technical—since this is a setuid binary replacement for sudo, deployment requires careful system integration testing, and the relatively lean maintainer team means community contribution is important. No single-maintainer risk observed given the foundation backing (Trifecta Tech Foundation).

Active maintenance on version 0.2.x branch with regular point releases (0.2.13 is current). Recent work includes distribution packaging improvements, AppArmor profile support, sudoedit command implementation, and compatibility enhancements. The project tracks undocumented original sudo behaviors in docs/undocumented-ogsudo-behavior.md and maintains localization with 9 language .po files.

Clone, build with Rust 1.85+, and compile the release binary:

git clone https://github.com/trifectatechfoundation/sudo-rs.git
cd sudo-rs
rustup default 1.85
cargo build --release
# Binary at target/release/sudo

For system integration testing, review docs/sudoers.example for configuration syntax.

Daily commands: Development build: cargo build produces target/debug/sudo. Release build: cargo build --release. Run tests: cargo test. The Makefile provides convenience targets. Note: local execution of sudo/su requires setuid bit and root ownership, which normally requires installation; development usually tests via cargo test or in a container. See Dockerfile for containerized build environment.

• src/bin/sudo.rs — Primary entry point for the sudo command; handles argument parsing, PAM authentication, and execution flow.
• src/bin/su.rs — Entry point for the su command; manages user switching and session initialization.
• src/sudo/cli/mod.rs — Command-line interface parser and validator for sudo; defines core CLI argument handling logic.
• src/common/context.rs — Core execution context abstraction; manages user/group credentials, permissions, and security state throughout execution.
• src/pam/mod.rs — PAM (Pluggable Authentication Modules) wrapper; critical for password authentication and user validation.
• src/exec/mod.rs — Privilege-elevated command execution engine; handles PTY allocation, signal forwarding, and child process management.
• docs/sudoers.example — Configuration file format reference; required reading to understand sudoers policy syntax and defaults.

Add a new sudo CLI option

1. Define the new option in the CLI struct within src/sudo/cli/mod.rs (src/sudo/cli/mod.rs)
2. Add parsing logic to handle the option in the argument parser (src/sudo/cli/mod.rs)
3. Update help text in src/sudo/cli/help.rs to document the option (src/sudo/cli/help.rs)
4. Implement behavior in src/bin/sudo.rs using the parsed option from context (src/bin/sudo.rs)

Add a new sudoers policy rule type

1. Add rule variant to the policy AST in src/sudo/policy/mod.rs (src/sudo/policy/mod.rs)
2. Implement parsing logic to recognize the rule syntax (src/sudo/policy/mod.rs)
3. Implement evaluation logic in the policy checker (src/sudo/policy/mod.rs)
4. Document the syntax in docs/man/sudoers.5.md (docs/man/sudoers.5.md)

Add PAM conversation response handling

1. Identify the new PAM message type in src/pam/sys_linuxpam.rs or src/pam/sys_openpam.rs (src/pam/sys_linuxpam.rs)
2. Add handler for the message type in src/pam/converse.rs (src/pam/converse.rs)
3. If secure memory is needed, use mechanisms in src/pam/securemem.rs (src/pam/securemem.rs)
4. Test with PAM module integration tests (src/pam/mod.rs)

Add a new execution mode

1. Define execution parameters in src/common/context.rs (src/common/context.rs)
2. Add execution path implementation in src/exec/mod.rs or as new module under src/exec/ (src/exec/mod.rs)
3. Implement signal handling and I/O coordination in the new execution path (src/exec/io_util.rs)
4. Wire execution mode selection in src/bin/sudo.rs (src/bin/sudo.rs)

• Rust — Memory safety without garbage collection; eliminates entire classes of vulnerabilities (buffer overflows, use-after-free) critical in a setuid binary handling user credentials.
• libc — Direct system call bindings for privilege management (setuid, setgid, getpwnam) and PAM integration; necessary for POSIX compliance.
• PAM (Pluggable Authentication Modules) — Industry-standard authentication framework; allows integration with system authentication backends (LDAP, Kerberos, local password) without reimplementing authentication logic.
• PTY (Pseudo-Terminal) — Preserves interactive terminal behavior (signals, terminal size changes) when executing commands; required for sudo -i and interactive shells.
• AppArmor (optional) — Mandatory access control enforcement; provides additional sandboxing layer for command execution when enabled.

• Memory safety (Rust) vs. drop-in replacement compatibility

  • Why: Rust's strict borrow checker and ownership model prevent memory vulnerabilities but require careful API design.
  • Consequence: Some legacy sudo features may be unimplemented; trade safety for feature completeness initially, gradually adding features post-audit.

• Single-threaded execution with signal handlers vs. async/await

  • Why: Sudo must handle signals (SIGWINCH, SIGTERM) synchronously to forward to child process; async adds complexity.
  • Consequence: Simpler, more predictable signal handling but less parallelism in I/O multiplexing.

• Mandatory PAM integration vs. optional native authentication

  • Why: PAM is ubiquitous on Linux/FreeBSD; reimplementing authentication is a security antipattern.
  • Consequence: Depends on system PAM configuration; incompatible with systems lacking PAM.

• Two audit passes (2023, 2025) vs. continuous fuzzing

  • Why: Formal audits provide third-party verification; fuzzing catches edge cases post-audit.
  • Consequence: Periodic audits are expensive; fuzzing is ongoing but may miss architectural flaws.

• Does not implement full backward compatibility with original sudo; some obscure features and configuration options remain unimplemented.
• Not a Windows port; explicitly targets Linux and FreeBSD only.
• Does not provide networked authentication without PAM backend; authentication delegated entirely to PAM modules.
• Not a security framework; assumes kernel and libc correctness; does not harden against kernel exploits.

1. Setuid execution context: sudo/su must be compiled as setuid binaries with root ownership; local cargo run will not work for privilege escalation testing—must be installed system-wide or tested in containers. 2) PAM service names vary by distro: The pam-login feature must only be enabled for distros (Debian, Fedora) that provide separate 'sudo-i' PAM service; enabling on Arch will break. 3) Sudoers file parsing is strict: Unlike original sudo which is lenient, sudo-rs parser may reject valid but oddly-formatted sudoers files; see docs/undocumented-ogsudo-behavior.md for compatibility quirks. 4) MSRV is firm: Rust 1.85+ required; using older toolchain will not compile. 5) No generic 'cargo --all-features': The repo explicitly includes do-not-use-all-features to prevent accidental unsupported compilation; feature combinations are documented.

• Setuid binary execution — sudo-rs is compiled as a setuid binary (owned by root with setuid bit), allowing unprivileged users to execute it while it runs with root privileges—this is the fundamental privilege escalation mechanism and why memory safety is critical
• POSIX Capabilities (Linux capabilities(7)) — Modern sudo-rs uses fine-grained Linux capability dropping (CAP_SETUID, CAP_SETGID, etc.) instead of full root, minimizing attack surface if the process is compromised
• PAM (Pluggable Authentication Modules) — sudo-rs authenticates users via PAM service stacks, which vary by distribution (Debian, Fedora, Arch define different /etc/pam.d/sudo configs); understanding PAM chain execution is essential for debugging auth failures
• AppArmor mandatory access control (MAC) — The optional apparmor feature enforces AppArmor profiles loaded in the kernel; this is a second layer of privilege restriction beyond capabilities, important for confined privilege escalation in hardened systems
• Sudoers file syntax and parsing — sudo-rs hand-parses /etc/sudoers (not using yacc like original sudo), implementing a strict parser that rejects lenient original sudo syntax; mastering sudoers rule precedence, user/group expansion, and env var filters is essential for configuration
• Memory safety in Rust (ownership, borrow checker, unsafe blocks) — The entire premise of sudo-rs is replacing C's manual memory management with Rust's compile-time guarantees; understanding why unsafe blocks are audited (see audit reports in docs/audit/) and why unsafe_op_in_unsafe_fn = deny lint is set is critical to appreciating the project's security model
• Sudoedit (safe file editing with privilege elevation) — sudoedit is a complex feature that copies a file to a temp location, launches $EDITOR as the invoking user (not root), and copies back with root; understanding the race conditions and permission checks in src/ is important for secure file editing

• openssh/openssh-portable — Companion security-critical binary using similar privilege escalation patterns; sudo-rs and openssh often run together in privilege separation contexts
• torvalds/linux — Kernel source for capabilities(7), PAM, AppArmor subsystems that sudo-rs binds via libc and depends on for privilege model correctness
• linux-pam/linux-pam — Official PAM library that sudo-rs wraps via libc bindings; understanding PAM module chain execution is essential for sudo-rs auth flow
• trifectatechfoundation/sudo-rs-security — Upstream security issue tracker separate from main repo for responsible disclosure of vulnerabilities in this privilege escalation tool
• sudo-project/sudo — Original C-based sudo—sudo-rs maintains behavioral compatibility; consulting original source clarifies which behaviors are intentional vs. undocumented quirks

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 comprehensive unit tests for src/common/resolve.rs path resolution logic

The resolve.rs module handles critical path resolution for sudo execution. Given sudo-rs's focus on memory safety and security, this file lacks visible test coverage in the repo structure. Adding unit tests for edge cases (symlink resolution, relative paths, permission checks, path traversal attempts) would improve security guarantees and prevent regressions in this security-critical component.

• [ ] Review src/common/resolve.rs to identify all public functions and their edge cases
• [ ] Create tests/resolve_tests.rs with unit tests covering: absolute paths, relative paths, symlinks, non-existent paths, and malformed input
• [ ] Add tests for interaction with src/common/path.rs path utilities
• [ ] Verify tests pass with cargo test and add to CI coverage in .github/workflows/ci.yaml if not already covered
• [ ] Document test cases in code comments explaining the security implications of each test

Add GitHub Actions workflow for security vulnerability scanning with cargo-audit

While the repo has CI, dependabot, and zizmor workflows, there's no explicit security scanning for known vulnerabilities in dependencies. Adding a cargo-audit check would catch CVEs in transitive dependencies before they reach a release. This is particularly important for sudo-rs given its security-critical nature and the two successful audits mentioned in the README.

• [ ] Create .github/workflows/security-audit.yml that runs cargo audit on pull requests and main branch
• [ ] Configure the workflow to fail on any found vulnerabilities (with option to deny warnings)
• [ ] Set it to run on schedule (e.g., daily) in addition to push/PR events
• [ ] Add status badge to README.md linking to security audit workflow
• [ ] Document the security audit process in CONTRIBUTING.md

Complete missing man page documentation and add validation CI check

The repo has man page sources in docs/man/ (sudo.8.md, su.1.md, sudoers.5.md, visudo.8.man), but docs/man/visudo.8.md appears to be missing (only .man file exists). Additionally, there's no CI validation ensuring man pages are kept in sync with code changes or formatted correctly. Adding a workflow to validate markdown formatting and completeness would prevent documentation drift.

• [ ] Create docs/man/visudo.8.md from the existing docs/man/visudo.8.man file (or implement if truly missing)
• [ ] Add .github/workflows/docs-validate.yml that runs cargo run --bin visudo -- --help and validates output matches docs/man/visudo.8.md
• [ ] Add validation for all other man pages (sudo.8.md, su.1.md, sudoers.5.md) to ensure sections exist and match code behavior
• [ ] Run pandoc or similar to validate markdown syntax for all .md man pages
• [ ] Update CONTRIBUTING.md with instructions for maintaining man page documentation when modifying command-line arguments

• Add localized error messages for the Spanish (po/es.po), French (po/fr.po), and Italian (po/it.po) .po files, which are currently stubs with only header metadata. Pick a language, extract untranslated strings from the codebase using gettext tools, and submit translations following the existing po/nl.po format.
• Document PAM-related configuration examples and failure modes in docs/: create a new docs/pam-configuration.md that explains the pam-login feature gate, shows sample PAM service files for different distros (Debian vs Arch vs Fedora), and documents how to troubleshoot 'PAM authentication failed' errors. Reference docs/sudoers.example as a model.
• Expand the undocumented behavior catalog (docs/undocumented-ogsudo-behavior.md) by systematically testing original sudo binary for edge cases: collect 5-10 specific behavioral quirks (e.g., how whitespace in sudoers is parsed, how environment variable filtering handles special cases, how group expansion works), test if sudo-rs matches, and document discrepancies with reproducible test cases.

The sudo-rs codebase demonstrates strong security practices with memory safety through Rust, explicit unsafe code linting, professional security disclosure policy, and completion of two independent security audits (2023, 2025). The project properly documents security-sensitive features and includes comprehensive CI/CD workflows. Minor concerns include: (1) development logging that can compromise security if accidentally enabled, (2) unsafe code linting set to warn rather than deny, (3) unstable remote sudoers feature requiring careful security consideration, and (4) general dependency supply chain monitoring. Overall, this is a well-maintained security-critical project with appropriate scrutiny and professional practices. No critical vulnerabilities detected in the static analysis scope.

• Low · Development Logging Feature May Compromise Security — Cargo.toml (features section), likely src/log/mod.rs or src/log/simple_logger.rs. The 'dev' feature flag enables detailed logging to /tmp, which the codebase explicitly warns 'will compromise the security of sudo-rs somewhat'. This feature should never be enabled in production builds, but there is no automated enforcement preventing accidental compilation with this flag. Fix: Implement build-time checks or CI/CD validation to prevent release builds with the 'dev' feature enabled. Consider adding a build.rs script to enforce this constraint. Add documentation warnings in the feature flag itself.
• Low · Unsafe Code Not Fully Documented — src/ (multiple files with unsafe code), clippy.toml lints configuration. While the codebase enforces 'unsafe_op_in_unsafe_fn' and warns on 'undocumented_unsafe_blocks', the presence of unsafe code in a security-critical sudo implementation requires extremely careful review. The lints are set to warn rather than deny for undocumented blocks. Fix: Upgrade 'undocumented_unsafe_blocks' lint from 'warn' to 'deny' level. Ensure all unsafe blocks have detailed comments explaining why unsafe code is necessary and what invariants must be maintained. Consider regular security audits of unsafe code sections.
• Low · Unstable Remote Sudoers Feature Not Production Ready — Cargo.toml (unstable-remote-sudoers feature). The '@socket' feature for fetching remote sudoers is marked as 'unstable-remote-sudoers'. Network-based sudoers configuration introduces additional attack surface and potential MITM vulnerabilities if not properly secured with TLS/authentication. Fix: Ensure this feature is disabled by default and thoroughly tested before production use. If enabled, mandate TLS certificate validation, secure credential handling, and audit logging. Consider requiring explicit opt-in via configuration with clear security warnings.
• Low · Dependency Monitoring Gaps — Cargo.lock (not provided for analysis), Cargo.toml. While the project uses Dependabot for dependency management (visible in .github/dependabot.yml), only two core dependencies are specified (libc, glob). Transitive dependencies are not visible in the provided Cargo.toml. Any vulnerabilities in transitive dependencies could affect the security of this critical system utility. Fix: Regularly audit Cargo.lock for transitive dependencies using tools like 'cargo-audit'. Consider using 'cargo-deny' for additional dependency policy enforcement. Pin critical dependencies to specific versions and implement a regular security review schedule.

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.