# dulmina-hasith/sentinelx architecture

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

- Interactive diagram: https://gitdiagram.com/dulmina-hasith/sentinelx
- Repository: https://github.com/dulmina-hasith/sentinelx

## Overview

SentinelX monitors Linux SSH authentication logs, turns matching records into per-IP severity alerts, persists escalation state, and exposes telemetry and a live dashboard. The principal runtime path is configuration and log selection, file tailing, parsing, alert evaluation, persistence, then WebSocket delivery. The graph also includes the dashboard/API and privilege dropping. Source excerpts show the main orchestration and detection implementation; dashboard details beyond its template path and other unsampled behavior are kept limited to documented capabilities.

Main entry points: [`run.py`](https://github.com/dulmina-hasith/sentinelx/blob/main/run.py) (Daemon orchestrator), [`core/alerts.py`](https://github.com/dulmina-hasith/sentinelx/blob/main/core/alerts.py) (Alert engine), [`config.py`](https://github.com/dulmina-hasith/sentinelx/blob/main/config.py) (Configuration loader), [`core/watcher.py`](https://github.com/dulmina-hasith/sentinelx/blob/main/core/watcher.py) (Log tail and rotation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime setup"]
  node_config["Configuration loader<br/>[config.py]"]
  node_daemon["Daemon orchestrator<br/>[run.py]"]
  node_privileges["Privilege dropping<br/>[privileges.py]"]
end

subgraph group_detection["Log detection"]
  node_watcher["Log tail and rotation<br/>[watcher.py]"]
  node_parser["SSH event parser<br/>[parser.py]"]
end

subgraph group_alerting["Alert state"]
  node_engine["Alert engine<br/>[alerts.py]"]
  node_state[("Alert state file")]
end

subgraph group_interface["Web interface"]
  node_dashboard["Dashboard template<br/>[index.html]"]
  node_management["Health and stats API<br/>[run.py]"]
  node_socketio["WebSocket transport<br/>[run.py]"]
end

node_operator(("Operator"))
node_authlog["SSH auth log"]
node_browser(("Dashboard user"))
node_environment["Environment settings"]

node_daemon -->|"loads settings"| node_config
node_environment -->|"overrides"| node_config
node_daemon -->|"selects log path"| node_environment
node_daemon -->|"starts tailing"| node_watcher
node_authlog -->|"appends records"| node_watcher
node_daemon -->|"parses lines"| node_parser
node_daemon -->|"processes events"| node_engine
node_engine -->|"loads and saves"| node_state
node_daemon -->|"emits alerts"| node_socketio
node_browser -->|"requests telemetry"| node_management
node_browser -->|"requests dashboard"| node_daemon
node_daemon -->|"renders page"| node_dashboard
node_browser -->|"receives alerts"| node_socketio
node_daemon -->|"drops privileges"| node_privileges

click node_config "https://github.com/dulmina-hasith/sentinelx/blob/main/config.py"
click node_daemon "https://github.com/dulmina-hasith/sentinelx/blob/main/run.py"
click node_privileges "https://github.com/dulmina-hasith/sentinelx/blob/main/core/privileges.py"
click node_watcher "https://github.com/dulmina-hasith/sentinelx/blob/main/core/watcher.py"
click node_parser "https://github.com/dulmina-hasith/sentinelx/blob/main/core/parser.py"
click node_engine "https://github.com/dulmina-hasith/sentinelx/blob/main/core/alerts.py"
click node_dashboard "https://github.com/dulmina-hasith/sentinelx/blob/main/templates/index.html"
click node_management "https://github.com/dulmina-hasith/sentinelx/blob/main/run.py"
click node_socketio "https://github.com/dulmina-hasith/sentinelx/blob/main/run.py"

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_config,node_daemon,node_privileges,node_browser toneBlue
class node_watcher,node_parser toneAmber
class node_engine,node_state toneMint
class node_dashboard,node_management,node_socketio toneRose
class node_operator,node_authlog,node_environment toneIndigo
```

## Components

### Runtime setup

- [Configuration loader](https://github.com/dulmina-hasith/sentinelx/blob/main/config.py): `config.py`
- [Daemon orchestrator](https://github.com/dulmina-hasith/sentinelx/blob/main/run.py): `run.py`
- [Privilege dropping](https://github.com/dulmina-hasith/sentinelx/blob/main/core/privileges.py): `core/privileges.py`

### Log detection

- [Log tail and rotation](https://github.com/dulmina-hasith/sentinelx/blob/main/core/watcher.py): `core/watcher.py`
- [SSH event parser](https://github.com/dulmina-hasith/sentinelx/blob/main/core/parser.py): `core/parser.py`

### Alert state

- [Alert engine](https://github.com/dulmina-hasith/sentinelx/blob/main/core/alerts.py): `core/alerts.py`
- **Alert state file**

### Web interface

- [Dashboard template](https://github.com/dulmina-hasith/sentinelx/blob/main/templates/index.html): `templates/index.html`
- [Health and stats API](https://github.com/dulmina-hasith/sentinelx/blob/main/run.py): `run.py`
- [WebSocket transport](https://github.com/dulmina-hasith/sentinelx/blob/main/run.py): `run.py`

### Other components

- **Operator**
- **SSH auth log**
- **Dashboard user**
- **Environment settings**

## Connections

- Daemon orchestrator → Configuration loader: loads settings
- Environment settings → Configuration loader: overrides
- Daemon orchestrator → Environment settings: selects log path
- Daemon orchestrator → Log tail and rotation: starts tailing
- SSH auth log → Log tail and rotation: appends records
- Daemon orchestrator → SSH event parser: parses lines
- Daemon orchestrator → Alert engine: processes events
- Alert engine → Alert state file: loads and saves
- Daemon orchestrator → WebSocket transport: emits alerts
- Dashboard user → Health and stats API: requests telemetry
- Dashboard user → Daemon orchestrator: requests dashboard
- Daemon orchestrator → Dashboard template: renders page
- Dashboard user → WebSocket transport: receives alerts
- Daemon orchestrator → Privilege dropping: drops privileges