# sdslabs/watchdog architecture

> Architecture diagram of the GitHub repository sdslabs/watchdog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sdslabs/watchdog
- Repository: https://github.com/sdslabs/watchdog

## Overview

Watchdog is a single-binary server access manager: SSH public-key authorization is checked against Keyhouse (with a local-cache fallback), while PAM hooks report SSH, sudo, and su activity. The graph preserves the documented user/group update, configuration, and log capabilities. Several handlers and shared modules were not sampled, so their internal calls are omitted; documented command dispatch and PAM integration are shown without assuming additional wiring.

Main entry points: [`src/main.rs`](https://github.com/sdslabs/watchdog/blob/master/src/main.rs) (Command dispatcher), [`src/auth.rs`](https://github.com/sdslabs/watchdog/blob/master/src/auth.rs) (SSH authorization), [`src/lib/notifier.rs`](https://github.com/sdslabs/watchdog/blob/master/src/lib/notifier.rs) (Notification dispatch), [`src/lib/config.rs`](https://github.com/sdslabs/watchdog/blob/master/src/lib/config.rs) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_main["Command dispatcher<br/>[main.rs]"]
end

subgraph group_access["Access control"]
  node_auth["SSH authorization<br/>[auth.rs]"]
  node_keyhouse["Keyhouse access data<br/>[keyhouse.rs]"]
  node_cache["Local key cache<br/>[utils.rs]"]
  node_update["User and group update<br/>[update.rs]"]
end

subgraph group_audit["Activity reporting"]
  node_ssh["SSH PAM handler<br/>[ssh.rs]"]
  node_sudo["Sudo PAM handler<br/>[sudo.rs]"]
  node_su["Su PAM handler<br/>[su.rs]"]
  node_notifier["Notification dispatch<br/>[notifier.rs]"]
end

subgraph group_shared["Shared services"]
  node_config["Configuration<br/>[config.rs]"]
  node_init["Runtime initialization<br/>[init.rs]"]
  node_logger["Logging and log queries<br/>[logger.rs]"]
  node_environment["PAM environment<br/>[environment.rs]"]
end

node_admin(("Administrator"))
node_sshd(("SSH / PAM"))
node_slack["Slack webhook"]
node_system[("Linux accounts")]

node_admin -->|"runs commands"| node_main
node_sshd -->|"invokes commands"| node_main
node_main -->|"dispatches auth"| node_auth
node_main -->|"dispatches ssh"| node_ssh
node_main -->|"dispatches sudo"| node_sudo
node_main -->|"dispatches su"| node_su
node_main -->|"dispatches update"| node_update
node_main -->|"queries logs"| node_logger
node_main -->|"config commands"| node_config
node_auth -->|"reads settings"| node_config
node_auth -->|"initializes"| node_init
node_auth -->|"validates key"| node_keyhouse
node_auth -->|"checks fallback"| node_cache
node_keyhouse -->|"reads access data"| node_slack
node_update -->|"reads access data"| node_keyhouse
node_update -->|"updates accounts"| node_system
node_ssh -->|"reads settings"| node_config
node_ssh -->|"initializes"| node_init
node_sudo -->|"reads settings"| node_config
node_sudo -->|"initializes"| node_init
node_su -->|"reads settings"| node_config
node_su -->|"initializes"| node_init
node_auth -->|"reports failed login"| node_notifier
node_ssh -->|"reports SSH activity"| node_notifier
node_sudo -->|"reports sudo activity"| node_notifier
node_su -->|"reports su activity"| node_notifier
node_notifier -.->|"posts summaries"| node_slack
node_sshd -->|"provides PAM context"| node_environment
node_admin -->|"requests logs"| node_logger

click node_main "https://github.com/sdslabs/watchdog/blob/master/src/main.rs"
click node_auth "https://github.com/sdslabs/watchdog/blob/master/src/auth.rs"
click node_keyhouse "https://github.com/sdslabs/watchdog/blob/master/src/lib/keyhouse.rs"
click node_cache "https://github.com/sdslabs/watchdog/blob/master/src/lib/utils.rs"
click node_update "https://github.com/sdslabs/watchdog/blob/master/src/update.rs"
click node_ssh "https://github.com/sdslabs/watchdog/blob/master/src/ssh.rs"
click node_sudo "https://github.com/sdslabs/watchdog/blob/master/src/sudo.rs"
click node_su "https://github.com/sdslabs/watchdog/blob/master/src/su.rs"
click node_notifier "https://github.com/sdslabs/watchdog/blob/master/src/lib/notifier.rs"
click node_config "https://github.com/sdslabs/watchdog/blob/master/src/lib/config.rs"
click node_init "https://github.com/sdslabs/watchdog/blob/master/src/lib/init.rs"
click node_logger "https://github.com/sdslabs/watchdog/blob/master/src/lib/logger.rs"
click node_environment "https://github.com/sdslabs/watchdog/blob/master/src/lib/environment.rs"

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_main toneBlue
class node_auth,node_keyhouse,node_cache,node_update,node_system toneAmber
class node_ssh,node_sudo,node_su,node_notifier,node_slack toneMint
class node_config,node_init,node_logger,node_environment toneRose
class node_admin,node_sshd toneIndigo
```

## Components

### Entrypoints

- [Command dispatcher](https://github.com/sdslabs/watchdog/blob/master/src/main.rs): `src/main.rs`

### Access control

- [SSH authorization](https://github.com/sdslabs/watchdog/blob/master/src/auth.rs): `src/auth.rs`
- [Keyhouse access data](https://github.com/sdslabs/watchdog/blob/master/src/lib/keyhouse.rs): `src/lib/keyhouse.rs`
- [Local key cache](https://github.com/sdslabs/watchdog/blob/master/src/lib/utils.rs): `src/lib/utils.rs`
- [User and group update](https://github.com/sdslabs/watchdog/blob/master/src/update.rs): `src/update.rs`

### Activity reporting

- [SSH PAM handler](https://github.com/sdslabs/watchdog/blob/master/src/ssh.rs): `src/ssh.rs`
- [Sudo PAM handler](https://github.com/sdslabs/watchdog/blob/master/src/sudo.rs): `src/sudo.rs`
- [Su PAM handler](https://github.com/sdslabs/watchdog/blob/master/src/su.rs): `src/su.rs`
- [Notification dispatch](https://github.com/sdslabs/watchdog/blob/master/src/lib/notifier.rs): `src/lib/notifier.rs`

### Shared services

- [Configuration](https://github.com/sdslabs/watchdog/blob/master/src/lib/config.rs): `src/lib/config.rs`
- [Runtime initialization](https://github.com/sdslabs/watchdog/blob/master/src/lib/init.rs): `src/lib/init.rs`
- [Logging and log queries](https://github.com/sdslabs/watchdog/blob/master/src/lib/logger.rs): `src/lib/logger.rs`
- [PAM environment](https://github.com/sdslabs/watchdog/blob/master/src/lib/environment.rs): `src/lib/environment.rs`

### Other components

- **Administrator**
- **SSH / PAM**
- **Slack webhook**
- **Linux accounts**

## Connections

- Administrator → Command dispatcher: runs commands
- SSH / PAM → Command dispatcher: invokes commands
- Command dispatcher → SSH authorization: dispatches auth
- Command dispatcher → SSH PAM handler: dispatches ssh
- Command dispatcher → Sudo PAM handler: dispatches sudo
- Command dispatcher → Su PAM handler: dispatches su
- Command dispatcher → User and group update: dispatches update
- Command dispatcher → Logging and log queries: queries logs
- Command dispatcher → Configuration: config commands
- SSH authorization → Configuration: reads settings
- SSH authorization → Runtime initialization: initializes
- SSH authorization → Keyhouse access data: validates key
- SSH authorization → Local key cache: checks fallback
- Keyhouse access data → Slack webhook: reads access data
- User and group update → Keyhouse access data: reads access data
- User and group update → Linux accounts: updates accounts
- SSH PAM handler → Configuration: reads settings
- SSH PAM handler → Runtime initialization: initializes
- Sudo PAM handler → Configuration: reads settings
- Sudo PAM handler → Runtime initialization: initializes
- Su PAM handler → Configuration: reads settings
- Su PAM handler → Runtime initialization: initializes
- SSH authorization → Notification dispatch: reports failed login
- SSH PAM handler → Notification dispatch: reports SSH activity
- Sudo PAM handler → Notification dispatch: reports sudo activity
- Su PAM handler → Notification dispatch: reports su activity
- Notification dispatch → Slack webhook: posts summaries
- SSH / PAM → PAM environment: provides PAM context
- Administrator → Logging and log queries: requests logs