# sshlog/agent architecture

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

- Interactive diagram: https://gitdiagram.com/sshlog/agent
- Repository: https://github.com/sshlog/agent

## Overview

##### Main Components
- Daemon Process (core service):
- Located primarily in the “daemon” directory and composed of several logical modules:
▸ CLI Interface (daemon/cli): Handles direct user commands.
▸ Communication Layer (daemon/comms): Manages messaging between components (e.g., MQ clients/servers, event serialization).
▸ Event Handling (daemon/events): Processes and formats SSH events using an event bus.
▸ Plug-in Architecture (daemon/plugins): Divided into actions (e.g., sending emails, triggering syslog, etc.) and filters. This layer enables extensibility.
▸ Trackers (daemon/trackers): Likely used for tracking sessions and their states.
- libsshlog Library:
- Found in “libsshlog”; written in C++ (with associated Python bindings available in libsshlog/bindings/python). Contains components such as:
▸ eBPF Integration (libsshlog/bpf): Contains sources, headers, and scripts related to eBPF probes for SSH session monitoring.
▸ Event Serialization and SSH tracing (libsshlog/event_serializer.cpp, sshlog.cpp, and sshtrace_wrapper.cpp): These components are central in capturing SSH events and converting them into a format that the daemon processes.
- Packaging and Distribution:
- The “package” and “distros” directories: Provide build scripts and packaging configuration for generating OS-specific installable packages (DEB, RPM, etc.) and Docker images.
- Utilities and Build/Configuration Management:
- CMake build scripts (CMakeLists.txt and cmake/ subdirectory) and docker-related files (Dockerfile, .dockerignore) indicate the use of standard build and deployment pipelines.
- External Integration Points:
- The configuration files (e.g., from daemon/config_samples) allow administrators to customize behaviors like sending Slack notifications or directing logs to syslog.
- External systems such as Slack (for messaging), syslog servers, and statsd (for metrics) are part of the broader ecosystem.

##### Relationships and Interactions
- “Event Bus” in the events submodule, which receives data from eBPF probes (from libsshlog) and then disseminates events to the plugins.
- “libsshlog” with the Daemon – indicate that it provides low-level SSH session and event data (via eBPF probes and event serializers) that are consumed by the Daemon.
- External integrations as separate nodes:
- Slack, Syslog, and Statsd can be illustrated as “external services” that receive notifications or logs via dedicated action plugins.
- Packaging & deployment:
- A section for “Deployment” showing how distribution packages (Debian/RedHat installers) and Docker deployments feed into the overall production environment.

##### Architectural Patterns and Design Principles
- Modular Design and Separation of Concerns:
- Separate the functionality into distinct components (CLI, communications, event processing, plugins).
- Plug-in Architecture:
- That custom Python plugins extend core functionalities (e.g., filtering, action handling).
- Inter-process Communication:
- Dual Language Integration:
- Coexistence of C++ (for performance and low-level interaction with eBPF) and Python (for easier scripting and extensibility).

##### Relevant Technologies and Tools
- eBPF (for monitoring SSH sessions)
- CMake (as the build system)
- Docker (for containerized deployments)
- Packaging tools (for building DEB, RPM packages)
- External APIs/integrations (Slack, syslog, statsd)

##### Final Assembly
- SSH session initiation (via OpenSSH) leading to eBPF probes capturing data.
- How libsshlog processes these events and passes them to the daemon’s event bus.
- That the daemon distributes events to plugins (action and filter plugins) and exposes a control interface (CLI).
- Incorporate side components such as configuration management and packaging infrastructure to complete the architecture overview.

## Diagram (Mermaid)

```mermaid
graph TD
  OSS["OpenSSH Session"]:::ext
  
  subgraph "libsshlog Library"
    EBI["eBPF Integration"]:::lib
    ES["Event Serialization"]:::lib
    STW["SSH Trace Wrapper"]:::lib
    PBS["Python Bindings"]:::lib
    EBI --> ES
    EBI --> STW
    ES --> PBS
  end
  
  OSS --> EBI
  ES --> DGN["SSHLog Daemon Process"]:::daemon
  STW --> DGN
  PBS --> DGN

  subgraph "SSHLog Daemon Modules"
    CLI["CLI Interface"]:::daemon
    COM["Communication Layer"]:::daemon
    EVT["Event Handling"]:::daemon
    PLG["Plug-in Architecture"]:::daemon
    TRK["Session Trackers"]:::daemon
    CLI --> DGN
    COM --> DGN
    EVT --> DGN
    PLG --> DGN
    TRK --> DGN
  end

  PLG --> SLK["Slack"]:::ext
  PLG --> SYS["Syslog"]:::ext
  PLG --> STD["Statsd"]:::ext
  
  EIC["Ext Integration Configs"]:::ext
  EIC --> PLG

  subgraph "Deployment & Packaging"
    PKG["Packaging & Distribution"]:::pkg
    DR["Distribution (Debian/RedHat)"]:::pkg
    PKG --> DR
  end
  DGN --> PKG

  subgraph "Build & Configuration"
    CMAKE["CMake (CMakeLists.txt)"]:::build
    CMAKE_MOD["CMake Modules (cmake)"]:::build
    DOCKER["Dockerfile"]:::build
    DOCKERIG[".dockerignore"]:::build
    CMAKE --> CMAKE_MOD
    CMAKE --> DOCKER
    DOCKER --> DOCKERIG
  end
  DOCKERIG --> PKG
  CMAKE --> DGN

  %% Click Events
  click DGN "https://github.com/sshlog/agent/blob/master/daemon/daemon.py"
  click CLI "https://github.com/sshlog/agent/tree/master/daemon/cli"
  click COM "https://github.com/sshlog/agent/tree/master/daemon/comms"
  click EVT "https://github.com/sshlog/agent/tree/master/daemon/events"
  click PLG "https://github.com/sshlog/agent/tree/master/daemon/plugins"
  click TRK "https://github.com/sshlog/agent/tree/master/daemon/trackers"
  click EBI "https://github.com/sshlog/agent/tree/master/libsshlog/bpf"
  click ES "https://github.com/sshlog/agent/blob/master/libsshlog/event_serializer.cpp"
  click STW "https://github.com/sshlog/agent/blob/master/libsshlog/sshtrace_wrapper.cpp"
  click PBS "https://github.com/sshlog/agent/tree/master/libsshlog/bindings/python/sshlog"
  click PKG "https://github.com/sshlog/agent/tree/master/package"
  click DR "https://github.com/sshlog/agent/tree/master/distros"
  click CMAKE "https://github.com/sshlog/agent/blob/master/CMakeLists.txt"
  click CMAKE_MOD "https://github.com/sshlog/agent/tree/master/cmake"
  click DOCKER "https://github.com/sshlog/agent/tree/master/Dockerfile"
  click DOCKERIG "https://github.com/sshlog/agent/blob/master/.dockerignore"
  click EIC "https://github.com/sshlog/agent/tree/master/daemon/config_samples"

  %% Styles
  classDef daemon fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
  classDef lib fill:#90EE90,stroke:#006400,stroke-width:2px;
  classDef ext fill:#FFD700,stroke:#B8860B,stroke-width:2px;
  classDef build fill:#D3D3D3,stroke:#696969,stroke-width:2px;
  classDef pkg fill:#FFA07A,stroke:#CD5C5C,stroke-width:2px;
```
