# trifectatechfoundation/sudo-rs architecture

> Architecture diagram of the GitHub repository trifectatechfoundation/sudo-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trifectatechfoundation/sudo-rs
- Repository: https://github.com/trifectatechfoundation/sudo-rs

## Overview

##### Project type and purpose
- sudo-rs is a systems-level CLI tool, a drop-in replacement for Unix’s `sudo`, `su`, and `visudo` commands.
- Written in Rust, it focuses on safety and memory correctness, targeting Linux 5.9+ and leveraging PAM for authentication.

##### High-level architecture
┌───────────────────┐     ┌───────────────────────┐     ┌──────────────────────────┐
│  User / Shell     │ ──> │  sudo-rs / su-rs /    │ ──> │   Core Library (src/)    │
│  (CLI invocation) │     │  visudo-rs binaries   │     │   – cli modules          │
└───────────────────┘     └───────────────────────┘     │   – common, defaults     │
│   – parser (sudoers)     │
│   – policy engine        │
│   – authentication (PAM) │
│   – execution (PTY, sys) │
│   – apparmor integration │
│   – logging (syslog)     │
└──────────────────────────┘
│
┌────────────────────────────────────────────────┴──────────────────────────────────┐
│                                                                                │
┌──────────────────┐                                                         ┌──────────────────┐
│   Linux Kernel   │                                                         │  External files  │
│  & Syscalls      │<─── exec / system abstractions <───┐                │  & services:     │
│  (fork, execve,  │                                   │                │  /etc/sudoers,   │
│   chown, pty,    │                                   ├── PAM library  │  /etc/pam.d      │
│   signal, audit) │                                   │                │  config files    │
└──────────────────┘                                   │                └──────────────────┘
│
┌────────┴────────┐
│   PAM Library   │
│ (libpam.so)     │
└─────────────────┘

##### Main components & interactions
a. Entry points (bin/):
- `bin/sudo.rs`, `bin/su.rs`, `bin/visudo.rs` – thin wrappers that parse CLI flags and hand off to core.
b. Core library (src/lib.rs + submodules):
- cli modules (`src/sudo/cli`, `src/su/cli`, `src/visudo/cli`) – argument parsing & help text.
- defaults (`src/defaults`) – compile-time and run-time default settings.
- config parser (`src/sudoers/*`) – lexing, parsing, AST, policy models.
- policy evaluation (`src/sudoers/policy.rs`) – decides if action is permitted.
- authentication (`src/pam/*`) – conversing with PAM, password input, secure memory.
- execution (`src/exec/*`) – spawning the target process, with or without PTY, backchannels, monitoring.
- system abstraction (`src/system/*`) – file operations, chown, locking, signals, tempdir, timestamps, auditing.
- sandboxing (`src/apparmor/*`) – AppArmor confinement support on Linux.
- logging (`src/log/*`) – simple logger to stderr or syslog sink.
c. External interactions:
- Linux kernel syscalls (fork, execve, setuid, ioctl for pty, signals) via `system/*`.
- PAM (via FFI to libpam, configured by service names “sudo”/“sudo-i”).
- Reading `/etc/sudoers[-rs]` and `/etc/pam.d/*` files.
- Writing audit logs and syslog entries.

