microNIDS — ML for network intrusion detection

A Network Intrusion Detection System reads traffic and emits a verdict — benign or malicious — per flow. Modern enterprise IDSes are hybrid: signature engines (Snort, Suricata) catch known patterns, ML classifiers catch statistical anomalies the signatures miss. The signatures are brittle but cheap. The ML is generalizable but attackable. This lab builds the ML half, attacks it three different ways, then layers defenses that buy back partial coverage.

Most ML-NIDS work in the literature targets one of three datasets — NSL-KDD (1999 data, 2009 revisions), CIC-IDS2017 (real PCAPs), or UNSW-NB15 (synthetic but well-distributed). All three describe network flows as a fixed vector of statistical features (byte counts, durations, packet counts, error rates) and train a classifier. microNIDS uses NSL-KDD for the walkthrough — its 41-feature schema is exhaustively documented and its dataset is small enough to retrain in seconds. Once you've seen the whole pipeline, the optional Going Further section swaps in CIC-IDS2017 — a larger, real-world captured-traffic dataset — to see which attacks still land.

Where to find it

• microNIDS source — nids/micro_nids.py. ~180 lines, gradient-boosted classifier + permutation-importance explainer. Stdlib + pandas + sklearn.
• Dataset — data/. KDDTrain+.txt / KDDTest+.txt are the canonical NSL-KDD splits (~125k + 22k flows); nslkdd_sample.csv is a 4,000-row balanced excerpt that ships with the lab so you can run end-to-end without a download.
• Attack scripts — attacks/01_feature_perturbation.py, 02_packet_padding.py, 03_timing_jitter.py. Each takes high-confidence-attack flows, perturbs them, reports the per-flow evasion rate.
• Defense scripts — secure/ensemble_nids.py (three-model vote), secure/baseline_anomaly.py (per-feature envelope).
• Instructor notes — solution/NOTES.md. Teaching plan, common student questions, grading rubric.

Authorized use — read this carefully

Everything in this lab runs against the NSL-KDD synthetic dataset and a model you trained yourself. Adversarial ML against ML-NIDS systems on production networks is unauthorized access; some jurisdictions (US under CFAA, UK under CMA, EU under NIS2) treat it as a felony regardless of intent. The skills here generalize directly to attacking production IDSes; the corresponding boundary is research disclosure to the vendor, never live testing. Lab 10's scope rules apply equally here.

1 · Anatomy of an ML-IDS ~10 min

An ML-NIDS has two pipelines, a training path and an inference path. Both share the same feature vocabulary; training writes the model, inference reads it.

The pipeline runs top-to-bottom at training time. At inference time the model sees one flow at a time and emits one verdict. The attack scripts in §4-§6 each tamper with one stage's input; the defense scripts in §7 each add a check at one stage's output.

2 · The microNIDS code · five steps ~15 min

Open nids/micro_nids.py. ↓ download lab-16-code.zip Each step below maps to one section of the file.

2.1 Step 1 · load

COLUMNS = [
    "duration", "protocol_type", "service", "flag", "src_bytes", "dst_bytes",
    # ... 35 more flow statistics ...
    "label", "difficulty",
]

def load(split: str = "train") -> pd.DataFrame:
    full = DATA / ("KDDTrain+.txt" if split == "train" else "KDDTest+.txt")
    if full.exists():
        df = pd.read_csv(full, header=None, names=COLUMNS).drop(columns=["difficulty"])
    else:
        df = pd.read_csv(DATA / "nslkdd_sample.csv")
    df["y"] = (df["label"] != "normal").astype(int)
    return df

The 41 features split into four conceptual groups: basic (duration, byte counts, protocol/service/flag), content-based (failed logins, file accesses, shell escalations — derived from payload inspection), traffic-window (counts of similar connections in the last 2 seconds), and host-window (counts of similar connections in the last 100 connections to the same host). Each group has different evasion characteristics — Attack 3 in §6 specifically targets the traffic-window features.

2.2 Step 2 · preprocess

