A framework for building and evaluating staged (cascade) network intrusion detection systems. You describe a design in one YAML file, or draw it in the dashboard: the stages, the model in each, and where each stage sends the flows it judges. IDSLab fits it, makes every choice on validation data, and then shows on untouched test data whether the design beats its own first stage alone, and what each stage adds.
IDSLab needs Python 3.10 or newer and installs from PyPI.
python3 -m venv .venv && .venv/bin/pip install idslab
.venv/bin/idslab example demo # synthetic data and three reference designs
.venv/bin/idslab run demo/r1_router_gate.yaml --out demo/runs # fit, choose on VAL, report on TEST
.venv/bin/idslab dashboard --workspace demo --open # optional web UIOn Windows, in PowerShell (the programs are in .venv\Scripts):
py -3.12 -m venv .venv; .\.venv\Scripts\pip install idslab
.\.venv\Scripts\idslab example demo
.\.venv\Scripts\idslab run demo\r1_router_gate.yaml --out demo\runs
.\.venv\Scripts\idslab dashboard --workspace demo --open # keep the window open; Ctrl+C stops itThe report is demo/runs/r1-router-gate/report.html. Step-by-step guides for Windows, macOS and
GNU/Linux, optional model libraries and troubleshooting are in
INSTALL.md.
| Guide | What it covers |
|---|---|
| How it works | one run in figures: the design, the splits, the accuracy after each stage, the frontier gap and the flow map |
| Getting started | a first run on the synthetic data, reading the report, moving to your own data |
| Example designs | the three reference cascades with diagrams, a custom model adapter, an outside score job |
| Config reference | every key of a config file, with defaults |
| Protocol and controls | splits, greedy selection on VAL, the controls and what each reported number means |
| Models in stages | score contracts, pipelines and search, PyTorch, your own adapter, scores from models trained elsewhere |
| Outputs | the report pages and every file a run writes |
| Comparing designs and sweeps | two designs on the same flows, paired per seed; one base config with many variants |
| Command line | validate, run, report, export-splits, example, compare, sweep, dashboard |
| Dashboard | the local web UI: pages, jobs, security (source reference) |
| Architecture | what happens during a run, the modules, and where to extend |
| Known limitations | what the numbers do and do not show |
| Design notes | the reasoning behind each protocol rule |
| Install guide | platform setup, extras, tests and checks |
| Changelog | what changed in each version |
| Project site | the project's overview page |
Every release and its changes are in the changelog and on the Releases page. Releases from 0.3.0 on are archived on Zenodo under the concept DOI above. From 0.3.1 on, a release that does not change the evaluation keeps finished runs; upgrades to 0.2.0 and 0.3.0 ran them again.
v0.3.0: the dashboard redesigned around experiments, with a guided setup, a results page that reads the cascade against its first stage, and job progress.v0.2.0: visual pipeline builder, cost objectives and stage cost, plugins,idslab compareandidslab sweep.v0.1.0: first public release.
Cite the version you used. The concept DOI 10.5281/zenodo.23435536 always resolves to the latest version, and lists each version's own DOI and citation. CITATION.cff holds the same details, and GitHub shows them under "Cite this repository".
AGPL-3.0-or-later. See LICENSE.