##### Architectural patterns and design principles
- Modular separation: CLI, parsing, policy, auth, execution, system layer, logging.
- Shared library core: `lib.rs` provides reusable building blocks for all three binaries.
- Strategy pattern in `exec/use_pty` vs `exec/no_pty`.
- Clear boundaries between parsing (pure Rust code) and system side-effects (isolated in `system/*`).
- Safety-first: no unsafe except narrow FFI (PAM), AppArmor syscalls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        User["User / Shell"]:::external
    end

    subgraph "CLI Wrappers" 
        SudoBin["sudo.rs"]:::cli
        SuBin["su.rs"]:::cli
        VisudoBin["visudo.rs"]:::cli
    end

    subgraph "Core Library"
        Lib["lib.rs"]:::core

        subgraph "CLI Modules"
            SudoCliMod["mod.rs"]:::core
            SudoCliHelp["help.rs"]:::core
            SuCli["su/cli.rs"]:::core
            VisudoCliMod["visudo/cli.rs"]:::core
            VisudoCliHelp["visudo/help.rs"]:::core
        end

        subgraph "Defaults Module"
            DefaultsMod["mod.rs"]:::core
            DefaultsDSL["settings_dsl.rs"]:::core
        end

        subgraph "Config Parser (sudoers)"
            SudoersMod["mod.rs"]:::core
            BasicParser["basic_parser.rs"]:::core
            AST["ast.rs"]:::core
            PolicySrc["policy.rs"]:::core
        end

        subgraph "Authentication (PAM)"
            PamMod["mod.rs"]:::system
        end

        subgraph "Execution Module"
            ExecMod["mod.rs"]:::core
        end

        subgraph "System Abstraction"
            SysMod["mod.rs"]:::system
        end

        Apparmor["apparmor/mod.rs"]:::system
        Logging["log/mod.rs"]:::core
    end

    subgraph "External Config & Services"
        ConfigFiles[("Cylinders: /etc/sudoers & /etc/pam.d/*")]:::external
        PAMLib[("PAM Library (libpam.so)")]:::external
        Kernel[("Linux Kernel & Syscalls")]:::external
    end

    subgraph "Test Framework"
        TestFw["E2E & Compliance Tests"]:::test
    end

    %% Flow
    User --> SudoBin
    User --> SuBin
    User --> VisudoBin

    SudoBin --> Lib
    SuBin --> Lib
    VisudoBin --> Lib

    Lib --> SudoCliMod
    Lib --> SudoCliHelp
    Lib --> SuCli
    Lib --> VisudoCliMod
    Lib --> VisudoCliHelp

    SudoCliMod --> DefaultsMod
    DefaultsMod --> DefaultsDSL

    Lib --> SudoersMod
    SudoersMod --> BasicParser
    BasicParser --> AST
    AST --> PolicySrc

    Lib --> PamMod
    PamMod --> PAMLib
    ConfigFiles --> SudoersMod
    ConfigFiles --> PamMod

    Lib --> ExecMod
    ExecMod --> Kernel

    Lib --> SysMod
    SysMod --> Kernel

    Lib --> Apparmor
    Apparmor --> Kernel

    Lib --> Logging

    TestFw --> SudoBin
    TestFw --> SuBin
    TestFw --> VisudoBin

    %% Click Events
    click SudoBin "https://github.com/trifectatechfoundation/sudo-rs/blob/main/bin/sudo.rs"
    click SuBin "https://github.com/trifectatechfoundation/sudo-rs/blob/main/bin/su.rs"
    click VisudoBin "https://github.com/trifectatechfoundation/sudo-rs/blob/main/bin/visudo.rs"
    click Lib "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/lib.rs"
    click SudoCliMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudo/cli/mod.rs"
    click SudoCliHelp "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudo/cli/help.rs"
    click SuCli "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/su/cli.rs"
    click VisudoCliMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/visudo/cli.rs"
    click VisudoCliHelp "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/visudo/help.rs"
    click DefaultsMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/defaults/mod.rs"
    click DefaultsDSL "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/defaults/settings_dsl.rs"
    click SudoersMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudoers/mod.rs"
    click BasicParser "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudoers/basic_parser.rs"
    click AST "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudoers/ast.rs"
    click PolicySrc "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/sudoers/policy.rs"
    click PamMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/pam/mod.rs"
    click ExecMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/exec/mod.rs"
    click SysMod "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/system/mod.rs"
    click Apparmor "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/apparmor/mod.rs"
    click Logging "https://github.com/trifectatechfoundation/sudo-rs/blob/main/src/log/mod.rs"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#76A5AF,color:#034F84;
    classDef core fill:#E2F0D9,stroke:#6BAA39,color:#33691E;
    classDef system fill:#FFE7D9,stroke:#DA6A2A,color:#8D3006;
    classDef external fill:#F0F0F0,stroke:#B3B3B3,color:#666666;
    classDef test fill:#F3E5F5,stroke:#A569BD,color:#4A235A
```
