FlowSentinel v0.1.0

FlowSentinel v0.1.0

Release date: 2026-08-08

v0.1.0 is the first source-data-free, reproducible portfolio release of the PCAP-to-risk-score workflow.

Included

• Cross-platform Python conversion CLIs for one PCAP or an entire directory tree.
• Checkpointed conversion that resumes an interrupted capture from the last durable frame.
• Flow-disjoint train/validation/test construction using source_capture + tcp.stream.
• Parameterised Logistic Regression, HistGradientBoosting, MLP, ResNet1D, and benign-only Isolation Forest training scripts.
• Safe local CSV scoring, evaluation, benchmark aggregation, tests, lint configuration, and GitHub Actions CI.
• Fixed resource-aware benchmark configuration, data/score contracts, data card, CIC attribution, MIT license, and CFF citation metadata.
• A source-data-free benchmark preview and a frozen metric record.

Not included

This release deliberately excludes PCAPs, CSVs, model weights, predictions, reports, checkpoints, and private/production scoring code. Those files are ignored by Git because they can be large, sensitive, or non-redistributable.

Reproduce the primary result

1. Download CICIoT2023 under the source's current terms and ensure tshark is on PATH.

2. Follow README setup.

3. Convert and split the PCAP tree:

   python scripts/convert_pcap_tree.py /data/CICIoT2023 --output-root data/interim/ciciot2023
   python scripts/build_flow_splits.py data/interim/ciciot2023 --output-root data/processed/flow_split

4. Build the fixed sample and run HGB:

   python scripts/build_hgb_sample.py --split-dir data/processed/flow_split \
     --output-dir data/processed/hgb_sample --train-per-class 100000 \
     --evaluation-rows 50000 --batch-rows 25000
   python scripts/train_supervised.py --split-dir data/processed/hgb_sample \
     --model hist_gradient_boosting --run-dir artifacts/hist_gradient_boosting

5. Aggregate local metadata or create the safe test evaluation:

   python scripts/build_benchmark_report.py --artifacts-dir artifacts --output-dir reports/benchmark
   python scripts/evaluate_predictions.py --model-dir artifacts/hist_gradient_boosting \
     --input-csv data/processed/hgb_sample/test.csv --output-dir reports/hgb_evaluation

The primary result is within-capture, flow-disjoint validation, not an unseen-capture benchmark. Read the data card and metric record before using results.

Verification on the release commit

python -m ruff check src scripts tests
python -m pytest -q

Release verification completed: 12 tests passed and Ruff reported no findings.

Citation and attribution

Use CITATION.cff to cite this repository. Cite CICIoT2023 when using its data or derived results; source and paper links are in data provenance.