# stamusnetworks/selks architecture

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

- Interactive diagram: https://gitdiagram.com/stamusnetworks/selks
- Repository: https://github.com/stamusnetworks/selks

## Overview

##### Project Type and Purpose
- SELKS is an open-source, Debian-based Network Security Monitoring (NSM) platform that integrates multiple specialized tools (Suricata, Elasticsearch, Logstash, Kibana, Scirius, EveBox, Arkime, CyberChef) into a cohesive, containerized/microservices-style monitoring solution.

##### File Structure Analysis
- Top-level:
- docker/ – Dockerfiles, Compose definitions, container config and bootstrap scripts
- kubernetes/ – Namespaces, Deployments, Services, ConfigMaps, StatefulSets for each component
- scripts/ – Upgrade and helper scripts for ISO/staging installations
- staging/ – Debian Live chroot hooks, packaging and default configs for ISO
- build-debian-live.sh, install-deps.sh – ISO build and host dependency scripts
- Each major component (Suricata, Elasticsearch, Logstash, Kibana, Scirius, EveBox, Arkime) has its own Dockerfile or Deployment YAML and supporting config under docker/containers-data or kubernetes/.

##### README Insights
- Confirms core pipeline:
1. Suricata captures and inspects network packets →
2. Emits JSON logs →
3. Ingested via Logstash (or Fluentd/Filebeat) →
4. Indexed in Elasticsearch →
5. Visualized in Kibana and EveBox →
6. Threat-hunt UI in Scirius; PCAP storage and search in Arkime; ad-hoc data analysis in CyberChef.
- Provides a list of default dashboards and indexes.

- Network Tap/Sensor (Suricata IDS)
- Log Collector (Logstash / Fluentd-Fluent Bit / Filebeat)
- Search & Storage (Elasticsearch cluster)
- Visualization & Dashboards (Kibana, EveBox)
- Threat Hunting UI (Scirius)
- Packet Capture Storage & Search (Arkime)
- Ad-hoc Analysis Tool (CyberChef)
- Reverse Proxy / Web Server (Nginx)
- Orchestration Layer (Docker Compose or Kubernetes)
- Supporting Services: Cron Jobs (rule updates, log rotation), System Services (Debian Live init scripts)
- External Integrations (optional alerts, exports to SIEM/SOAR)

1. Suricata → JSON logs → Logstash/Fluent Bit
2. Logstash → Elasticsearch
3. Elasticsearch ←→ Kibana (UI queries)
4. Elasticsearch ←→ Scirius (queries, index management)
5. Suricata PCAPs → Arkime (ingest) → Elasticsearch (metadata)
6. Elasticsearch ←→ EveBox (event viewer)
7. User Browsers → Nginx (TLS termination, routing) → Kibana / Scirius / EveBox / Arkime UI
8. CyberChef invoked by user with selected event/payload
9. Cron jobs → update Suricata rules, rotate logs, refresh templates

c. Architectural Patterns & Principles:
- Microservices/Containerization: each component isolated in its own container/deployment
- Event-driven pipeline: log generation → ingestion → indexing → visualization
- Stateless UIs + Stateful storage (Elasticsearch, Arkime PVs)
- Infrastructure-as-Code: Docker Compose & Kubernetes manifests for repeatable deployments
- Separation of concerns: sensor layer, processing layer, storage layer, presentation layer

