chore: checkpoint PROTEAN research planning and architecture

configs/datasets/datasets.yaml

@@ -0,0 +1,67 @@
+# Centralized dataset configuration for perdalam-protean.
+#
+# RAW DATA CONTRACT
+#   The raw datasets live OUTSIDE this repository and are read-only source data.
+#   They must never be moved, renamed, overwritten, or copied wholesale into the repo.
+#
+# PATH RESOLUTION PRECEDENCE (implemented in src/protean_research/utils/config.py)
+#   1. per-dataset environment variable listed in `env_override`
+#   2. `raw_path` below (`~` is expanded)
+#   3. values are resolved at load time; nothing is hardcoded in training logic
+#
+# GENERATED DATA
+#   All preprocessed caches, partitions, manifests, checkpoints and analysis
+#   outputs must be written under `generated_root` (default: artifacts/), never
+#   back into the raw dataset directory.
+
+generated_root: artifacts
+
+datasets:
+  xiiotid:
+    name: X-IIoTID
+    raw_path: ~/datasets/X-IIoTID/X-IIoTID-dataset.csv
+    env_override: PROTEAN_XIIOTID_RAW_PATH
+    # Paper uses the 10 "general" attack classes and removes Crypto-ransomware.
+    label_column: class2
+    label_column_aliases:
+      fine_grained: class1        # 19 specific attacks
+      binary: class3              # Normal / Attack
+    benign_label: Normal
+    drop_labels:
+      - crypto-ransomware
+    # '-' is the dataset's documented missing placeholder, not an empty string.
+    missing_tokens: ["-", "?"]
+    # Columns that are identifiers / timestamps / network endpoints and must NOT
+    # be used as model features without an explicit, documented decision.
+    non_feature_columns:
+      - Date
+      - Timestamp
+      - Scr_IP
+      - Scr_port
+      - Des_IP
+      - Des_port
+    notes: >
+      Row-level missing placeholders ('-') and a small number of malformed tokens
+      (e.g. '?', 'aza') exist. Exact duplicate rows are present. See
+      docs/research/DATASET_INSPECTION.md.
+
+  5gnidd:
+    name: 5G-NIDD
+    raw_path: ~/datasets/5G-NIDD/5G-NIDD.csv
+    env_override: PROTEAN_5GNIDD_RAW_PATH
+    # Multi-class attack label (9 values incl. Benign): the class used by PROTEAN.
+    label_column: Attack Type
+    label_column_aliases:
+      binary: Label              # Malicious / Benign
+      tool: Attack Tool
+    benign_label: Benign
+    drop_labels: []
+    missing_tokens: [""]
+    # First column is an unnamed row index. Seq / Offset are flow-ordering fields.
+    non_feature_columns:
+      - ""
+      - Seq
+      - Offset
+    notes: >
+      Several columns are missing for large row fractions (e.g. dTos, DstWin,
+      sVid, dVid). See docs/research/DATASET_INSPECTION.md.

configs/experiments/experiment_protocol.yaml

@@ -0,0 +1,60 @@
+# Frozen experiment protocol for the beta-weighted prototype aggregation study.
+# Values below are the required research settings. Seed set is provisional until
+# the verified baseline convention is reproduced (see docs/baseline/).
+
+datasets:
+  - xiiotid
+  - 5gnidd
+
+non_iid:
+  partition: dirichlet
+  alphas: [0.75, 0.50, 0.25]        # required by the research specification
+  num_clients: 10                    # matches PROTEAN paper cross-silo setting
+
+aggregation:
+  # beta candidates under test (one beta is applied to all classes and clients)
+  betas: [0.00, 0.25, 0.50, 0.75, 1.00]
+  # Modes:
+  #   original_protean : verified baseline semantics (NOT YET VERIFIED)
+  #   support_weighted : w_ij = N_ij ** beta, normalized over S_j  (proposed)
+  #   equal_available  : equal weights over S_j (methodological control,
+  #                      introduced only if the baseline participant rule differs)
+  primary_mode: support_weighted
+  baseline_mode: original_protean
+  control_mode: equal_available
+
+training:
+  rounds: 10
+  local_epochs: 3
+  # mu is stated in the paper; lambda is NOT stated in the paper text (UNRESOLVED).
+  mu: 0.1
+  lambda: null
+  batch_size: null                   # to be fixed after baseline reproduction
+  learning_rate: null                # to be fixed after baseline reproduction
+
+evaluation:
+  # The paper uses 80/20 train/test and has no validation split.
+  # This study ADDS a validation split used only for beta selection.
+  test_fraction: 0.20
+  validation_fraction: null          # finalize after baseline reproduction
+  selection_metric: rare_class_macro_f1
+  rare_class_rule: two_smallest_positive_attack_support
+  report_metrics:
+    - rare_class_macro_f1
+    - rare_class_recall
+    - overall_macro_f1
+    - accuracy
+    - per_client_metrics
+
+seeds:
+  # Paper averaged over three random seeds. Exact seed values are UNRESOLVED;
+  # they must be fixed before any beta comparison and shared across all modes.
+  provisional: [0, 1, 2]
+  status: provisional
+
+artifacts:
+  partition_manifest_dir: artifacts/partitions
+  processed_dir: artifacts/processed
+  checkpoint_dir: artifacts/checkpoints
+  analysis_dir: artifacts/analysis
+  results_dir: results

configs/models/protean_cnn.yaml

@@ -0,0 +1,44 @@
+# PROTEAN detection model as described in Chennoufi et al. (2025), Section 4.1.
+# The architecture is FROZEN to the baseline and is not part of this study's
+# contribution. The only proposed change is server-side prototype aggregation.
+
+model:
+  name: protean_cnn
+  framework: pytorch
+  input: flow_features          # tabular -> treated as 1D / single-channel input
+  embedding_dim: 128            # output of the dense layer == prototype dimension d
+  layers:
+    - type: conv1d
+      filters: 64
+      activation: relu
+      pool: max
+      dropout: 0.2
+    - type: conv1d
+      filters: 128
+      activation: relu
+      pool: max
+      dropout: 0.5
+    - type: flatten
+    - type: dense
+      units: 128
+    - type: classification_head
+      output: log_softmax
+  # Head concatenates/uses the dense embedding; EOF prototypes are extracted
+  # from the embedding part phi(x) (first 8 of 10 layers per the paper text).
+  prototype_source: embedding
+
+loss:
+  # Eq. (3): classification loss + lambda * prototype alignment + mu/2 * model alignment
+  terms:
+    - classification: cross_entropy
+    - prototype_alignment: l2_squared_distance_to_global_prototype
+      weight: lambda
+    - model_alignment: l2_squared_distance_to_previous_global_model
+      weight: mu
+  mu: 0.1
+  lambda: null                  # UNRESOLVED: not stated in the paper text
+
+inference:
+  rule: nearest_global_prototype_l2
+  trailing: "assign label of the global prototype with the smallest L2 distance
+              to the instance embedding (paper Section 3.2)"