# security-onion-solutions/securityonion architecture

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

- Interactive diagram: https://gitdiagram.com/security-onion-solutions/securityonion
- Repository: https://github.com/security-onion-solutions/securityonion

## Overview

##### Main Components
- Central Data Processing & Analysis: This includes the pipelines that ingest and process the raw log or network data. Look for components related to “logstash”, “elastalert”, “elasticfleet”, “elasticagent”, and “kibana” – part of the Elastic Stack for data indexing, search, and visualization.
- Management and Orchestration: There are plenty of Salt configuration files (under “salt/”, “pillar/”, etc.) that show how different aspects (firewall, healthcheck, patching, idh, etc.) are configured and orchestrated across the security infrastructure.
- User Interface & Dashboards: The screenshots in the README indicate visual interfaces for Alerts, Dashboards, Hunt, PCAP, Grid, and Config. These are primarily provided using Kibana and other frontend web interfaces (managed via components like “salt/kibana” and “salt/nginx”).
- Supporting and Utility Components: Other subcomponents include tools for backup, scheduling, and agent management (e.g., “salt/backup”, “salt/manager”, “salt/logrotate”, “salt/telegraf”, “salt/pcap”, “salt/strelka”, etc.) which are integral to the overall operation.

##### Relationships and Interactions
- Data Flow: Show data generating at the sensor layer (using Zeek, Suricata, additional analyzers in “salt/sensoroni/files/analyzers”) that forward logs and alerts through the network. This data is then collected by centralized processors and forwarded to the Elastic Stack (Elasticsearch, Logstash, Kibana, and related integrations).
- Orchestration: Illustrate how SaltStack acts as a configuration management and orchestration layer (represented by “salt/_modules”, “salt/common”, “salt/manager”, etc.) that coordinates policies, configuration files (pillars), and highstate runs across distributed nodes (sensors, managers, etc.).
- UI & Administration: Highlight the connection between data processing (Elastic Stack) and the web-based dashboards, alerts, and configuration interfaces – components that provide the operational view of the network such as alert visualization, detection hunt, and PCAP analysis.

##### Architectural Patterns and Design Principles
- Modular and Distributed Architecture: Emphasize the fact that Security Onion is built as a distributed system with many modular components (sensor nodes, ingestion pipelines, central repositories, and UI layers) that communicate via well-defined APIs and configuration management.
- Configuration Management and Infrastructure as Code: The project uses SaltStack for managing configurations (with “pillar” files, Salt modules, and orchestrator states). Show how these “infrastructure as code” aspects integrate with the overall system.
- Data Ingestion and Processing Pipeline: The design follows a pipeline that collects, processes, indexes, and visualizes large volumes of network security data. Each stage (data collection, processing, storage, and visualization) should be clearly represented.

##### Relevant Technologies and Frameworks
- SaltStack: Configuration management and orchestration.
- Elastic Stack: Elasticsearch, Logstash, Kibana (with additional packages like elasticagent, elasticfleet) for data indexing and visualization.
- Network Sensors: Zeek, Suricata, and other custom analyzers (located in the “salt/sensoroni/files/analyzers” directory) to process network events.
- Supporting Utilities: Docker, Nginx, Telegraf, and other utility scripts play supporting roles in deployment and operational tasks.