d. Key Technologies & Configs:
- Suricata (IDS/NSM); custom YAML rules under docker/containers-data/suricata
- Logstash config (docker/containers-data/logstash/conf.d/logstash.conf)
- Elasticsearch (StatefulSet, PV/PVC)
- Kibana (Deployment + Dashboards job)
- Scirius (Deployment, Web UI, uses own PV/PVC for rule DB)
- EveBox (Deployment + Service)
- Arkime (Dockerfile + startup script; uses large PV for PCAP storage)
- Nginx & OWASP-modsecurity for HTTPS and WAF functionality
- Fluentd/Fluent Bit and Filebeat for alternative log ingestion paths
- Debian Live ISO staging (hooks, default configs, polkit rules)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Infrastructure / Orchestration"
        Orch["Docker Compose / Kubernetes"]:::infra
        Nginx["Nginx (TLS/WAF)"]:::infra
        Cron["Cron Jobs"]:::infra
        ISO["Debian Live ISO Staging"]:::infra
        Deps["install-deps.sh"]:::infra
    end

    subgraph "Sensor Layer"
        Suricata["Suricata IDS"]:::sensor
    end

    subgraph "Ingestion Layer"
        Logstash["Logstash"]:::ingestion
        FluentBit["Fluent Bit / Fluentd"]:::ingestion
        Filebeat["Filebeat"]:::ingestion
    end

    subgraph "Storage Layer"
        ES["Elasticsearch Cluster"]:::storage
        ArkimePV["Arkime PCAP Storage"]:::storage
    end

    subgraph "Presentation Layer"
        Kibana["Kibana"]:::presentation
        Scirius["Scirius"]:::presentation
        EveBox["EveBox"]:::presentation
        ArkimeUI["Arkime UI"]:::presentation
        CyberChef["CyberChef"]:::presentation
    end

    Suricata -->|"JSON logs"| Logstash
    Suricata --> FluentBit
    Suricata --> Filebeat

    Logstash -->|"indices"| ES
    FluentBit --> ES
    Filebeat --> ES

    ES <--> Kibana
    ES <--> Scirius
    ES <--> EveBox

    Suricata -->|"PCAPs"| ArkimePV
    ArkimePV --> ArkimeUI
    ES --> ArkimeUI

    User["User Browser"]:::infra
    User --> Nginx
    Nginx --> Kibana
    Nginx --> Scirius
    Nginx --> EveBox
    Nginx --> ArkimeUI

    Kibana --> CyberChef
    Scirius --> CyberChef
    EveBox --> CyberChef

    Cron --> Suricata
    Cron --> Logstash
    Cron --> Kibana

    ISO --> Orch

    classDef sensor fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ingestion fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef storage fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef presentation fill:#d4edda,stroke:#155724,color:#155724;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;

    click Suricata "https://github.com/stamusnetworks/selks/tree/master/docker/containers-data/suricata/"
    click Suricata "https://github.com/stamusnetworks/selks/blob/master/kubernetes/suricata/suricata-daemonset.yaml"
    click Logstash "https://github.com/stamusnetworks/selks/blob/master/docker/containers-data/logstash/conf.d/logstash.conf"
    click Logstash "https://github.com/stamusnetworks/selks/blob/master/kubernetes/logstash_filebeat/logstash-statefulset.yaml"
    click ES "https://github.com/stamusnetworks/selks/blob/master/kubernetes/elasticsearch/elasticsearch-statefulset.yaml"
    click Kibana "https://github.com/stamusnetworks/selks/blob/master/kubernetes/kibana/kibana-deployment.yaml"
    click Scirius "https://github.com/stamusnetworks/selks/blob/master/kubernetes/scirius/scirius-deployment.yaml"
    click EveBox "https://github.com/stamusnetworks/selks/blob/master/kubernetes/evebox/evebox-deployment.yaml"
    click ArkimePV "https://github.com/stamusnetworks/selks/blob/master/docker/Arkime/Arkime.dockerfile"
    click ArkimePV "https://github.com/stamusnetworks/selks/blob/master/kubernetes/arkime/arkime-deployment.yaml"
    click Nginx "https://github.com/stamusnetworks/selks/blob/master/docker/containers-data/nginx/nginx.conf"
    click Nginx "https://github.com/stamusnetworks/selks/blob/master/kubernetes/nginx/nginx-deployment.yaml"
    click FluentBit "https://github.com/stamusnetworks/selks/blob/master/kubernetes/fluentd_fluent-bit/fluentbit-daemonset.yaml"
    click Filebeat "https://github.com/stamusnetworks/selks/blob/master/kubernetes/logstash_filebeat/filebeat-daemonset.yaml"
    click Cron "https://github.com/stamusnetworks/selks/tree/master/docker/containers-data/cron-jobs/"
    click Cron "https://github.com/stamusnetworks/selks/blob/master/kubernetes/scirius/scirius-cronjob.yaml"
    click ISO "https://github.com/stamusnetworks/selks/tree/master/staging/config/hooks/"
    click ISO "https://github.com/stamusnetworks/selks/blob/master/build-debian-live.sh"
    click Deps "https://github.com/stamusnetworks/selks/blob/master/install-deps.sh"
```