CATEGORICAL = ["protocol_type", "service", "flag"]

def preprocess(df, encoders=None, scaler=None):
    if encoders is None:
        encoders = {}
        for col in CATEGORICAL:
            le = LabelEncoder().fit(df[col])
            df[col] = le.transform(df[col])
            encoders[col] = le
    # ... fold unknown categories onto the most common at predict time ...
    X = df[feature_cols].values.astype(np.float32)
    y = df["y"].values.astype(np.int8)
    if scaler is None:
        scaler = StandardScaler().fit(X)
    X = scaler.transform(X).astype(np.float32)
    return X, y, encoders, scaler, feature_cols

The encoders and scaler get persisted alongside the model. At inference time they must be applied identically — if you re-fit on the inference data you've introduced train-test skew and the model behavior changes silently. Every production MLOps stack has a horror story about a scaler that re-fit on production data.

2.3 Step 3 · train

def train(out=ARTIFACTS / "model.pkl"):
    train_df = load("train")
    X, y, encoders, scaler, feature_cols = preprocess(train_df)
    model = HistGradientBoostingClassifier(
        max_iter=200, max_depth=6, learning_rate=0.1, random_state=42,
    )
    model.fit(X, y)
    bundle = {"model": model, "encoders": encoders, "scaler": scaler,
              "feature_cols": feature_cols}
    pickle.dump(bundle, out.open("wb"))

A 200-tree gradient-boosted model trains on the full NSL-KDD train split in about 10 seconds on a laptop. Test ROC-AUC is around 0.96; raw accuracy is ~80%. Why the gap? NSL-KDD test contains attack categories that are absent from train — that's a deliberate feature of the dataset, designed to make accuracy harder so methodological papers can't cherry-pick. Production IDS authors face the same problem every day: today's training data doesn't include tomorrow's attacks.

2.4 Step 4 · predict

def predict(row_idx=0, split="test"):
    bundle = load_bundle()
    df = load(split)
    row = df.iloc[[row_idx]]
    X, y, *_ = preprocess(row, encoders=bundle["encoders"], scaler=bundle["scaler"])
    score = float(bundle["model"].predict_proba(X)[0, 1])
    pred = "attack" if score >= 0.5 else "benign"
    return {"score": score, "predicted": pred, "truth": "attack" if y[0] else "benign"}

One flow in, one verdict out. In production the verdict streams into a SIEM (Splunk, Sentinel, Chronicle) where rules + analyst review decide whether to page the on-call.

2.5 Step 5 · explain

def explain(top_k=10, n_repeats=5, sample=2000):
    bundle = load_bundle()
    test_df = load("test").sample(n=sample, random_state=42)
    X, y, *_ = preprocess(test_df, encoders=bundle["encoders"], scaler=bundle["scaler"])
    pi = permutation_importance(bundle["model"], X, y,
                                 n_repeats=n_repeats, random_state=42)
    return sorted(zip(bundle["feature_cols"], pi.importances_mean),
                   key=lambda kv: -kv[1])[:top_k]

Permutation importance shuffles each column in the test set and measures how much the model's accuracy drops. Bigger drop ⇒ the model depended on that feature more. The output is the attacker's target list.

3 · Run it ~15 min

On Rivanna, run this inside an Open OnDemand interactive session (Interactive Apps → Code Server, 4 cores is plenty, no GPU), not on the login node — training is CPU-heavy and the login node is single-threaded and rate-limited. Then open a terminal there.

The whole lab — build, break, and secure — runs from one command. run.sh creates a local venv, installs the three dependencies, and executes every step with headings:

$ cd Class/labs/lab-16
$ module load miniforge   # Rivanna only · gives you Python 3.13 (skip if you already have 3.9+)
$ chmod +x ./run.sh     # make the script executable (only needed once)
$ ./run.sh              # or: ./run.sh build | break | secure

Prefer to run each step yourself and watch it? Here is the same thing by hand — start with build:

