# gblach/please architecture

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

- Interactive diagram: https://gitdiagram.com/gblach/please
- Repository: https://github.com/gblach/please

## Overview

##### Project type and purpose
- This is a small, open-source, command-line utility that replicates a subset of sudo’s behavior.
- It provides PAM-based authentication and, upon success, forks/execs a requested command under elevated (root) privileges.

##### File structure
- please.c           → the core C source implementing the “please” CLI.
- Makefile           → build rules (compilation, linking against libpam).
- pam.d/please.*     → PAM configuration snippets for various Linux/BSD distributions.
- please.1           → man-page source for usage reference.
- README.md/.rst     → documentation and project description.
- COPYRIGHT          → license information.

##### README for additional insights
- Confirms that the only “bell and whistle” is PAM authentication.
- No database or external services; purely local OS integration.

##### Main components
a. User (unprivileged shell)
b. please CLI binary
c. PAM framework (libpam and /etc/pam.d/please configuration)
d. OS authentication stack (e.g., /etc/shadow, PAM modules)
e. OS kernel / privilege escalation (setuid, fork/exec)
f. Child process (the target command run as root)

##### Relationships and interactions
1. User invokes “please <command>”
→ please CLI reads /etc/pam.d/please config
→ calls pam_start()/pam_authenticate() via libpam
→ PAM framework loads underlying modules (pam_unix)
→ kernel prompts for password, verifies credentials
→ PAM returns success or failure to please CLI
2. On success
→ please CLI calls setuid(0)/setgid(0) (binary is installed with root ownership and set-uid bit)
→ forks and execve() the requested command under effective UID=0
3. On failure
→ CLI prints error and exits

##### Architectural patterns and design principles
- Single Responsibility: CLI only handles authentication + exec. No logging, no caching, no policy engine.
- OS integration: Leverages existing PAM modules rather than reinventing authentication.
- Minimal attack surface: small code footprint, minimal dependencies.

##### Important technologies / libraries
- C standard library (libc)
- PAM library (libpam)
- POSIX calls (fork, execve, setuid)
- Makefile for build automation
- Distribution-specific PAM configs in pam.d/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Documentation
    subgraph "Documentation"
        doc1["README.md"]:::doc
        doc2["please.rst"]:::doc
        doc3["please.1"]:::doc
        doc4["COPYRIGHT"]:::doc
    end

    %% Build artifacts
    subgraph "Build"
        MakefileNode["Makefile"]:::build
        CLIsrc["please.c"]:::priv
    end

    %% Main Flow
    User["User Shell"]:::user
    CLI["please CLI (set-uid root binary)"]:::priv
    subgraph "PAM Configuration (pam.d)"
        pamBSD["please.BSD"]:::lib
        pamDeb["please.Debian"]:::lib
        pamFed["please.Fedora"]:::lib
        pamSUSE["please.openSUSE"]:::lib
    end
    PAM["libpam"]:::lib
    OSAuth["OS Authentication (pam_unix → /etc/shadow)"]:::lib
    Kernel["Kernel Privilege Escalation"]:::priv
    Child["Child Command (UID=0)"]:::child

    %% Connections
    User -->|"invokes please <command>"| CLI
    MakefileNode -->|"builds"| CLI
    CLIsrc -->|"compiled into"| CLI
    CLI -->|"reads config"| pamBSD
    CLI -->|"reads config"| pamDeb
    CLI -->|"reads config"| pamFed
    CLI -->|"reads config"| pamSUSE
    CLI -->|"calls pam_start()/pam_authenticate()"| PAM
    PAM -->|"loads pam_unix module"| OSAuth
    OSAuth -->|"verifies credentials"| PAM
    PAM -->|"returns success/failure"| CLI
    CLI -->|"on success: setuid(0)/setgid(0)"| Kernel
    Kernel -->|"fork/execve()"| Child

    %% Click Events
    click CLIsrc "https://github.com/gblach/please/blob/main/please.c"
    click MakefileNode "https://github.com/gblach/please/tree/main/Makefile"
    click pamBSD "https://github.com/gblach/please/blob/main/pam.d/please.BSD"
    click pamDeb "https://github.com/gblach/please/blob/main/pam.d/please.Debian"
    click pamFed "https://github.com/gblach/please/blob/main/pam.d/please.Fedora"
    click pamSUSE "https://github.com/gblach/please/blob/main/pam.d/please.openSUSE"
    click doc1 "https://github.com/gblach/please/blob/main/README.md"
    click doc2 "https://github.com/gblach/please/blob/main/please.rst"
    click doc3 "https://github.com/gblach/please/blob/main/please.1"
    click doc4 "https://github.com/gblach/please/tree/main/COPYRIGHT"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef priv fill:#F08080,stroke:#000,stroke-width:1px
    classDef child fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef build fill:#E6E6FA,stroke:#000,stroke-width:1px
    classDef doc fill:#FFFACD,stroke:#000,stroke-width:1px
```
