# zhiyu-l/csc3104-honeypot-fl architecture

> Architecture diagram of the GitHub repository zhiyu-l/csc3104-honeypot-fl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhiyu-l/csc3104-honeypot-fl
- Repository: https://github.com/zhiyu-l/csc3104-honeypot-fl

## Overview

This repository implements federated honeypot intrusion detection: Cowrie sessions become labelled features, organisations train locally, and a coordinator aggregates model updates into versioned global models. A parallel dataset workflow splits training and replay data, then evaluates models. The README also documents nightly feature ingestion and a model API, though their implementation is not represented in the sampled source. Edges are limited to documented workflows and relationships visible in excerpts or the source index.

Main entry points: [`services/coordinator/src/fl_coordinator/server_app.py`](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/server_app.py) (Coordinator app), [`services/log-processor/process_replay.py`](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/log-processor/process_replay.py) (Replay processing), [`services/client/src/fl_client/task.py`](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/task.py) (Local training), [`tools/cowrie_dataset/cowrie_sessions.py`](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/cowrie_sessions.py) (Session labeling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_honeypot["Cowrie honeypots"]
  node_label["Session labeling<br/>[cowrie_sessions.py]"]
  node_split["Org data splits<br/>[split_orgs.py]"]
  node_replay["Replay test data<br/>[replay_testset.py]"]
end

subgraph group_features["Feature processing"]
  node_processor["Replay processing<br/>[process_replay.py]"]
  node_nightly["Nightly processing<br/>[nightly.py]"]
  node_featuredata[("Feature batches<br/>[data.py]")]
end

subgraph group_federated["Federated learning"]
  node_clientapp["Client app<br/>[client_app.py]"]
  node_clienttask["Local training<br/>[task.py]"]
  node_server["Coordinator app<br/>[server_app.py]"]
  node_runner["Fault-tolerant rounds<br/>[runner.py]"]
  node_strategies["Aggregation strategies<br/>[strategies.py]"]
  node_adaptive["Adaptive aggregation<br/>[adaptive.py]"]
  node_checkpoints[("Run checkpoints<br/>[checkpoints.py]")]
  node_publisher["Model promotion<br/>[publish.py]"]
end

subgraph group_shared["Shared model layer"]
  node_schema["Feature schema<br/>[schema.py]"]
  node_model["Shared classifier<br/>[model.py]"]
  node_evaluation["Model evaluation<br/>[evaluation.py]"]
  node_synthetic["Synthetic data<br/>[synthetic.py]"]
end

subgraph group_serving["Model serving"]
  node_modelapi["Model API"]
end

node_operator(("Pipeline operator"))
node_attacker(("SSH attacker"))

node_attacker -->|"sends traffic"| node_honeypot
node_honeypot -->|"produces logs"| node_label
node_label -->|"labels sessions"| node_split
node_label -->|"shares extractor"| node_processor
node_split -->|"provides training data"| node_clienttask
node_split -->|"provides held-out data"| node_replay
node_replay -->|"selects replay sessions"| node_processor
node_processor -->|"uses schema"| node_schema
node_processor -->|"writes feature batches"| node_featuredata
node_nightly -->|"invokes processing"| node_processor
node_nightly -->|"publishes batches"| node_featuredata
node_featuredata -->|"loads data"| node_clienttask
node_clientapp -->|"trains locally"| node_clienttask
node_clientapp -->|"loads weights"| node_model
node_clienttask -->|"validates features"| node_schema
node_clienttask -->|"uses fallback data"| node_synthetic
node_server -->|"initializes model"| node_model
node_server -->|"selects strategy"| node_strategies
node_server -->|"runs rounds"| node_runner
node_runner -->|"aggregates updates"| node_strategies
node_strategies -->|"uses adaptive logic"| node_adaptive
node_runner -.->|"dispatches rounds"| node_clientapp
node_server -->|"saves run"| node_checkpoints
node_server -->|"promotes model"| node_publisher
node_server -->|"evaluates final model"| node_evaluation
node_operator -->|"runs pipeline"| node_label
node_operator -->|"starts training"| node_server
node_operator -->|"tests model"| node_evaluation
node_publisher -.->|"publishes versions"| node_modelapi

click node_honeypot "https://github.com/zhiyu-l/csc3104-honeypot-fl/tree/main/services/cowrie"
click node_label "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/cowrie_sessions.py"
click node_split "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/split_orgs.py"
click node_replay "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/replay_testset.py"
click node_processor "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/log-processor/process_replay.py"
click node_nightly "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/log-processor/nightly.py"
click node_featuredata "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/data.py"
click node_schema "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/schema.py"
click node_model "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/model.py"
click node_evaluation "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/evaluation.py"
click node_synthetic "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/synthetic.py"
click node_clientapp "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/client_app.py"
click node_clienttask "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/task.py"
click node_server "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/server_app.py"
click node_runner "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/runner.py"
click node_strategies "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/strategies.py"
click node_adaptive "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/adaptive.py"
click node_checkpoints "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/checkpoints.py"
click node_publisher "https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/publish.py"
click node_modelapi "https://github.com/zhiyu-l/csc3104-honeypot-fl/tree/main/services/model-api"

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_honeypot,node_label,node_split,node_replay toneBlue
class node_processor,node_nightly,node_featuredata toneAmber
class node_clientapp,node_clienttask,node_server,node_runner,node_strategies,node_adaptive,node_checkpoints,node_publisher toneMint
class node_schema,node_model,node_evaluation,node_synthetic toneRose
class node_modelapi,node_operator,node_attacker toneIndigo
```

## Components

### Data preparation

- [Cowrie honeypots](https://github.com/zhiyu-l/csc3104-honeypot-fl/tree/main/services/cowrie): `services/cowrie`
- [Session labeling](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/cowrie_sessions.py): `tools/cowrie_dataset/cowrie_sessions.py`
- [Org data splits](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/split_orgs.py): `tools/cowrie_dataset/split_orgs.py`
- [Replay test data](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/tools/cowrie_dataset/replay_testset.py): `tools/cowrie_dataset/replay_testset.py`

### Feature processing

- [Replay processing](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/log-processor/process_replay.py): `services/log-processor/process_replay.py`
- [Nightly processing](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/log-processor/nightly.py): `services/log-processor/nightly.py`
- [Feature batches](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/data.py): `services/client/src/fl_client/data.py`

### Federated learning

- [Client app](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/client_app.py): `services/client/src/fl_client/client_app.py`
- [Local training](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/client/src/fl_client/task.py): `services/client/src/fl_client/task.py`
- [Coordinator app](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/server_app.py): `services/coordinator/src/fl_coordinator/server_app.py`
- [Fault-tolerant rounds](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/runner.py): `services/coordinator/src/fl_coordinator/runner.py`
- [Aggregation strategies](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/strategies.py): `services/coordinator/src/fl_coordinator/strategies.py`
- [Adaptive aggregation](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/adaptive.py): `services/coordinator/src/fl_coordinator/adaptive.py`
- [Run checkpoints](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/checkpoints.py): `services/coordinator/src/fl_coordinator/checkpoints.py`
- [Model promotion](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/services/coordinator/src/fl_coordinator/publish.py): `services/coordinator/src/fl_coordinator/publish.py`

### Shared model layer

- [Feature schema](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/schema.py): `libs/fl-common/src/fl_common/schema.py`
- [Shared classifier](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/model.py): `libs/fl-common/src/fl_common/model.py`
- [Model evaluation](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/evaluation.py): `libs/fl-common/src/fl_common/evaluation.py`
- [Synthetic data](https://github.com/zhiyu-l/csc3104-honeypot-fl/blob/main/libs/fl-common/src/fl_common/synthetic.py): `libs/fl-common/src/fl_common/synthetic.py`

### Model serving

- [Model API](https://github.com/zhiyu-l/csc3104-honeypot-fl/tree/main/services/model-api): `services/model-api`

### Other components

- **Pipeline operator**
- **SSH attacker**

## Connections

- SSH attacker → Cowrie honeypots: sends traffic (evidence: `README.md`)
- Cowrie honeypots → Session labeling: produces logs (evidence: `README.md`)
- Session labeling → Org data splits: labels sessions (evidence: `README.md`)
- Session labeling → Replay processing: shares extractor (evidence: `services/log-processor/process_replay.py`)
- Org data splits → Local training: provides training data (evidence: `README.md`)
- Org data splits → Replay test data: provides held-out data (evidence: `README.md`)
- Replay test data → Replay processing: selects replay sessions (evidence: `tools/cowrie_dataset/replay_testset.py`)
- Replay processing → Feature schema: uses schema (evidence: `services/log-processor/process_replay.py`)
- Replay processing → Feature batches: writes feature batches (evidence: `README.md`)
- Nightly processing → Replay processing: invokes processing (evidence: `services/log-processor/nightly.py`)
- Nightly processing → Feature batches: publishes batches (evidence: `README.md`)
- Feature batches → Local training: loads data (evidence: `services/client/src/fl_client/task.py`)
- Client app → Local training: trains locally (evidence: `services/client/src/fl_client/client_app.py`)
- Client app → Shared classifier: loads weights (evidence: `services/client/src/fl_client/client_app.py`)
- Local training → Feature schema: validates features (evidence: `services/client/src/fl_client/task.py`)
- Local training → Synthetic data: uses fallback data (evidence: `services/client/src/fl_client/task.py`)
- Coordinator app → Shared classifier: initializes model (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Coordinator app → Aggregation strategies: selects strategy (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Coordinator app → Fault-tolerant rounds: runs rounds (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Fault-tolerant rounds → Aggregation strategies: aggregates updates (evidence: `services/coordinator/src/fl_coordinator/runner.py`)
- Aggregation strategies → Adaptive aggregation: uses adaptive logic (evidence: `services/coordinator/src/fl_coordinator/strategies.py`)
- Fault-tolerant rounds → Client app: dispatches rounds
- Coordinator app → Run checkpoints: saves run (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Coordinator app → Model promotion: promotes model (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Coordinator app → Model evaluation: evaluates final model (evidence: `services/coordinator/src/fl_coordinator/server_app.py`)
- Pipeline operator → Session labeling: runs pipeline (evidence: `README.md`)
- Pipeline operator → Coordinator app: starts training (evidence: `README.md`)
- Pipeline operator → Model evaluation: tests model (evidence: `README.md`)
- Model promotion → Model API: publishes versions