$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r nids/requirements.txt
$ python nids/micro_nids.py train
saved → artifacts/model.pkl  (125973 training flows)
              precision    recall  f1-score   support
      benign       0.69      0.97      0.81      9711
      attack       0.97      0.68      0.80     12833
    accuracy                           0.80     22544
ROC-AUC: 0.9655
$ python nids/micro_nids.py predict --row 0
row 0 · score=1.000 · predicted=attack · truth=attack
$ python nids/micro_nids.py explain --top-k 8
top-8 features by permutation importance:
  src_bytes                    0.0899  ████████████████████████████████████████████████████████████
  dst_host_rerror_rate         0.0247  ████████████████
  dst_bytes                    0.0189  ████████████
  dst_host_srv_count           0.0167  ███████████
  duration                     0.0159  ██████████

~80% test accuracy at 0.96 ROC-AUC matches the canonical NSL-KDD literature numbers. The model is good. Now read the attacker's chart and pretend you've never seen it before — that's how Lab 16's break phase begins.

4 · Break · Attack 1 · feature-space perturbation ~20 min

MITRE ATLAS T0043 — Craft Adversarial Data. The attacker has white-box access to the model (or to its feature-importance output, which is structurally just as bad) and reshapes a real attack flow's statistical fingerprint to mimic the benign class.

# attacks/01_feature_perturbation.py — the perturbation
PERTURB_TARGETS = {
    "src_bytes":               (200,  2000),   # mid-range HTTP body
    "dst_bytes":               (500,  5000),   # mid-range response
    "duration":                (1,    30),
    "count":                   (1,    8),
    "diff_srv_rate":           (0.0,  0.1),
    "dst_host_srv_count":      (50,   200),
    "dst_host_same_srv_rate":  (0.8,  1.0),
}

def perturb(flow):
    for col, (lo, hi) in PERTURB_TARGETS.items():
        flow[col] = (lo + hi) / 2    # pin at the benign-class mid-point
    return flow

The widget uses a logistic regression surrogate trained on the same NSL-KDD split so it runs in the browser without 200 trees. The real model in micro_nids.py has the same shape of decision boundary; the per-feature thresholds differ slightly.

4.1 Run it

$ python attacks/01_feature_perturbation.py

Attack 1 · feature-space perturbation
  pool: 8067 high-confidence attack flows
--- flow 0 · category=neptune ---
  original score      : 1.000
  after perturbation  : 0.119   (Δ = -0.881)
  ✓ EVASION SUCCEEDED — flow now classified as benign
--- flow 1 · category=neptune ---
  ✓ EVASION SUCCEEDED — flow now classified as benign
--- flow 2 · category=saint ---
  ✗ still classified as attack
--- flow 3 · category=neptune ---
  ✓ EVASION SUCCEEDED — flow now classified as benign
--- flow 4 · category=neptune ---
  ✓ EVASION SUCCEEDED — flow now classified as benign

4/5 flows successfully disguised by feature perturbation.

5 · Break · Attack 2 · packet padding ~15 min

MITRE ATLAS T0043. A more constrained, more realistic perturbation: only the byte counts. The attacker pads payloads with junk (zeroes after a protocol terminator, repeated NOPs in a shellcode, harmless HTTP headers). The attack still completes; the byte counts now look like a normal file transfer.

TARGET_SRC_BYTES = 1024     # mid-size POST body
TARGET_DST_BYTES = 8192     # typical HTML response

def pad(flow):
    flow["src_bytes"] = max(flow["src_bytes"], TARGET_SRC_BYTES)
    flow["dst_bytes"] = max(flow["dst_bytes"], TARGET_DST_BYTES)
    return flow

5.1 Run it

$ python attacks/02_packet_padding.py

Attack 2 · packet padding
  pool: 8067 high-confidence attack flows
--- flow 0 · category=neptune ---
  src_bytes      0 →   1024    dst_bytes      0 →   8192
  ✓ EVASION SUCCEEDED — flow now classified as benign
