os_floor_registry.py
http-3.0/os_floor_registry.py · 241 line(s) · py
"""os_floor_registry.py -- SLeeLa install-time "tidiest fit" OS-floor discovery.
When a SLeeLa executable installs on a host, it wants the *tidiest fit*: it
looks at the operating-system "floor" it landed on (OS + filesystem), confers
with any capability responder present (TAC3 or another, via the bonding collar),
and records what it found. Over time SLeeLa keeps a growing **registry of OS
floors / filesystems** it has seen, with rollup statistics, and can *advance*
new or updated discoveries to a known GitHub endpoint (see os_floor_report.py).
DESIGN STANCE (matches the bonding collar):
- Observe, don't misrepresent. A floor's bonded tier is exactly what the
collar attested -- never guessed.
- Fail closed / no leakage. Detection makes no privileged calls and records
only non-identifying descriptors (OS name, filesystem hint, bonded tier,
a derived fingerprint). No secrets, no user PII, no host-proprietary
internals (the collar already guarantees the last point).
- Portable. Uses only the standard library so it runs on any host SLeeLa
reaches, including a new/unknown OS.
"""
from __future__ import annotations
import hashlib
import json
import os
import platform
import time
from dataclasses import dataclass, field, asdict
from typing import Dict, List, Optional
from bonding_collar import (
BondingCollar, CollarOffer, probe_env_responder,
CAP_ALL, tier_name, MAC_KEY_BYTES,
)
REGISTRY_VERSION = 1
def _now_iso() -> str:
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
# --------------------------------------------------------------------------
# A single observed OS floor
# --------------------------------------------------------------------------
@dataclass
class OsFloor:
"""One OS/filesystem floor SLeeLa has landed on, and the advantage it confers."""
floor_id: str # stable fingerprint (dedupe key)
os_name: str # e.g. "Linux", "Darwin", "Windows", or "Unknown"
os_release: str # kernel/OS release string (non-identifying)
filesystem: str # detected/declared fs hint, or "unknown"
bonded_tier: int # bonding-collar tier (0 = NONE / unknown)
bonded_tier_name: str
responder: str # "tac3", "generic", or "none"
first_seen: str = ""
last_seen: str = ""
seen_count: int = 0
notes: str = ""
def to_dict(self) -> dict:
return asdict(self)
def _fingerprint(os_name: str, os_release: str, filesystem: str, responder: str) -> str:
"""Stable, non-identifying dedupe key for a floor (12 hex chars)."""
h = hashlib.sha256(f"{os_name}|{os_release}|{filesystem}|{responder}".encode("utf-8"))
return "floor-" + h.hexdigest()[:12]
def detect_filesystem_hint() -> str:
"""A conservative, non-privileged guess at the host filesystem 'floor'.
Reads only what the platform readily exposes; never mounts, never calls a
privileged tool. Returns "unknown" when nothing safe is available.
"""
# A host (or a responder like TAC3) may declare the floor explicitly.
declared = os.environ.get("SLEELA_FS_FLOOR")
if declared:
return declared.strip()[:64]
sysname = platform.system()
if sysname == "Linux":
# /proc/mounts is world-readable and non-privileged where present.
try:
root_fs = None
with open("/proc/mounts", "r", encoding="utf-8", errors="replace") as fh:
for line in fh:
parts = line.split()
if len(parts) >= 3 and parts[1] == "/":
root_fs = parts[2]
break
if root_fs:
return root_fs
except OSError:
pass
elif sysname == "Darwin":
return "apfs?" # best-effort hint without privileged calls
elif sysname == "Windows":
return "ntfs?"
return "unknown"
def confer_with_host(key: bytes, *, env: Optional[dict] = None) -> tuple:
"""Confer via the bonding collar. Returns (bonded_tier, tier_name, responder).
responder is "tac3" when the host declares SLEELA_OS_RESPONDER=tac3 alongside
a valid attestation, "generic" for any other attested responder, else "none".
"""
e = env if env is not None else os.environ
collar = BondingCollar(local_caps=CAP_ALL, key=key)
offer = probe_env_responder(key, env=e)
result = collar.confer(offer)
if not result.bonded:
return (result.tier, result.tier_name, "none")
responder = (e.get("SLEELA_OS_RESPONDER") or "generic").strip().lower()[:32]
if responder not in ("tac3", "generic"):
responder = "generic"
return (result.tier, result.tier_name, responder)
def observe_current_floor(key: bytes, *, env: Optional[dict] = None) -> OsFloor:
"""Detect the current OS floor and confer for its bonded advantage tier."""
e = env if env is not None else os.environ
os_name = platform.system() or "Unknown"
os_release = (platform.release() or "")[:96]
fs_hint = detect_filesystem_hint()
tier, tname, responder = confer_with_host(key, env=e)
fid = _fingerprint(os_name, os_release, fs_hint, responder)
now = _now_iso()
return OsFloor(
floor_id=fid, os_name=os_name, os_release=os_release, filesystem=fs_hint,
bonded_tier=tier, bonded_tier_name=tname, responder=responder,
first_seen=now, last_seen=now, seen_count=1,
)
# --------------------------------------------------------------------------
# The registry (deduplicated, persistent)
# --------------------------------------------------------------------------
class OsFloorRegistry:
"""A growing, deduplicated list of OS floors/filesystems SLeeLa has seen."""
def __init__(self, path: Optional[str] = None) -> None:
self.path = path
self._floors: Dict[str, OsFloor] = {}
if path and os.path.exists(path):
self.load(path)
# ---- persistence ----
def load(self, path: Optional[str] = None) -> None:
p = path or self.path
with open(p, "r", encoding="utf-8") as fh:
doc = json.load(fh)
self._floors = {}
for entry in doc.get("floors", []):
f = OsFloor(**entry)
self._floors[f.floor_id] = f
def save(self, path: Optional[str] = None) -> None:
p = path or self.path
if not p:
raise ValueError("no path to save to")
tmp = p + ".tmp"
with open(tmp, "w", encoding="utf-8") as fh:
fh.write(self.to_json())
os.replace(tmp, p)
# ---- mutation ----
def record(self, floor: OsFloor) -> tuple:
"""Add or update a floor. Returns (floor, is_new).
Dedupe key is floor_id. On re-observation we bump seen_count/last_seen
and upgrade the bonded tier if the host now attests to a higher one.
"""
existing = self._floors.get(floor.floor_id)
if existing is None:
self._floors[floor.floor_id] = floor
return (floor, True)
existing.seen_count += 1
existing.last_seen = floor.last_seen
if floor.bonded_tier > existing.bonded_tier:
existing.bonded_tier = floor.bonded_tier
existing.bonded_tier_name = floor.bonded_tier_name
existing.responder = floor.responder
return (existing, False)
# ---- access ----
def floors(self) -> List[OsFloor]:
return sorted(self._floors.values(), key=lambda f: (-f.bonded_tier, f.floor_id))
def get(self, floor_id: str) -> Optional[OsFloor]:
return self._floors.get(floor_id)
def stats(self) -> dict:
"""Rollup statistics over the registry (non-identifying)."""
floors = list(self._floors.values())
by_tier: Dict[str, int] = {}
by_os: Dict[str, int] = {}
by_fs: Dict[str, int] = {}
by_responder: Dict[str, int] = {}
total_observations = 0
bonded = 0
for f in floors:
by_tier[f.bonded_tier_name] = by_tier.get(f.bonded_tier_name, 0) + 1
by_os[f.os_name] = by_os.get(f.os_name, 0) + 1
by_fs[f.filesystem] = by_fs.get(f.filesystem, 0) + 1
by_responder[f.responder] = by_responder.get(f.responder, 0) + 1
total_observations += f.seen_count
if f.bonded_tier > 0:
bonded += 1
return {
"distinct_floors": len(floors),
"total_observations": total_observations,
"bonded_floors": bonded,
"unbonded_floors": len(floors) - bonded,
"by_tier": by_tier,
"by_os": by_os,
"by_filesystem": by_fs,
"by_responder": by_responder,
}
def to_json(self, *, indent: int = 2) -> str:
doc = {
"registry_version": REGISTRY_VERSION,
"generated": _now_iso(),
"floor_count": len(self._floors),
"stats": self.stats(),
"floors": [f.to_dict() for f in self.floors()],
}
return json.dumps(doc, indent=indent)
if __name__ == "__main__":
# No-network self-demo: observe this host's floor and print it.
key = b"\x3c" * MAC_KEY_BYTES
reg = OsFloorRegistry()
floor = observe_current_floor(key)
f, is_new = reg.record(floor)
print(f"observed floor: {f.os_name} / {f.filesystem} -> tier={f.bonded_tier_name} "
f"responder={f.responder} (new={is_new})")
print(reg.to_json())