gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/domain/fingerprint.py

@@ -0,0 +1,201 @@
+"""Process fingerprints — a behavioral signature per process, from REAL kernel telemetry.
+
+A fingerprint is a small feature vector over five axes, each derived from data the Machine Lab
+already collects (no simulation, no LLM judgement):
+
+  cpu      — fraction of samples the proc wanted the CPU (RUNNING/RUNNABLE), from procdump
+  io_wait  — fraction of samples SLEEPING (blocked on IO / wait / pipe), from procdump
+  syscalls — syscall rate, from the syscall trace ring (per-pid TRACE entries)
+  faults   — page-fault rate, from the trap-taxonomy ring (per-pid pagefault traps)
+  forks    — fork() rate, from the syscall ring (num == SYS_fork)
+
+Two layers sit on top, both pure/deterministic and testable:
+
+  • classify(fp)          — a threshold rule mapping a fingerprint to a behavior CLASS. This is the
+                            baseline the "classify game" grades a student against (or that a student
+                            tunes as an assignment).
+  • confusion_matrix(...) — scores predicted-vs-true classes. GROUND_TRUTH is the oracle's knowledge
+                            of what each shipped program really is; it grades, it never classifies.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+SYS_FORK = 1            # xv6 syscall number for fork()
+TRAP_PAGEFAULT = 1      # trap-taxonomy kind index for a page fault
+
+# the fingerprint axes, in radar order
+FEATURE_AXES = ["cpu", "syscalls", "io_wait", "faults", "forks"]
+AXIS_LABEL = {"cpu": "CPU", "syscalls": "syscalls", "io_wait": "IO wait",
+              "faults": "faults", "forks": "forks"}
+
+# behavior classes a fingerprint can be sorted into
+CLASSES = ["cpu-bound", "io-bound", "memory", "fork-heavy", "mixed"]
+
+# the oracle's ground truth — what each launchable program ACTUALLY is. Used only to grade the
+# classify game; never shown to the classifier. (grind forks + does file/pipe work, so it can
+# honestly be confused with io-bound — that overlap is the lesson.)
+GROUND_TRUTH = {
+    "spin": "cpu-bound", "busy": "cpu-bound",
+    "alloc": "memory", "writer": "io-bound",
+    "forktest": "fork-heavy", "grind": "fork-heavy",
+}
+
+# saturation constants: rate at which each axis reaches ~0.5 (via x/(x+k)). Tuned so the shipped
+# programs land in distinct regions; documented so a student can reason about them.
+_K_SYS, _K_FLT, _K_FORK = 20.0, 5.0, 2.0
+
+# default classifier thresholds — a student assignment can tune these and watch the confusion move.
+DEFAULT_THRESHOLDS = {"fork": 0.4, "flt": 0.3, "io": 0.35, "sys": 0.4, "cpu": 0.5}
+
+
+@dataclass
+class ProcFeatures:
+    """Raw per-process tallies accumulated over a window. All fields come from real dumps."""
+    pid: int
+    name: str = ""
+    samples: int = 0          # procdump samples observed
+    run_samples: int = 0      # ...RUNNING or RUNNABLE (wanted the CPU)
+    sleep_samples: int = 0    # ...SLEEPING (blocked)
+    syscalls: int = 0         # syscall trace events attributed to this pid
+    forks: int = 0            # ...of which fork()
+    faults: int = 0           # page-fault traps
+    window: float = 1.0       # seconds the tallies span (for rates)
+
+
+def _sat(x: float, k: float) -> float:
+    """Saturating normalizer x/(x+k) -> 0..1: bounded and stable frame to frame."""
+    return x / (x + k) if x > 0 else 0.0
+
+
+def fingerprint(f: ProcFeatures) -> dict:
+    """A ProcFeatures -> the 0..1 feature vector (the fingerprint)."""
+    w = max(f.window, 1e-6)
+    s = max(f.samples, 1)
+    return {
+        "cpu": min(1.0, f.run_samples / s),
+        "io_wait": min(1.0, f.sleep_samples / s),
+        "syscalls": _sat(f.syscalls / w, _K_SYS),
+        "faults": _sat(f.faults / w, _K_FLT),
+        "forks": _sat(f.forks / w, _K_FORK),
+    }
+
+
+def classify(fp: dict, thresholds: dict | None = None) -> str:
+    """Map a fingerprint to a behavior class by a simple, inspectable rule. Order matters: the most
+    distinctive signal wins first. Thresholds are tunable (the assignment)."""
+    th = {**DEFAULT_THRESHOLDS, **(thresholds or {})}
+    if fp["forks"] >= th["fork"]:
+        return "fork-heavy"
+    if fp["faults"] >= th["flt"]:
+        return "memory"
+    if fp["io_wait"] >= th["io"] or (fp["syscalls"] >= th["sys"] and fp["cpu"] < th["cpu"]):
+        return "io-bound"
+    if fp["cpu"] >= th["cpu"]:
+        return "cpu-bound"
+    return "mixed"
+
+
+def similarity(a: dict, b: dict) -> float:
+    """Cosine similarity of two fingerprints (0..1) — 'who behaves like whom' for the board."""
+    dot = sum(a[k] * b[k] for k in FEATURE_AXES)
+    na = math.sqrt(sum(a[k] ** 2 for k in FEATURE_AXES))
+    nb = math.sqrt(sum(b[k] ** 2 for k in FEATURE_AXES))
+    return dot / (na * nb) if na > 0 and nb > 0 else 0.0
+
+
+def scatter_xy(fp: dict) -> tuple[float, float]:
+    """Project a fingerprint onto the behavior map: x = CPU-bound(1) <-> IO-bound(0),
+    y = compute(0) <-> heavy-kernel(1, syscalls+faults+forks). Both 0..1."""
+    x = max(0.0, min(1.0, 0.5 + 0.5 * (fp["cpu"] - fp["io_wait"])))
+    y = max(0.0, min(1.0, (fp["syscalls"] + fp["faults"] + fp["forks"]) / 3.0))
+    return x, y
+
+
+def true_class(name: str) -> str | None:
+    """The oracle's ground-truth class for a program name (None if unknown)."""
+    return GROUND_TRUTH.get((name or "").strip())
+
+
+def confusion_matrix(pairs, classes=None) -> dict:
+    """[(true_class, predicted_class), …] -> {(true, pred): count}. Off-diagonal = confusion."""
+    classes = classes or CLASSES
+    m = {(t, p): 0 for t in classes for p in classes}
+    for true, pred in pairs:
+        if (true, pred) in m:
+            m[(true, pred)] += 1
+    return m
+
+
+def accuracy(pairs) -> float:
+    """Fraction of (true, pred) pairs on the diagonal."""
+    pairs = list(pairs)
+    if not pairs:
+        return 0.0
+    return sum(1 for t, p in pairs if t == p) / len(pairs)
+
+
+class FingerprintAccumulator:
+    """Builds per-pid ProcFeatures from a stream of observations. Pure bookkeeping — the UI feeds it
+    procdump states each poll plus the NEW syscall/trap ring events since the last poll."""
+
+    def __init__(self) -> None:
+        self.feats: dict[int, ProcFeatures] = {}
+
+    def reset(self) -> None:
+        self.feats.clear()
+
+    def _get(self, pid: int, name: str = "") -> ProcFeatures:
+        f = self.feats.get(pid)
+        if f is None:
+            f = ProcFeatures(pid=pid, name=name)
+            self.feats[pid] = f
+        if name:
+            f.name = name
+        return f
+
+    def observe(self, procs, sc_events=(), trap_events=(), dt: float = 0.5) -> None:
+        """One poll: `procs` are the current [Proc]; `sc_events`/`trap_events` are the NEW ring
+        entries since the last poll (SyscallEvent / TrapEvent). `dt` advances every proc's window."""
+        for p in procs:
+            f = self._get(p.pid, p.name)
+            f.samples += 1
+            if p.state in ("running", "runnable"):
+                f.run_samples += 1
+            elif p.state == "sleeping":
+                f.sleep_samples += 1
+            f.window += dt
+        for e in sc_events:
+            f = self.feats.get(e.pid)
+            if f is not None:
+                f.syscalls += 1
+                if e.num == SYS_FORK:
+                    f.forks += 1
+        for e in trap_events:
+            f = self.feats.get(e.pid)
+            if f is not None and e.kind == TRAP_PAGEFAULT:
+                f.faults += 1
+
+    def fingerprints(self, min_samples: int = 3) -> dict:
+        """{pid: fingerprint} for procs with enough samples to be meaningful (else 'settling')."""
+        return {pid: fingerprint(f) for pid, f in self.feats.items() if f.samples >= min_samples}
+
+
+def demo_features() -> list:
+    """Canned but realistic fingerprints for the shipped programs, so the panel + game work offline
+    (and drive the pure tests). Tallies chosen to match GROUND_TRUTH under the default classifier."""
+    return [
+        ProcFeatures(pid=4, name="spin", samples=20, run_samples=20, sleep_samples=0,
+                     syscalls=1, forks=0, faults=0, window=10),
+        ProcFeatures(pid=5, name="busy", samples=20, run_samples=20, sleep_samples=0,
+                     syscalls=2, forks=0, faults=0, window=10),
+        ProcFeatures(pid=6, name="alloc", samples=20, run_samples=14, sleep_samples=6,
+                     syscalls=50, forks=0, faults=48, window=10),
+        ProcFeatures(pid=7, name="writer", samples=20, run_samples=6, sleep_samples=14,
+                     syscalls=200, forks=0, faults=0, window=10),
+        ProcFeatures(pid=8, name="grind", samples=20, run_samples=10, sleep_samples=10,
+                     syscalls=180, forks=40, faults=5, window=10),
+        ProcFeatures(pid=9, name="forktest", samples=20, run_samples=12, sleep_samples=8,
+                     syscalls=60, forks=50, faults=0, window=10),
+    ]

