# secureworks/dalton architecture

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

- Interactive diagram: https://gitdiagram.com/secureworks/dalton
- Repository: https://github.com/secureworks/dalton

## Overview

##### Project type and purpose
- Dalton is an open‐source, Docker‐orchestrated IDS-testing platform.
- It provides a Flask-based web “controller” (UI + HTTP/REST API) and one or more “agent” processes that run IDS engines (Snort, Suricata, Zeek) on user-supplied pcaps and rulesets.
- A Redis server is used as a job queue and result store; Nginx acts as a reverse proxy; all pieces are wired together via Docker Compose.

##### File structure
- Top-level: docker-compose.yml, Dockerfiles, .env, start-dalton.sh, run.py → orchestrate containers and launch scripts.
- /app: Flask controller code (dalton.py, flowsynth.py, certsynth.py), static files (JS/CSS, engine‐configs, rulesets), and Jinja2 templates for UI.
- /api: Python client wrapper and examples for programmatic job submission.
- /dalton-agent: Python agent code + Dockerfiles to build sensor containers embedding Snort/Suricata/Zeek.
- /engine-configs, /rulesets: persisted on controller container and shared into Docker for runtime sensor configs and rule files.
- /nginx-conf: Nginx config and TLS certs.
- tests: pytest tests for controller and Flowsynth module.

##### Key insights from README
- **Controller**:
- Written in Python/Flask with REST and web UI.
- Uses Redis for job queuing, storing transient job data and results.
- Stores job archives on disk (/opt/dalton/jobs).
- Exposes API endpoints under /dalton/controller_api and /dalton/sensor_api.
- **Agents**:
- Poll controller frequently over HTTP to fetch pending jobs.
- Run job: download pcap(s), ruleset, config; invoke IDS engine; collect alerts, logs, profiling data; POST results back.
- **Flowsynth WebUI**: integrated into controller to generate custom pcaps.
- **Docker**: everything is containerized: Nginx, Redis, controller, one or more agent containers, optional CyberChef.

##### Detail is key – capture all critical elements
- Docker service (nginx, controller, redis, agent-suricata-<version>, agent-snort-<version>, cyberchef).
- Shared mounts: rulesets → controller & nginx; engine-configs → controller & nginx; jobs directory → controller & nginx.
- Polling interval of agents (e.g. “Agent polls /controller_api for jobs every 1s”).
- “teapot” vs “regular” job TTL differences in Redis (optional annotation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Orchestrator
    subgraph "Docker Compose Orchestrator"
        Compose["docker-compose.yml"]:::ext
        StartScript["start-dalton.sh"]:::ext
        RunScript["run.py"]:::ext
        DockerfileDalton["Dockerfile-dalton"]:::ext
        DockerfileNginx["Dockerfile-nginx"]:::ext
    end

    %% User Layer
    subgraph "User Layer"
        Browser["User Web Browser"]:::ext
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        Nginx["Nginx Reverse Proxy"]:::web
    end

    %% Controller Layer
    subgraph "Controller Service"
        ControllerApp["Controller: Flask App"]:::web
        StaticAssets["Static Assets"]:::web
        Templates["Jinja2 Templates"]:::web
        FileStore["Disk Storage (/opt/dalton/jobs,\nengine-configs, rulesets)"]:::db
    end

    %% Data Store
    subgraph "Data Store"
        Redis["Redis Job Queue & Result Store"]:::db
    end

    %% Worker Layer
    subgraph "Agent Services"
        AgentSnort["Agent: Snort Container"]:::agent
        AgentSuricata["Agent: Suricata Container"]:::agent
        AgentZeek["Agent: Zeek Container"]:::agent
    end

    CyberChef["CyberChef Container (Optional)"]:::web

    %% Connections
    Browser --> Nginx
    Nginx --> ControllerApp
    ControllerApp --> Redis
    Redis --> ControllerApp
    ControllerApp --> FileStore
    ControllerApp --> StaticAssets
    ControllerApp --> Templates

    AgentSnort -->|"poll /controller_api"| ControllerApp
    AgentSuricata -->|"poll /controller_api"| ControllerApp
    AgentZeek -->|"poll /controller_api"| ControllerApp

    AgentSnort -->|"download jobs via sensor_api"| ControllerApp
    AgentSuricata -->|"download jobs via sensor_api"| ControllerApp
    AgentZeek -->|"download jobs via sensor_api"| ControllerApp

    AgentSnort -->|"POST results"| ControllerApp
    AgentSuricata -->|"POST results"| ControllerApp
    AgentZeek -->|"POST results"| ControllerApp

    ControllerApp -->|"push result data"| Redis

    Browser -->|"poll job status/results"| ControllerApp

    %% Click Events
    click Compose "https://github.com/secureworks/dalton/blob/master/docker-compose.yml"
    click StartScript "https://github.com/secureworks/dalton/blob/master/start-dalton.sh"
    click RunScript "https://github.com/secureworks/dalton/blob/master/run.py"
    click DockerfileDalton "https://github.com/secureworks/dalton/tree/master/Dockerfile-dalton"
    click DockerfileNginx "https://github.com/secureworks/dalton/tree/master/Dockerfile-nginx"

    click Nginx "https://github.com/secureworks/dalton/blob/master/nginx-conf/nginx.conf"
    click ControllerApp "https://github.com/secureworks/dalton/blob/master/app/dalton.py"
    click StaticAssets "https://github.com/secureworks/dalton/tree/master/app/static/"
    click Templates "https://github.com/secureworks/dalton/tree/master/app/templates/"
    click ControllerApp "https://github.com/secureworks/dalton/blob/master/app/flowsynth.py"
    click ControllerApp "https://github.com/secureworks/dalton/blob/master/app/certsynth.py"
    click ControllerApp "https://github.com/secureworks/dalton/blob/master/app/__init__.py"

    click AgentSnort "https://github.com/secureworks/dalton/blob/master/dalton-agent/dalton-agent.py"
    click AgentSnort "https://github.com/secureworks/dalton/blob/master/dalton-agent/dalton-agent.conf"
    click AgentSnort "https://github.com/secureworks/dalton/tree/master/dalton-agent/Dockerfiles/Dockerfile_snort"
    click AgentSuricata "https://github.com/secureworks/dalton/tree/master/dalton-agent/Dockerfiles/Dockerfile_suricata"
    click AgentZeek "https://github.com/secureworks/dalton/tree/master/dalton-agent/Dockerfiles/Dockerfile_zeek"

    %% Styles
    classDef web fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef db fill:#DFFFE0,stroke:#228B22,color:#228B22
    classDef agent fill:#FFE8A1,stroke:#D2691E,color:#D2691E
    classDef ext fill:#EEEEEE,stroke:#888888,color:#555555
```
