# alun-hub/sudo-logger architecture

> Architecture diagram of the GitHub repository alun-hub/sudo-logger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alun-hub/sudo-logger
- Repository: https://github.com/alun-hub/sudo-logger

## Overview

sudo-logger enforces privileged-session recording: the sudo plugin streams I/O to a local agent, which relays it to a central server for acknowledged recording. Operators then search and replay sessions in the web console and manage policy, approvals, users, and integrations. The graph preserves documented eBPF bypass detection, redaction, cgroup freezing, SIEM, and distributed storage capabilities. Some subsystem links rely on the README because their implementation files were not sampled; those evidence limits are reflected by omitting unverified call edges.

Main entry points: [`go/cmd/server/session_conn.go`](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/server/session_conn.go) (Log server), [`go/cmd/agent/main.go`](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/main.go) (Local agent), [`go/cmd/replay-server/ui/src/components/sessions/SessionList.tsx`](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/components/sessions/SessionList.tsx) (Session search), [`go/internal/store/store.go`](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/store/store.go) (Session storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_endpoint["Endpoint capture"]
  node_plugin["Sudo I/O plugin<br/>[plugin.c]"]
  node_agent["Local agent<br/>[main.go]"]
  node_ebpf["eBPF recorder<br/>[recorder.c]"]
  node_divergence["Divergence detection<br/>[divergence.go]"]
end

subgraph group_transport["Session transport"]
  node_protocol["Wire protocol<br/>[protocol.go]"]
end

subgraph group_server["Server and storage"]
  node_logserver["Log server<br/>[session_conn.go]"]
  node_iolog["Recording and redaction<br/>[iolog.go]"]
  node_store[("Session storage<br/>[store.go]")]
  node_distributed[("Distributed storage<br/>[distributed.go]")]
  node_replay_api["Replay API"]
end

subgraph group_console["Replay console"]
  node_web_app["Web application<br/>[App.tsx]"]
  node_session_list["Session search<br/>[SessionList.tsx]"]
  node_terminal["Session replay<br/>[TerminalPlayer.tsx]"]
  node_admin["Admin controls<br/>[routes.go]"]
end

subgraph group_controls["Security controls"]
  node_policy["JIT policy engine<br/>[engine.go]"]
  node_siem["SIEM forwarding<br/>[sender.go]"]
  node_approvals["Approvals<br/>[approval.go]"]
end

node_sudo_user(("Sudo user"))
node_external_server(("Remote log server"))

node_sudo_user -->|"starts sudo"| node_plugin
node_plugin -->|"streams I/O"| node_agent
node_agent -->|"forwards sessions"| node_external_server
node_external_server -->|"receives sessions"| node_logserver
node_logserver -->|"signed ACKs"| node_agent
node_agent -.->|"frames messages"| node_protocol
node_logserver -->|"writes recordings"| node_iolog
node_logserver -.->|"stores sessions"| node_store
node_store -.->|"selects backend"| node_distributed
node_ebpf -->|"records sessions"| node_agent
node_agent -->|"detects bypasses"| node_divergence
node_replay_api -->|"opens recordings"| node_store
node_web_app -->|"routes sessions"| node_session_list
node_session_list -.->|"queries sessions"| node_replay_api
node_session_list -.->|"selects replay"| node_terminal
node_admin -.->|"manages policy"| node_policy
node_logserver -.->|"handles approvals"| node_approvals
node_logserver -.->|"forwards events"| node_siem

click node_plugin "https://github.com/alun-hub/sudo-logger/blob/main/plugin/plugin.c"
click node_agent "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/main.go"
click node_ebpf "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/bpf/recorder.c"
click node_divergence "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/divergence.go"
click node_protocol "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/protocol/protocol.go"
click node_logserver "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/server/session_conn.go"
click node_iolog "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/iolog/iolog.go"
click node_store "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/store/store.go"
click node_distributed "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/store/distributed.go"
click node_replay_api "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/handlers_session.go"
click node_web_app "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/App.tsx"
click node_session_list "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/components/sessions/SessionList.tsx"
click node_terminal "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/components/terminal/TerminalPlayer.tsx"
click node_admin "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/routes.go"
click node_policy "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/policy/engine.go"
click node_siem "https://github.com/alun-hub/sudo-logger/blob/main/go/internal/siem/sender.go"
click node_approvals "https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/server/approval.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_agent,node_ebpf,node_divergence,node_sudo_user toneBlue
class node_protocol toneAmber
class node_logserver,node_iolog,node_store,node_distributed,node_replay_api,node_external_server toneMint
class node_web_app,node_session_list,node_terminal,node_admin toneRose
class node_policy,node_siem,node_approvals toneIndigo
```

## Components

### Endpoint capture

- [Sudo I/O plugin](https://github.com/alun-hub/sudo-logger/blob/main/plugin/plugin.c): `plugin/plugin.c`
- [Local agent](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/main.go): `go/cmd/agent/main.go`
- [eBPF recorder](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/bpf/recorder.c): `go/cmd/agent/bpf/recorder.c`
- [Divergence detection](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/agent/divergence.go): `go/cmd/agent/divergence.go`

### Session transport

- [Wire protocol](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/protocol/protocol.go): `go/internal/protocol/protocol.go`

### Server and storage

- [Log server](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/server/session_conn.go): `go/cmd/server/session_conn.go`
- [Recording and redaction](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/iolog/iolog.go): `go/internal/iolog/iolog.go`
- [Session storage](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/store/store.go): `go/internal/store/store.go`
- [Distributed storage](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/store/distributed.go): `go/internal/store/distributed.go`
- [Replay API](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/handlers_session.go): `go/cmd/replay-server/handlers_session.go`

### Replay console

- [Web application](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/App.tsx): `go/cmd/replay-server/ui/src/App.tsx`
- [Session search](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/components/sessions/SessionList.tsx): `go/cmd/replay-server/ui/src/components/sessions/SessionList.tsx`
- [Session replay](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/ui/src/components/terminal/TerminalPlayer.tsx): `go/cmd/replay-server/ui/src/components/terminal/TerminalPlayer.tsx`
- [Admin controls](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/replay-server/routes.go): `go/cmd/replay-server/routes.go`

### Security controls

- [JIT policy engine](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/policy/engine.go): `go/internal/policy/engine.go`
- [SIEM forwarding](https://github.com/alun-hub/sudo-logger/blob/main/go/internal/siem/sender.go): `go/internal/siem/sender.go`
- [Approvals](https://github.com/alun-hub/sudo-logger/blob/main/go/cmd/server/approval.go): `go/cmd/server/approval.go`

### Other components

- **Sudo user**
- **Remote log server**

## Connections

- Sudo user → Sudo I/O plugin: starts sudo (evidence: `README.md`)
- Sudo I/O plugin → Local agent: streams I/O (evidence: `README.md`)
- Local agent → Remote log server: forwards sessions (evidence: `README.md`)
- Remote log server → Log server: receives sessions (evidence: `README.md`)
- Log server → Local agent: signed ACKs (evidence: `README.md`)
- Local agent → Wire protocol: frames messages
- Log server → Recording and redaction: writes recordings (evidence: `README.md`)
- Log server → Session storage: stores sessions
- Session storage → Distributed storage: selects backend
- eBPF recorder → Local agent: records sessions (evidence: `README.md`)
- Local agent → Divergence detection: detects bypasses (evidence: `README.md`)
- Replay API → Session storage: opens recordings (evidence: `go/cmd/replay-server/handlers_session.go`)
- Web application → Session search: routes sessions (evidence: `go/cmd/replay-server/ui/src/App.tsx`)
- Session search → Replay API: queries sessions
- Session search → Session replay: selects replay
- Admin controls → JIT policy engine: manages policy
- Log server → Approvals: handles approvals
- Log server → SIEM forwarding: forwards events