--- flow 1 · category=neptune ---
  src_bytes      0 →   1024    dst_bytes      0 →   8192
  ✗ still classified as attack
--- flow 2 · category=saint ---
  src_bytes     20 →   1024    dst_bytes      0 →   8192
  ✗ still classified as attack
--- flow 3 · category=neptune ---
  src_bytes      0 →   1024    dst_bytes      0 →   8192
  ✗ still classified as attack
--- flow 4 · category=neptune ---
  src_bytes      0 →   1024    dst_bytes      0 →   8192
  ✓ EVASION SUCCEEDED — flow now classified as benign

2/5 flows evaded the classifier with only byte-count padding.

The success-rate-vs-stealth tradeoff is real: 80% evasion (Attack 1) requires changing many features and hoping the defender doesn't notice the joint distribution; 40% evasion (Attack 2) needs only the bytes and is invisible at the packet layer.

6 · Break · Attack 3 · slow-and-low timing ~15 min

The "slow rate" lineage — Slowloris, Slowdrip, drip-feed port scans. The attacker stretches the attack across minutes or hours instead of seconds, breaking the count-window features that the classifier relies on. Count windows in NSL-KDD assume the attacker is in a hurry; the attacker who isn't is invisible to them.

def jitter(flow):
    flow["duration"] = max(flow["duration"], 120)           # ≥ 2 minutes
    flow["count"] = 1                                         # no repetition
    flow["srv_count"] = 1
    flow["serror_rate"] = 0.0                                 # no retries
    flow["dst_host_count"] = min(flow["dst_host_count"], 5)
    flow["dst_host_srv_count"] = min(flow["dst_host_srv_count"], 5)
    flow["dst_host_serror_rate"] = 0.0
    return flow

6.1 Run it

$ python attacks/03_timing_jitter.py

Attack 3 · timing / count perturbation (slow-and-low)
--- flow 4 · category=neptune ---
  duration     0 →   120 s    count  120 →    1
  ✓ EVASION SUCCEEDED — flow now classified as benign

1/5 flows evaded the classifier via slow-and-low timing.

7 · Secure · ensemble + envelope ~30 min

Two defenses, deliberately limited. Both make a measurable dent in the attacks. Neither comes close to a complete fix. That's the lesson — production NIDS security is defense-in-depth, not a single trick.

7.1 Defense 1 · model-diversity ensemble

Three classifiers trained on the same data but from different model families — gradient-boosted trees, random forest, logistic regression. Vote (or average probabilities) at inference time. An adversarial perturbation tuned to fool one decision boundary is unlikely to land on the benign side of all three at once.

# secure/ensemble_nids.py — the train function
models = {
    "hgb": HistGradientBoostingClassifier(max_iter=200, max_depth=6, ...),
    "rf":  RandomForestClassifier(n_estimators=150, max_depth=10, ...),
    "lr":  LogisticRegression(max_iter=500, ...),
}
for mdl in models.values():
    mdl.fit(X, y)
# At inference: average the three probabilities.
probs = np.mean([m_.predict_proba(X)[:, 1] for m_ in models.values()], axis=0)

Coverage report

The ensemble shrinks padding evasion meaningfully (12 → 7) because the three model families have different sensitivities to src_bytes / dst_bytes. It doesn't help against feature perturbation (the attacker is moving features to ranges that look benign to all three models) and slightly worsens timing jitter (the LR component happens to over-trust the slow-and-low signal). The point of including the worsened number isn't to celebrate the defense — it's diversity helps some attacks, not all, and sometimes the diversity itself opens a new gap.

7.2 Defense 2 · per-feature distributional envelope

Fit median + IQR per feature on the benign training class. At inference, count how many features sit outside the ±3-IQR envelope. ≥ 4 features outside ⇒ flag.

# secure/baseline_anomaly.py — the envelope check
def anomaly_score(envelope, row):
    outliers = 0
    for col, (med, iqr) in envelope["stats"].items():
        z = abs(row[col] - med) / iqr
        if z >= envelope["z_threshold"]:
            outliers += 1
    return outliers

