# rachidafaf/cyb691-it691-capstoneprojectfall2026 architecture

> Architecture diagram of the GitHub repository rachidafaf/cyb691-it691-capstoneprojectfall2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rachidafaf/cyb691-it691-capstoneprojectfall2026
- Repository: https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026

## Overview

This repository is an OT cybersecurity monitoring testbed and analysis pipeline. Operators can generate baseline Modbus polling and unauthorized writes against a PLC emulator; the resulting Suricata/firewall telemetry is normalized, then consumed by incident triage and ML evaluation. Triage produces both structured and Markdown reports, while ML produces benchmark results. The README also describes microsegmentation and security hardening, but the tree and sampled runtime code do not show an implementation of those controls. Some parser wiring is based on README documentation because its full source was not sampled.

Main entry points: [`data/normalized_telemetry.json`](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/normalized_telemetry.json) (Normalized Telemetry), [`src/timeline_generator.py`](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/timeline_generator.py) (Incident Triage), [`src/log_parser.py`](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/log_parser.py) (Telemetry Parser), [`infrastructure/traffic_generator.py`](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/traffic_generator.py) (Modbus Traffic Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_testbed["OT Testbed"]
  node_generator["Modbus Traffic Generator"]
  node_plc["PLC Emulator"]
  node_monitoring["Suricata / pfSense"]
  node_eve["Suricata EVE Logs<br/>[eve.json]"]
  node_sample_alert["Sample Alert"]
end

subgraph group_normalization["Telemetry Normalization"]
  node_handoff["Telemetry Handoff"]
  node_parser["Telemetry Parser<br/>[log_parser.py]"]
  node_normalized["Normalized Telemetry"]
end

subgraph group_analysis["Detection &amp; Triage"]
  node_timeline["Incident Triage"]
  node_ml["ML Detection<br/>[ml_detector.py]"]
end

subgraph group_outputs["Analysis Artifacts"]
  node_incident_report["Incident Metrics"]
  node_incident_timeline["Incident Timeline"]
  node_ml_results["ML Benchmarks"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_generator
node_generator -->|"sends Modbus"| node_plc
node_plc -.->|"generates traffic"| node_monitoring
node_monitoring -.->|"records events"| node_eve
node_monitoring -.->|"emits alerts"| node_sample_alert
node_eve -->|"ingests logs"| node_parser
node_handoff -->|"extracts archive"| node_parser
node_parser -->|"writes records"| node_normalized
node_normalized -->|"reads telemetry"| node_timeline
node_normalized -->|"reads telemetry"| node_ml
node_timeline -->|"writes metrics"| node_incident_report
node_timeline -->|"writes timeline"| node_incident_timeline
node_ml -->|"writes benchmarks"| node_ml_results

click node_generator "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/traffic_generator.py"
click node_eve "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/extracted_handoff/var/log/suricata/eve.json"
click node_sample_alert "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/logs/sample_suricata_alert.json"
click node_handoff "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/ot_telemetry_handoff_2026-09-26.tar.gz"
click node_parser "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/log_parser.py"
click node_normalized "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/normalized_telemetry.json"
click node_timeline "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/timeline_generator.py"
click node_ml "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/ml_detector.py"
click node_incident_report "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/incident_report.json"
click node_incident_timeline "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/incident_timeline.md"
click node_ml_results "https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/ml_evaluation_results.json"

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_generator,node_plc,node_monitoring,node_eve,node_sample_alert toneBlue
class node_handoff,node_parser,node_normalized toneAmber
class node_timeline,node_ml toneMint
class node_incident_report,node_incident_timeline,node_ml_results toneRose
class node_operator toneIndigo
```

## Components

### OT Testbed

- [Modbus Traffic Generator](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/traffic_generator.py): `infrastructure/traffic_generator.py`
- **PLC Emulator**
- **Suricata / pfSense**
- [Suricata EVE Logs](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/extracted_handoff/var/log/suricata/eve.json): `infrastructure/extracted_handoff/var/log/suricata/eve.json`
- [Sample Alert](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/logs/sample_suricata_alert.json): `infrastructure/logs/sample_suricata_alert.json`

### Telemetry Normalization

- [Telemetry Handoff](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/infrastructure/ot_telemetry_handoff_2026-09-26.tar.gz): `infrastructure/ot_telemetry_handoff_2026-09-26.tar.gz`
- [Telemetry Parser](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/log_parser.py): `src/log_parser.py`
- [Normalized Telemetry](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/normalized_telemetry.json): `data/normalized_telemetry.json`

### Detection & Triage

- [Incident Triage](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/timeline_generator.py): `src/timeline_generator.py`
- [ML Detection](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/src/ml_detector.py): `src/ml_detector.py`

### Analysis Artifacts

- [Incident Metrics](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/incident_report.json): `data/incident_report.json`
- [Incident Timeline](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/incident_timeline.md): `data/incident_timeline.md`
- [ML Benchmarks](https://github.com/rachidafaf/cyb691-it691-capstoneprojectfall2026/blob/main/data/ml_evaluation_results.json): `data/ml_evaluation_results.json`

### Other components

- **Operator**

## Connections

- Operator → Modbus Traffic Generator: runs
- Modbus Traffic Generator → PLC Emulator: sends Modbus
- PLC Emulator → Suricata / pfSense: generates traffic
- Suricata / pfSense → Suricata EVE Logs: records events
- Suricata / pfSense → Sample Alert: emits alerts
- Suricata EVE Logs → Telemetry Parser: ingests logs
- Telemetry Handoff → Telemetry Parser: extracts archive
- Telemetry Parser → Normalized Telemetry: writes records
- Normalized Telemetry → Incident Triage: reads telemetry
- Normalized Telemetry → ML Detection: reads telemetry
- Incident Triage → Incident Metrics: writes metrics
- Incident Triage → Incident Timeline: writes timeline
- ML Detection → ML Benchmarks: writes benchmarks