cpssbench 0.1.0__tar.gz

cpssbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Md Hasan Shahriar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cpssbench-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: cpssbench
+Version: 0.1.0
+Summary: Cyber-Physical Systems Security Bench: datasets that download, preprocess, and load like MNIST.
+Author: Md Hasan Shahriar
+License: MIT
+Project-URL: Homepage, https://github.com/shahriar0651/cpssbench
+Keywords: dataset,cpss,cps,can,ids,vehicular,cybersecurity,pytorch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14
+Requires-Dist: joblib>=1.3
+Requires-Dist: torch>=2.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# cpssbench
+
+Cyber-Physical Systems Security Bench. It downloads raw traces, builds windowed tensors, and returns a PyTorch dataset with the same contract as MNIST: `(window, label)`.
+
+```python
+from cpssbench import SynCAN
+from torch.utils.data import DataLoader
+
+train = SynCAN(root="./data", split="train", download=True)
+test = SynCAN(root="./data", split="test", download=True)
+
+window, label = train[0]          # window: (1, time, signals), label: 0 benign / 1 attack
+loader = DataLoader(train, batch_size=64, shuffle=True)
+```
+
+Or load by name:
+
+```python
+import cpssbench
+
+dataset = cpssbench.load("road", root="./data", split="test", download=True)
+print(dataset.input_shape)   # (channels, window, signals)
+```
+
+## Install
+
+```bash
+pip install cpssbench
+```
+
+That works after the package is published on PyPI. Until then, install this repository directly:
+
+```bash
+pip install "git+https://github.com/shahriar0651/cpssbench.git"
+```
+
+From a local clone, for development:
+
+```bash
+pip install -e .
+```
+
+Then open `examples/train_like_mnist.ipynb` to plot a sample grid and train a small network.
+
+Python 3.10+. SynCAN also needs `git` on `PATH`. ROAD is fetched from Zenodo with the standard library, so `wget` is not required.
+
+## Datasets
+
+| Name | Status | What you get |
+| --- | --- | --- |
+| `syncan` | ready, auto-download | Synthetic CAN intrusion traces |
+| `road` | ready, auto-download | ROAD dynamometer CAN traces |
+| `misbehaviorx` | loader ready, manual files | V2X misbehavior (also accepted as `vasp`) |
+| `x-canids` | registered, not implemented | Raises a clear error until a loader is added |
+
+```bash
+python -m cpssbench list
+python -m cpssbench info syncan
+python -m cpssbench download syncan --root ./data --split train
+```
+
+Downloaded files land in `<root>/<name>/{ambient,attacks}` plus a fitted min/max scaler under `<root>/<name>/scaler`. Later calls reuse those files.
+
+## Overrides
+
+Windowing defaults live in the library so a new project does not need the old Hydra YAML. Override them per call:
+
+```python
+from cpssbench import ROAD
+
+dataset = ROAD(root="./data", split="train", download=True, window_size=50, step_size=5)
+```
+
+Pass `return_meta=True` if you also need the source file and row index: `(window, label, {"file", "idx"})`.
+
+## Layout
+
+Each sample is a min-max scaled window with a channel axis, so the same convolutional IDS can run on every dataset. Shape is always `(channels, window_size, num_signals)`. Label `0` is benign and `1` is attack (any attack flag inside the window).
+
+## Adding a dataset
+
+1. Add a `DatasetSpec` in `src/cpssbench/specs.py`.
+2. Add a downloader in `src/cpssbench/download.py` if the files can be fetched automatically.
+3. Register the class in `src/cpssbench/datasets.py` and `_CLASSES` in `__init__.py`.
+
+The IDS experiments that consume this package live in the sibling [RobIDS](https://github.com/shahriar0651/robids) repo.

cpssbench-0.1.0/README.md

@@ -0,0 +1,86 @@
+# cpssbench
+
+Cyber-Physical Systems Security Bench. It downloads raw traces, builds windowed tensors, and returns a PyTorch dataset with the same contract as MNIST: `(window, label)`.
+
+```python
+from cpssbench import SynCAN
+from torch.utils.data import DataLoader
+
+train = SynCAN(root="./data", split="train", download=True)
+test = SynCAN(root="./data", split="test", download=True)
+
+window, label = train[0]          # window: (1, time, signals), label: 0 benign / 1 attack
+loader = DataLoader(train, batch_size=64, shuffle=True)
+```
+
+Or load by name:
+
+```python
+import cpssbench
+
+dataset = cpssbench.load("road", root="./data", split="test", download=True)
+print(dataset.input_shape)   # (channels, window, signals)
+```
+
+## Install
+
+```bash
+pip install cpssbench
+```
+
+That works after the package is published on PyPI. Until then, install this repository directly:
+
+```bash
+pip install "git+https://github.com/shahriar0651/cpssbench.git"
+```
+
+From a local clone, for development:
+
+```bash
+pip install -e .
+```
+
+Then open `examples/train_like_mnist.ipynb` to plot a sample grid and train a small network.
+
+Python 3.10+. SynCAN also needs `git` on `PATH`. ROAD is fetched from Zenodo with the standard library, so `wget` is not required.
+
+## Datasets
+
+| Name | Status | What you get |
+| --- | --- | --- |
+| `syncan` | ready, auto-download | Synthetic CAN intrusion traces |
+| `road` | ready, auto-download | ROAD dynamometer CAN traces |
+| `misbehaviorx` | loader ready, manual files | V2X misbehavior (also accepted as `vasp`) |
+| `x-canids` | registered, not implemented | Raises a clear error until a loader is added |
+
+```bash
+python -m cpssbench list
+python -m cpssbench info syncan
+python -m cpssbench download syncan --root ./data --split train
+```
+
+Downloaded files land in `<root>/<name>/{ambient,attacks}` plus a fitted min/max scaler under `<root>/<name>/scaler`. Later calls reuse those files.
+
+## Overrides
+
+Windowing defaults live in the library so a new project does not need the old Hydra YAML. Override them per call:
+
+```python
+from cpssbench import ROAD
+
+dataset = ROAD(root="./data", split="train", download=True, window_size=50, step_size=5)
+```
+
+Pass `return_meta=True` if you also need the source file and row index: `(window, label, {"file", "idx"})`.
+
+## Layout
+
+Each sample is a min-max scaled window with a channel axis, so the same convolutional IDS can run on every dataset. Shape is always `(channels, window_size, num_signals)`. Label `0` is benign and `1` is attack (any attack flag inside the window).
+
+## Adding a dataset
+
+1. Add a `DatasetSpec` in `src/cpssbench/specs.py`.
+2. Add a downloader in `src/cpssbench/download.py` if the files can be fetched automatically.
+3. Register the class in `src/cpssbench/datasets.py` and `_CLASSES` in `__init__.py`.
+
+The IDS experiments that consume this package live in the sibling [RobIDS](https://github.com/shahriar0651/robids) repo.

cpssbench-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cpssbench"
+version = "0.1.0"
+description = "Cyber-Physical Systems Security Bench: datasets that download, preprocess, and load like MNIST."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Md Hasan Shahriar" }]
+keywords = ["dataset", "cpss", "cps", "can", "ids", "vehicular", "cybersecurity", "pytorch"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "numpy>=1.23",
+  "pandas>=2.0",
+  "pyarrow>=14",
+  "joblib>=1.3",
+  "torch>=2.0",
+  "tqdm>=4.60",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/shahriar0651/cpssbench"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cpssbench = ["py.typed"]

cpssbench-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cpssbench-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

cpssbench-0.1.0/src/cpssbench/__init__.py

@@ -0,0 +1,76 @@
+"""cpssbench: Cyber-Physical Systems Security Bench, loaded like MNIST.
+
+Example::
+
+    from cpssbench import SynCAN
+    from torch.utils.data import DataLoader
+
+    train = SynCAN(root="./data", split="train", download=True)
+    window, label = train[0]
+    loader = DataLoader(train, batch_size=64, shuffle=True)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .datasets import MisbehaviorX, ROAD, SynCAN, VehicularDataset
+from .specs import DatasetSpec, get_spec, list_specs
+
+__all__ = [
+    "SynCAN",
+    "ROAD",
+    "MisbehaviorX",
+    "VehicularDataset",
+    "load",
+    "list_datasets",
+    "describe",
+    "get_spec",
+]
+
+__version__ = "0.1.0"
+
+_CLASSES = {
+    "syncan": SynCAN,
+    "road": ROAD,
+    "misbehaviorx": MisbehaviorX,
+    "vasp": MisbehaviorX,
+    "veremi": MisbehaviorX,
+}
+
+
+def list_datasets(status: Optional[str] = None) -> list[dict]:
+    """Return name, status, family, and shape for every registered dataset."""
+    rows = []
+    for spec in list_specs(status):
+        rows.append(
+            {
+                "name": spec.name,
+                "status": spec.status,
+                "family": spec.family,
+                "input_shape": spec.input_shape if spec.features else None,
+                "downloadable": spec.downloadable,
+                "description": spec.description,
+            }
+        )
+    return rows
+
+
+def describe(name: str) -> DatasetSpec:
+    return get_spec(name)
+
+
+def load(name: str, **kwargs) -> VehicularDataset:
+    """Load a dataset by name.
+
+    ``kwargs`` are forwarded to the dataset class (``root``, ``split``,
+    ``download``, ``window_size``, ...).
+    """
+    key = name.strip().lower()
+    if key == "x-canids":
+        spec = get_spec(key)
+        raise NotImplementedError(f"{spec.name} is not implemented yet. {spec.notes}")
+    if key not in _CLASSES:
+        known = ", ".join(sorted(set(_CLASSES) | {"x-canids"}))
+        raise KeyError(f"Unknown dataset '{name}'. Known datasets: {known}")
+    return _CLASSES[key](**kwargs)

cpssbench-0.1.0/src/cpssbench/__main__.py

@@ -0,0 +1,38 @@
+"""Small command-line helper: ``python -m cpssbench list``."""
+
+from __future__ import annotations
+
+import argparse
+
+from . import describe, list_datasets, load
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download and inspect vehicular IDS datasets.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("list", help="List registered datasets")
+
+    info = sub.add_parser("info", help="Show one dataset specification")
+    info.add_argument("name")
+
+    fetch = sub.add_parser("download", help="Download and preprocess a split")
+    fetch.add_argument("name")
+    fetch.add_argument("--root", default="./data")
+    fetch.add_argument("--split", default="train", choices=["train", "test"])
+
+    args = parser.parse_args()
+    if args.command == "list":
+        for row in list_datasets():
+            shape = row["input_shape"] or "n/a"
+            print(f"{row['name']:16} {row['status']:8} {row['family']:4} {shape}")
+    elif args.command == "info":
+        spec = describe(args.name)
+        print(spec)
+    else:
+        dataset = load(args.name, root=args.root, split=args.split, download=True, verbose=True)
+        print(f"Loaded {len(dataset)} windows with shape {dataset.input_shape}")
+
+
+if __name__ == "__main__":
+    main()

cpssbench-0.1.0/src/cpssbench/datasets.py

@@ -0,0 +1,130 @@
+"""Public dataset classes.
+
+Usage matches torchvision:
+
+    from cpssbench import SynCAN
+
+    train = SynCAN(root="./data", split="train", download=True)
+    window, label = train[0]
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from torch.utils.data import Dataset
+
+from .download import dataset_root, ensure_downloaded, split_dir
+from .preprocess import prepare_can_split
+from .specs import DatasetSpec, get_spec
+from .v2x import V2XWindowDataset, prepare_v2x_split
+from .windows import WindowDataset
+
+
+class VehicularDataset(Dataset):
+    """Base class for datasets that download, preprocess, and yield windows."""
+
+    spec_name: str = ""
+
+    def __init__(
+        self,
+        root: str | Path = "./data",
+        split: str = "train",
+        download: bool = True,
+        transform=None,
+        target_transform=None,
+        window_size: Optional[int] = None,
+        step_size: Optional[int] = None,
+        sampling_period: Optional[int] = None,
+        return_meta: bool = False,
+        data_dir: Optional[str | Path] = None,
+        scaler_dir: Optional[str | Path] = None,
+        n_jobs: Optional[int] = None,
+        verbose: bool = False,
+    ) -> None:
+        spec = get_spec(self.spec_name).with_overrides(window_size, step_size, sampling_period)
+        if spec.status == "planned":
+            raise NotImplementedError(f"{spec.name} is not implemented yet. {spec.notes}")
+
+        self.spec = spec
+        self.root = Path(root).expanduser().resolve()
+        self.split = split
+        self.transform = transform
+        self.target_transform = target_transform
+        self.return_meta = return_meta
+
+        if data_dir is None and download:
+            ensure_downloaded(spec, self.root)
+
+        self.data_dir = Path(data_dir) if data_dir is not None else split_dir(self.root, spec.name, split)
+        if scaler_dir is not None:
+            self.scaler_path = Path(scaler_dir) / f"min_max_values_{spec.name}.csv"
+        else:
+            self.scaler_path = dataset_root(self.root, spec.name) / "scaler" / f"min_max_values_{spec.name}.csv"
+
+        fit_scaler = split.strip().lower() in {"train", "training", "ambient"}
+        if spec.family == "can":
+            prepare_can_split(spec, self.data_dir, self.scaler_path, fit_scaler, n_jobs=n_jobs)
+            self._base = WindowDataset(spec, self.data_dir, self.scaler_path, return_meta, verbose)
+        elif spec.family == "v2x":
+            prepare_v2x_split(spec, self.data_dir, self.scaler_path, fit_scaler)
+            self._base = V2XWindowDataset(spec, self.data_dir, self.scaler_path, return_meta, verbose)
+        else:
+            raise ValueError(f"Unsupported dataset family: {spec.family}")
+
+    def __len__(self) -> int:
+        return len(self._base)
+
+    def __getitem__(self, idx: int):
+        item = self._base[idx]
+        window, label = item[0], item[1]
+        if self.transform is not None:
+            window = self.transform(window)
+        if self.target_transform is not None:
+            label = self.target_transform(label)
+        if self.return_meta:
+            return window, label, item[2]
+        return window, label
+
+    @property
+    def classes(self) -> tuple[str, ...]:
+        return self.spec.classes
+
+    @property
+    def input_shape(self) -> tuple[int, int, int]:
+        return self.spec.input_shape
+
+    @property
+    def num_signals(self) -> int:
+        return self.spec.num_signals
+
+    @property
+    def window_size(self) -> int:
+        return self.spec.window_size
+
+    @property
+    def channels(self) -> int:
+        return self.spec.channels
+
+    @property
+    def features(self) -> tuple[str, ...]:
+        return self.spec.features
+
+
+class SynCAN(VehicularDataset):
+    """SynCAN intrusion dataset. ``split`` is ``'train'`` or ``'test'``."""
+
+    spec_name = "syncan"
+
+
+class ROAD(VehicularDataset):
+    """ROAD CAN intrusion dataset. ``split`` is ``'train'`` or ``'test'``."""
+
+    spec_name = "road"
+
+
+class MisbehaviorX(VehicularDataset):
+    """V2X misbehavior dataset. Requires a local copy; download is manual."""
+
+    spec_name = "misbehaviorx"

cpssbench-0.1.0/src/cpssbench/download.py

@@ -0,0 +1,160 @@
+"""Download raw vehicular datasets into a local root directory."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from .specs import DatasetSpec
+
+
+class DownloadError(RuntimeError):
+    """Raised when a dataset cannot be fetched or unpacked."""
+
+
+def _require_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        raise DownloadError(
+            f"'{name}' is required to download this dataset but was not found on PATH."
+        )
+
+
+def _download_file(url: str, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    print(f"Downloading {url}")
+    try:
+        urllib.request.urlretrieve(url, destination)
+    except Exception as exc:
+        raise DownloadError(f"Failed to download {url}: {exc}") from exc
+
+
+def split_dirname(split: str) -> str:
+    key = split.strip().lower()
+    mapping = {
+        "train": "ambient",
+        "training": "ambient",
+        "ambient": "ambient",
+        "test": "attacks",
+        "testing": "attacks",
+        "attack": "attacks",
+        "attacks": "attacks",
+    }
+    if key not in mapping:
+        raise ValueError(
+            f"Unsupported split '{split}'. Use 'train'/'ambient' or 'test'/'attacks'."
+        )
+    return mapping[key]
+
+
+def dataset_root(root: str | Path, name: str) -> Path:
+    return Path(root).expanduser().resolve() / name
+
+
+def split_dir(root: str | Path, name: str, split: str) -> Path:
+    return dataset_root(root, name) / split_dirname(split)
+
+
+def raw_csvs_present(path: Path) -> bool:
+    return path.is_dir() and any(path.glob("*.csv"))
+
+
+def download_syncan(destination: Path) -> None:
+    """Clone SynCAN and unpack ambient/attacks next to each other."""
+    _require_tool("git")
+    destination.mkdir(parents=True, exist_ok=True)
+    if raw_csvs_present(destination / "ambient") and raw_csvs_present(destination / "attacks"):
+        print(f"SynCAN already present at {destination}")
+        return
+
+    clone_dir = destination / "_raw"
+    if clone_dir.exists():
+        shutil.rmtree(clone_dir)
+    print(f"Cloning SynCAN into {clone_dir}")
+    subprocess.run(
+        ["git", "clone", "--depth", "1", "https://github.com/etas/SynCAN.git", str(clone_dir)],
+        check=True,
+    )
+
+    for pattern, folder in (("train_*.zip", "ambient"), ("test_*.zip", "attacks")):
+        zips = sorted(clone_dir.glob(pattern))
+        if not zips:
+            raise DownloadError(f"SynCAN clone is missing {pattern} archives.")
+        out = destination / folder
+        out.mkdir(parents=True, exist_ok=True)
+        for archive in zips:
+            print(f"Extracting {archive.name} -> {out}")
+            with zipfile.ZipFile(archive) as zf:
+                zf.extractall(out)
+
+    for normal in (destination / "attacks").glob("test_normal*"):
+        if normal.is_file():
+            normal.unlink()
+    shutil.rmtree(clone_dir, ignore_errors=True)
+    print(f"SynCAN downloaded to {destination}")
+
+
+def download_road(destination: Path) -> None:
+    """Download the ROAD signal-extraction release from Zenodo."""
+    destination.mkdir(parents=True, exist_ok=True)
+    if raw_csvs_present(destination / "ambient") and raw_csvs_present(destination / "attacks"):
+        print(f"ROAD already present at {destination}")
+        return
+
+    archive = destination / "road.zip"
+    _download_file("https://zenodo.org/records/10462796/files/road.zip", archive)
+    extract_root = destination / "_raw"
+    if extract_root.exists():
+        shutil.rmtree(extract_root)
+    extract_root.mkdir(parents=True, exist_ok=True)
+    print(f"Extracting {archive.name}")
+    with zipfile.ZipFile(archive) as zf:
+        zf.extractall(extract_root)
+
+    signal_dir = next(extract_root.rglob("signal_extractions"), None)
+    source = signal_dir if signal_dir is not None else extract_root
+    for folder in ("ambient", "attacks"):
+        matches = [path for path in source.rglob(folder) if path.is_dir()]
+        if not matches:
+            raise DownloadError(
+                f"ROAD archive does not contain an '{folder}' directory. "
+                f"Inspect {extract_root} and place the CSVs manually."
+            )
+        target = destination / folder
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.move(str(matches[0]), str(target))
+
+    # Original release includes non-ambient files inside ambient/.
+    for extra in (destination / "ambient").iterdir():
+        if extra.is_file() and not extra.name.startswith("ambient_"):
+            extra.unlink()
+
+    archive.unlink(missing_ok=True)
+    shutil.rmtree(extract_root, ignore_errors=True)
+    print(f"ROAD downloaded to {destination}")
+
+
+def ensure_downloaded(spec: DatasetSpec, root: str | Path) -> Path:
+    """Download ``spec`` under ``root/<name>`` and return that directory."""
+    destination = dataset_root(root, spec.name)
+    if spec.status == "planned":
+        raise DownloadError(
+            f"{spec.name} is registered but not implemented yet. {spec.notes}"
+        )
+    if not spec.downloadable:
+        if raw_csvs_present(destination / "ambient") or raw_csvs_present(destination / "attacks"):
+            return destination
+        raise DownloadError(
+            f"{spec.name} cannot be downloaded automatically. {spec.notes} "
+            f"Expected files under {destination}."
+        )
+    if spec.name == "syncan":
+        download_syncan(destination)
+    elif spec.name == "road":
+        download_road(destination)
+    else:
+        raise DownloadError(f"No downloader registered for {spec.name}.")
+    return destination