Coverage report

The envelope is nearly useless against perturbation attacks. The reason is in the attack design — every attack here moves features to plausibly benign values, not outlier values. The envelope is looking for "too far from the benign median"; the attacker is going to the benign median.

8 · Scaling up · production NIDS ~15 min

microNIDS is structurally complete — the five steps map one-to-one onto every production IDS. What's missing from microNIDS is the operational machinery production systems add around those five steps.

Going further · CIC-IDS2017

CIC-IDS2017 is the modern successor to NSL-KDD. Same shape (flow features → classifier) but built from real PCAPs captured in 2017 against a target network deliberately exposed to a curated attack list (DoS, brute force, infiltration, botnet, web attacks). 80+ features, 2.8M flows, more realistic feature distributions. Swapping CIC-IDS2017 in for NSL-KDD is a one-day exercise:

1. Download the labeled CSVs from CIC (8 files, ~500 MB total).
2. Replace load() in micro_nids.py with a CIC parser — the column names differ but the shape is identical.
3. Retrain. ROC-AUC should land around 0.99 on the easier attack classes.
4. Re-run the three attacks. Two will work, one will fail outright because CIC's feature engineering is more robust than NSL-KDD's.

The interesting research question — "which attacks generalize across IDS datasets?" — is the natural extension lab. See the Assignment for a smaller version.

Assignment · combine + defend ~3 hours

Three deliverables:

1. Combine Attacks 1 + 2 + 3 into a single composite attacker. Write attacks/04_composite.py. The composite should hit ≥ 95% evasion on the 20-flow pool, defeating both Defense 1 and Defense 2.
2. Add a third defense. One of: adversarial training (retrain with perturbed-attack examples), DPI feature additions (parse the original NSL-KDD content features more aggressively), per-category one-vs-all classifiers (each category votes separately). Run on the composite attacker; report the coverage.
3. writeup.md — one page. Three sections: (a) which features your composite touched and why; (b) what assumption your defense exploits; (c) the next attack class that defeats your defense, with one sentence of justification.

Rubric

FAQ

Why NSL-KDD instead of something modern?

For the walkthrough: small (~25 MB total), well-documented, every feature has a published interpretation. For learning the structural lessons — feature engineering, gradient-boosted classifiers, adversarial flow perturbation — the dataset's vintage doesn't matter. For production-quality results, the answer is CIC-IDS2017 (see §8); the lab provides a direct upgrade path.

How does this connect to Lab 17?

Lab 16 attacks an IDS in the feature space: the attacker controls the inputs the model reads (byte counts, durations) and reshapes them within network-valid bounds. Lab 17 attacks an image classifier in the pixel space: the attacker adds tiny, imperceptible noise to pixel values and watches the classifier flip. Same abstract attack — gradient-following perturbation of model inputs to flip the decision — but different domains, different constraints, different defenses.

Are XGBoost / LightGBM faster than sklearn's HistGradientBoosting?

Slightly. The runtime difference at 125k rows × 41 columns is negligible (under a second either way). XGBoost and LightGBM win at large scale (millions of rows) and on specialized GPU paths. For pedagogy and laptop reproducibility, sklearn's HistGradientBoostingClassifier is the right choice — the API is identical and no native-library install is needed.

Why doesn't the envelope defense work better?

Because the attacker is going to the benign distribution, not away from it. Distributional anomaly detection sees the magnitude of deviation; the perturbation has near-zero magnitude on the wrong axis. The envelope catches noisy attacks, not calibrated ones. This is the same reason why MLE-based outlier detection fails on careful adversarial examples in Lab 17.

Could you write a Snort signature that catches Attack 1?

For a specific perturbation, yes — the signature would look for "Neptune-shaped flow but with src_bytes > 200." For the general perturbation class, no — the attacker has too many degrees of freedom and the signature space is unbounded. This is the recurring lesson: signatures catch known attacks well, ML generalizes (badly) to novel ones, and the union of the two is what production NIDS actually deploy.