gini/domain/firewall.py

@@ -0,0 +1,34 @@
+"""Firewall rules -> gRouter ACL deploy commands (the firewall face of the Router Lab).
+
+A GINI Firewall is a gRouter with an ACL data-plane module. A rule `deny <cidr>` (or a bare
+CIDR) becomes `gpipe add acl <cidr>` on the real router; deploying clears the pipeline then
+adds each rule in order — the same live-deploy path as the Service Function Chain, just a
+firewall-shaped front-end. Pure/text-only, so it's unit-tested without Docker.
+"""
+from __future__ import annotations
+
+import re
+
+_CIDR = re.compile(r"^\d{1,3}(?:\.\d{1,3}){3}(?:/\d{1,2})?$")
+
+
+def parse_rules(text: str) -> list[tuple[str, str]]:
+    """[(action, target)] from a rules block — one `deny <cidr>` (or bare CIDR) per line.
+    Blank lines and `#` comments are ignored; unrecognised lines are skipped."""
+    out: list[tuple[str, str]] = []
+    for ln in (text or "").splitlines():
+        s = ln.strip()
+        if not s or s.startswith("#"):
+            continue
+        toks = s.split()
+        if toks[0].lower() in ("deny", "drop", "block") and len(toks) >= 2 and _CIDR.match(toks[1]):
+            out.append(("deny", toks[1]))
+        elif _CIDR.match(toks[0]):
+            out.append(("deny", toks[0]))
+    return out
+
+
+def deploy_commands(text: str) -> list[str]:
+    """The `gpipe` arg-lines that program this firewall's ACL into the running gRouter:
+    `clear`, then `add acl <cidr>` per deny rule, in order."""
+    return ["clear"] + [f"add acl {target}" for _action, target in parse_rules(text)]