- Use clear labels for each module/component and name them explicitly (e.g., “Sensor Nodes (Zeek/Suricata)”, “Data Ingestion (Logstash pipelines)”, “Indexing & Storage (Elasticsearch)”, “Visualization (Kibana Dashboard)”, “Configuration & Orchestration (SaltStack)”, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sensors & Data Collection Agents
    subgraph "Sensors & Data Collection"
        sensor1["Sensor (salt/sensor)"]:::sensors
        sensoroni["Sensoroni (salt/sensoroni)"]:::sensors
        zeek["Zeek (salt/zeek)"]:::sensors
        suricata["Suricata (salt/suricata)"]:::sensors
    end

    %% Central Data Processing & Analysis
    subgraph "Central Data Processing & Analysis"
        logstash["Logstash Pipelines"]:::processing
        elasticsearch["Indexing & Storage (Elasticsearch)"]:::processing
        elasticagent["Elastic Agent"]:::processing
        elasticfleet["Elastic Fleet"]:::processing
        elastalert["Alerting (Elastalert)"]:::processing
    end

    %% Management and Orchestration
    subgraph "Management and Orchestration"
        saltstack["SaltStack Orchestration"]:::management
        pillar["Pillar Configurations"]:::management
    end

    %% User Interface & Dashboards
    subgraph "User Interface & Dashboards"
        kibana["Kibana Dashboard"]:::ui
        nginx["Frontend (Nginx)"]:::ui
    end

    %% Supporting and Utility Components
    subgraph "Supporting and Utility Components"
        backup["Backup"]:::support
        logrotate["Logrotate"]:::support
        telegraf["Telegraf Agent"]:::support
        pcap["PCAP Analysis"]:::support
        strelka["Strelka Analyzer"]:::support
        reactor["Reactor Engine"]:::support
    end

    %% Data Flow Connections
    sensor1 -->|"sends_data"| logstash
    sensoroni -->|"sends_data"| logstash
    zeek -->|"sends_data"| logstash
    suricata -->|"sends_data"| logstash

    logstash -->|"processes_data"| elasticsearch
    logstash -->|"integrates_with"| elasticagent
    elasticagent -->|"works_with"| elasticfleet
    elasticsearch -->|"alerts_data"| elastalert
    elasticsearch -->|"indexes_data"| kibana
    kibana -->|"served_by"| nginx

    %% Management & Orchestration Connections
    pillar -->|"defines_config"| saltstack
    saltstack -->|"configures"| sensor1
    saltstack -->|"configures"| sensoroni
    saltstack -->|"configures"| zeek
    saltstack -->|"configures"| suricata
    saltstack -->|"manages"| logstash
    saltstack -->|"manages"| elasticsearch

    %% Supporting Components Connections
    backup -->|"supports"| saltstack
    logrotate -->|"supports"| saltstack
    telegraf -->|"monitors"| elasticsearch
    pcap -->|"analyzes"| sensor1
    pcap -->|"analyzes"| logstash
    strelka -->|"analyzes"| sensoroni
    reactor -->|"triggers"| saltstack

    %% Click Events for Sensors & Data Collection Agents
    click sensor1 "https://github.com/security-onion-solutions/securityonion/blob/2.4/main/salt/sensor/init.sls"
    click sensoroni "https://github.com/security-onion-solutions/securityonion/blob/2.4/main/salt/sensoroni/init.sls"
    click zeek "https://github.com/security-onion-solutions/securityonion/blob/2.4/main/salt/zeek/init.sls"
    click suricata "https://github.com/security-onion-solutions/securityonion/blob/2.4/main/salt/suricata/init.sls"

    %% Click Events for Central Data Processing & Analysis
    click logstash "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/logstash/pipelines"
    click elasticsearch "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/elasticsearch"
    click elasticagent "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/elasticagent"
    click elasticfleet "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/elasticfleet"
    click elastalert "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/elastalert"

    %% Click Events for Management and Orchestration
    click saltstack "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/_modules"
    click pillar "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/pillar/"

    %% Click Events for User Interface & Dashboards
    click kibana "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/kibana"
    click nginx "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/nginx"

    %% Click Events for Supporting and Utility Components
    click backup "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/backup"
    click logrotate "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/logrotate"
    click telegraf "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/telegraf"
    click pcap "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/pcap"
    click strelka "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/strelka"
    click reactor "https://github.com/security-onion-solutions/securityonion/tree/2.4/main/salt/reactor"

    %% Styles
    classDef sensors fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef processing fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef management fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef ui fill:#ffffcc,stroke:#ffd700,stroke-width:2px;
    classDef support fill:#ffe4b5,stroke:#d2691e,stroke-width:2px;
```
