# soobinzinzin/mini-soc-dashboard architecture

> Architecture diagram of the GitHub repository soobinzinzin/mini-soc-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soobinzinzin/mini-soc-dashboard
- Repository: https://github.com/soobinzinzin/mini-soc-dashboard

## Overview

Mini-SOC Lab simulates three site networks, detects attacks with Snort sensors, and includes a shipper-to-central-API telemetry workflow. An operator exercises the lab through the attacker and can inspect sensor alerts; the agent tails and parses Snort fast-alert lines, then forwards telemetry to the API, which validates, buffers, and exposes records and aggregate statistics. The README describes the three-site topology and alerting; source excerpts show the agent and API internals. The README’s future PostgreSQL and dashboard integrations are not implemented here.

Main entry points: [`central/main.py`](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/main.py) (Ingestion API), [`sensor/snort.conf`](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/sensor/snort.conf) (Snort sensors), [`agent/agent.py`](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/agent/agent.py) (Shipper agent), [`attacker`](https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/attacker) (Attacker container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lab["Attack Lab"]
  node_attacker["Attacker container"]
  node_victims["Site victims"]
end

subgraph group_detection["Site Detection"]
  node_snort["Snort sensors<br/>[snort.conf]"]
  node_rules["Detection rules<br/>[local.rules]"]
  node_alertlog["Fast alert log"]
end

subgraph group_shipping["Telemetry Shipping"]
  node_shipper["Shipper agent<br/>[agent.py]"]
  node_parser["Alert parser<br/>[agent.py]"]
end

subgraph group_central["Central API"]
  node_api["Ingestion API<br/>[main.py]"]
  node_schemas["Telemetry schemas<br/>[schemas.py]"]
  node_buffer[("Telemetry buffer<br/>[main.py]")]
end

node_operator(("Lab operator"))
node_readers(("API consumers"))

node_operator -->|"runs tests"| node_attacker
node_attacker -->|"attacks"| node_victims
node_victims -->|"network monitored"| node_snort
node_snort -.->|"uses rules"| node_rules
node_snort -->|"emits alerts"| node_alertlog
node_shipper -->|"tails"| node_alertlog
node_shipper -->|"parses lines"| node_parser
node_parser -->|"posts telemetry"| node_api
node_api -->|"validates payload"| node_schemas
node_api -->|"appends records"| node_buffer
node_api -->|"reads records"| node_buffer
node_readers -->|"queries telemetry"| node_api

click node_attacker "https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/attacker"
click node_victims "https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/victim"
click node_snort "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/sensor/snort.conf"
click node_rules "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/sensor/local.rules"
click node_alertlog "https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/sensor"
click node_shipper "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/agent/agent.py"
click node_parser "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/agent/agent.py"
click node_api "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/main.py"
click node_schemas "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/schemas.py"
click node_buffer "https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/main.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_attacker,node_victims toneBlue
class node_snort,node_rules,node_alertlog toneAmber
class node_shipper,node_parser,node_readers toneMint
class node_api,node_schemas,node_buffer toneRose
class node_operator toneIndigo
```

## Components

### Attack Lab

- [Attacker container](https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/attacker): `attacker`
- [Site victims](https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/victim): `victim`

### Site Detection

- [Snort sensors](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/sensor/snort.conf): `sensor/snort.conf`
- [Detection rules](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/sensor/local.rules): `sensor/local.rules`
- [Fast alert log](https://github.com/soobinzinzin/mini-soc-dashboard/tree/main/sensor): `sensor`

### Telemetry Shipping

- [Shipper agent](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/agent/agent.py): `agent/agent.py`
- [Alert parser](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/agent/agent.py): `agent/agent.py`

### Central API

- [Ingestion API](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/main.py): `central/main.py`
- [Telemetry schemas](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/schemas.py): `central/schemas.py`
- [Telemetry buffer](https://github.com/soobinzinzin/mini-soc-dashboard/blob/main/central/main.py): `central/main.py`

### Other components

- **Lab operator**
- **API consumers**

## Connections

- Lab operator → Attacker container: runs tests (evidence: `README.md`)
- Attacker container → Site victims: attacks (evidence: `README.md`)
- Site victims → Snort sensors: network monitored (evidence: `README.md`)
- Snort sensors → Detection rules: uses rules
- Snort sensors → Fast alert log: emits alerts
- Shipper agent → Fast alert log: tails (evidence: `agent/agent.py`)
- Shipper agent → Alert parser: parses lines (evidence: `agent/agent.py`)
- Alert parser → Ingestion API: posts telemetry (evidence: `agent/agent.py`)
- Ingestion API → Telemetry schemas: validates payload (evidence: `central/main.py`)
- Ingestion API → Telemetry buffer: appends records (evidence: `central/main.py`)
- Ingestion API → Telemetry buffer: reads records (evidence: `central/main.py`)
- API consumers → Ingestion API: queries telemetry (evidence: `central/main.py`)