gini/domain/flowlog.py

@@ -0,0 +1,61 @@
+"""Flow event log — accumulate the controller's flow-rule installs/expiries over time.
+
+The live flow table is only a snapshot: a reactive controller installs exact-match rules for
+learned conversations and they expire after an idle timeout, so at any instant you see only a
+few. To show the FULL picture of what the controller programmed, `FlowLog` diffs successive
+snapshots (the dashboard polls `openflow entry all` every ~2.5s): a rule present now but not
+before is an "installed" event; one present before but not now is an "expired" event. This
+captures every rule that lived at least one poll — no backend change needed.
+
+Rules are identified by their match+action (the flow's identity), since the numeric slot
+index gets reused. Pure/duck-typed (rows just need `match_summary()`/`action_summary()` and
+`.packets`), so it's unit-tested without Qt or Docker.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class FlowEvent:
+    kind: str            # "installed" | "expired"
+    match: str
+    action: str
+    packets: int | None  # at install: ~0; at expire: the final count the rule handled
+    when: str            # HH:MM:SS
+
+
+class FlowLog:
+    def __init__(self, cap: int = 300) -> None:
+        self._prev: dict[str, dict] = {}     # key -> {match, action, packets}
+        self.events: list[FlowEvent] = []    # oldest first
+        self.cap = cap
+
+    def update(self, rows, now: str | None = None) -> list[FlowEvent]:
+        """Fold a fresh snapshot in; return the events newly detected this poll."""
+        ts = now or time.strftime("%H:%M:%S")
+        cur: dict[str, dict] = {}
+        for f in rows or []:
+            match, action = f.match_summary(), f.action_summary()
+            cur[f"{match} ⇒ {action}"] = {"match": match, "action": action,
+                                          "packets": getattr(f, "packets", None)}
+        fresh: list[FlowEvent] = []
+        for key, v in cur.items():
+            if key not in self._prev:
+                fresh.append(FlowEvent("installed", v["match"], v["action"], v["packets"], ts))
+        for key, v in self._prev.items():
+            if key not in cur:                # gone this poll -> expired/removed
+                fresh.append(FlowEvent("expired", v["match"], v["action"], v["packets"], ts))
+        self._prev = cur
+        self.events.extend(fresh)
+        if len(self.events) > self.cap:
+            self.events = self.events[-self.cap:]
+        return fresh
+
+    def recent(self, n: int = 200) -> list[FlowEvent]:
+        """Most-recent events first (for display)."""
+        return list(reversed(self.events[-n:]))
+
+    def clear(self) -> None:
+        self._prev, self.events = {}, []

gini/domain/flowtable.py

@@ -0,0 +1,179 @@
+"""OpenFlow flow-table parsing — turn the gRouter's `openflow …` CLI dumps into rows the
+SDN dashboard can render.
+
+The OVS element is the C gRouter in `--openflow` mode; its CLI (reachable at runtime via
+`element_query(ovs, "openflow …")`) prints the live flow table:
+
+  • `openflow entry all`        -> match fields + actions per active entry
+  • `openflow stats entry all`  -> match + packet/byte counts + duration per active entry
+
+Both share the block format (delimited by `=====\nEntry N\n=====`, match fields one tab in,
+actions two tabs in). This module parses either, and `flows(entry_dump, stats_dump)` merges
+them by index into `FlowEntry` rows. Pure/text-only, so it's fully unit-tested without Docker.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_ENTRY_RE = re.compile(r"^Entry\s+(\d+)\s*$")
+_OFPP = {"OFPP_FLOOD": "flood", "OFPP_CONTROLLER": "controller", "OFPP_NORMAL": "normal",
+         "OFPP_ALL": "all", "OFPP_IN_PORT": "in_port", "OFPP_LOCAL": "local",
+         "OFPP_TABLE": "table", "OFPP_NONE": "none"}
+
+
+@dataclass
+class FlowEntry:
+    index: int
+    match: dict = field(default_factory=dict)     # e.g. {"Input port": "1", "IP protocol": "TCP"}
+    actions: list = field(default_factory=list)   # e.g. ["output:2", "flood"]
+    priority: int | None = None
+    packets: int | None = None
+    bytes: int | None = None
+    duration: int | None = None
+    idle_timeout: int | None = None
+    hard_timeout: int | None = None
+
+    def match_summary(self) -> str:
+        m = self.match
+        parts = []
+        if m.get("Input port"):
+            parts.append("in:" + m["Input port"])
+        src, dst = m.get("IP source address"), m.get("IP destination address")
+        smac, dmac = (m.get("Ethernet source MAC address"),
+                      m.get("Ethernet destination MAC address"))
+        if src or dst:
+            parts.append(f"{src or '*'}→{dst or '*'}")
+        elif smac or dmac:
+            parts.append(f"{smac or '*'}→{dmac or '*'}")
+        kind = m.get("IP protocol") or m.get("Ethernet frame type")
+        if kind:
+            parts.append(kind.lower())
+        dport = m.get("TCP destination port") or m.get("UDP destination port")
+        if dport:
+            parts.append("dport " + dport)
+        return "  ".join(parts) or "any (wildcard)"
+
+    def action_summary(self) -> str:
+        return ", ".join(self.actions) or "—"
+
+
+def _int(v):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _split_blocks(text: str):
+    """Yield (index, [lines]) per `Entry N` block, keeping raw lines (with tabs)."""
+    idx, buf = None, []
+    for raw in (text or "").splitlines():
+        line = raw.rstrip("\n")
+        if set(line.strip()) == {"="} and line.strip():          # a `=====` divider
+            continue
+        m = _ENTRY_RE.match(line.strip())
+        if m:
+            if idx is not None:
+                yield idx, buf
+            idx, buf = int(m.group(1)), []
+        elif idx is not None:
+            buf.append(line)
+    if idx is not None:
+        yield idx, buf
+
+
+def _port_name(v: str) -> str:
+    v = v.strip()
+    if v in _OFPP:
+        return _OFPP[v]
+    if v.startswith("OFPP_"):
+        return v[5:].lower()
+    return f"output:{v}"
+
+
+def parse(text: str) -> list[FlowEntry]:
+    """Parse one dump (`entry all` or `stats entry all`) into active FlowEntry rows."""
+    out: list[FlowEntry] = []
+    for index, lines in _split_blocks(text):
+        if any(l.strip() == "Entry inactive" for l in lines):
+            continue
+        e = FlowEntry(index=index)
+        section = None
+        for line in lines:
+            depth = len(line) - len(line.lstrip("\t"))
+            s = line.strip()
+            if not s:
+                continue
+            if depth == 0:
+                if s == "Match:":
+                    section = "match"; continue
+                if s == "Actions:":
+                    section = "actions"; continue
+                section = None                       # a top-level field ends the block
+                key, _, val = s.partition(":")
+                key, val = key.strip(), val.strip()
+                if key == "Priority":
+                    e.priority = _int(val)
+                elif key == "Packet count":
+                    e.packets = _int(val)
+                elif key == "Byte count":
+                    e.bytes = _int(val)
+                elif key == "Duration (seconds)":
+                    e.duration = _int(val)
+                elif key == "Last matched timeout (seconds)":
+                    e.idle_timeout = _int(val)
+                elif key == "Last modified timeout (seconds)":
+                    e.hard_timeout = _int(val)
+            elif depth == 1 and section == "match":
+                key, sep, val = s.partition(":")
+                if sep:
+                    e.match[key.strip()] = val.strip()
+            elif depth >= 2 and section == "actions":
+                key, sep, val = s.partition(":")
+                if sep and key.strip() == "Output port":
+                    e.actions.append(_port_name(val))
+        out.append(e)
+    return out
+
+
+def merge(entries: list, stats: list) -> list[FlowEntry]:
+    """Merge an `entry all` parse (match+actions) with a `stats entry all` parse
+    (counters), keyed by entry index. Missing fields are filled from whichever dump has them."""
+    by_idx: dict[int, FlowEntry] = {e.index: e for e in entries}
+    for s in stats:
+        e = by_idx.get(s.index)
+        if e is None:
+            by_idx[s.index] = s
+            continue
+        e.match = e.match or s.match
+        e.actions = e.actions or s.actions
+        for attr in ("priority", "packets", "bytes", "duration",
+                     "idle_timeout", "hard_timeout"):
+            if getattr(e, attr) is None and getattr(s, attr) is not None:
+                setattr(e, attr, getattr(s, attr))
+    return [by_idx[i] for i in sorted(by_idx)]
+
+
+def parse_table_stats(text: str) -> dict:
+    """Parse `openflow stats table` into the table-level counters that prove the switch is
+    being programmed: active flows, packets looked up, and packets that matched a flow."""
+    out: dict[str, int] = {}
+    keymap = {
+        "Number of active entries": "active",
+        "Number of packets looked up in tables": "lookups",
+        "Number of packets that hit tables": "matched",
+        "Maximum number of supported entries": "max",
+    }
+    for line in (text or "").splitlines():
+        k, sep, v = line.strip().partition(":")
+        if sep and k.strip() in keymap:
+            n = _int(v.strip())
+            if n is not None:
+                out[keymap[k.strip()]] = n
+    return out
+
+
+def flows(entry_dump: str, stats_dump: str = "") -> list[FlowEntry]:
+    """Convenience: parse both dumps and merge into the display rows."""
+    return merge(parse(entry_dump), parse(stats_dump) if stats_dump else [])