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.