sentry-v2 0.1.0__py3-none-any.whl

sentry_v2/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sentry_v2/actions.py

@@ -0,0 +1,147 @@
+"""How each action kind is captured, applied and undone against systemd.
+
+The executor decides when; this module only knows what. Capture (`prepare`)
+is separate from `apply` so the previous values can be journalled in
+between.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import time
+from pathlib import Path
+from typing import Any
+
+from .cgroupfs import CgroupFS
+from .policy import ActionSpec, BackupReload, Freeze, Notify, Throttle
+from .state import ActionRecord
+from .systemd import SystemdError, SystemdManager, UnitNotFound
+from .units import Percent
+
+MEMORY_HIGH_FLOOR = 32 * 1024**2
+UNIT_INACTIVE = "org.freedesktop.systemd1.UnitInactive"
+
+
+class Refused(Exception):
+    """The action must not go ahead; the message is the record's error."""
+
+
+async def prepare(
+    spec: ActionSpec, unit: str, mgr: SystemdManager, fs: CgroupFS
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Read current state; return (previous values to restore, params to apply)."""
+    props = await mgr.get_properties(unit)
+    match spec:
+        case Throttle():
+            mh = spec.memory_high
+            if isinstance(mh, Percent):
+                mh = max(mh.of(fs.memory_current(props.cgroup)), MEMORY_HIGH_FLOOR)
+            previous: dict[str, Any] = {}
+            if mh is not None:
+                previous["memory_high"] = props.memory_high
+            if spec.cpu_weight is not None:
+                previous["cpu_weight"] = props.cpu_weight
+            return previous, {"memory_high": mh, "cpu_weight": spec.cpu_weight}
+        case Freeze():
+            if props.active_state != "active":
+                raise Refused("unit inactive")
+            if props.freezer_state != "running":
+                raise Refused(f"already {props.freezer_state}")
+            return {"freezer_state": props.freezer_state}, {"cgroup": props.cgroup}
+        case BackupReload():
+            files = [props.fragment_path, *props.drop_in_paths, *map(str, spec.paths)]
+            return {}, {"files": [f for f in files if f]}
+        case Notify():  # pragma: no cover - the executor never prepares a notify
+            return {}, {}
+
+
+def describe(spec: ActionSpec) -> dict[str, Any]:
+    """What a dry-run would write, without touching systemd (a Percent stays "90%")."""
+    if not isinstance(spec, Throttle):
+        return {}
+    mh = spec.memory_high
+    return {
+        "memory_high": f"{mh.value:g}%" if isinstance(mh, Percent) else mh,
+        "cpu_weight": spec.cpu_weight,
+    }
+
+
+def copy_mode_and_times(src: Path | str, dest: Path | str) -> None:
+    """Give `dest` the permission bits and times of `src`, but not its xattrs.
+
+    shutil.copystat (and copy2) also copies security.selinux. That would
+    label a backup as a unit file, or a restored unit file as sentry-v2
+    state, and the daemon's SELinux domain is not allowed to relabel.
+    """
+    st = os.stat(src)
+    os.chmod(dest, stat.S_IMODE(st.st_mode))
+    os.utime(dest, ns=(st.st_atime_ns, st.st_mtime_ns))
+
+
+def backup(unit: str, files: list[str], backups_dir: Path, now: float) -> str:
+    """Copy `files` under `backups_dir/<unit>/<ts>/files/<abs path>` with a sha256 manifest.
+
+    Returns the backup id `<unit>/<ts>`. Copies keep mode and mtime.
+    """
+    backup_id = f"{unit}/{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime(now))}"
+    bdir = backups_dir / backup_id
+    copies = [(src, Path("files") / Path(src).relative_to("/")) for src in files]
+    for src, rel in copies:
+        if not (bdir / rel).resolve().is_relative_to(bdir.resolve()):
+            raise ValueError(f"{src}: escapes the backup directory")
+    backups_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    bdir.parent.mkdir(mode=0o700, exist_ok=True)
+    bdir.mkdir(mode=0o700)
+    manifest = []
+    for src, rel in copies:
+        dest = bdir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, dest)
+        copy_mode_and_times(src, dest)
+        manifest.append(f"{hashlib.sha256(dest.read_bytes()).hexdigest()}  {rel}\n")
+    (bdir / "MANIFEST.sha256").write_text("".join(manifest))
+    return backup_id
+
+
+async def apply(spec: ActionSpec, unit: str, params: dict[str, Any], mgr: SystemdManager) -> None:
+    """The D-Bus call that makes the action take effect."""
+    match spec:
+        case Throttle():
+            await mgr.set_properties(unit, params["memory_high"], params["cpu_weight"])
+        case Freeze():
+            await mgr.freeze(unit)
+        case BackupReload():
+            await mgr.reload(unit)
+        case Notify():  # pragma: no cover - nothing to apply
+            pass
+
+
+CHANGED_SINCE = "changed since; left as is"
+
+
+async def rollback(rec: ActionRecord, mgr: SystemdManager) -> str | None:
+    """Undo `rec`. Returns a note when there was nothing (or nothing safe) to undo.
+
+    A throttle is restored only while every value it wrote is still in
+    place; if someone changed one since, their change wins and nothing is
+    written. Raises on failure.
+    """
+    try:
+        if rec.action == "throttle":
+            props = await mgr.get_properties(rec.target)
+            if any(getattr(props, k) != rec.params.get(k) for k in rec.previous):
+                return CHANGED_SINCE
+            prev = rec.previous
+            await mgr.set_properties(rec.target, prev.get("memory_high"), prev.get("cpu_weight"))
+        elif rec.action == "freeze":
+            await mgr.thaw(rec.target)
+    except UnitNotFound:
+        return "unit gone"
+    except SystemdError as e:
+        if e.name == UNIT_INACTIVE:  # systemd thaws a unit when it stops
+            return "unit inactive"
+        raise
+    return None

sentry_v2/bundle.py

@@ -0,0 +1,176 @@
+"""Diagnostic bundles: one JSON document per incident, scrubbed of secrets."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import math
+import os
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from sentry_v2.config_types import RedactionConfig
+from sentry_v2.events import Incident
+from sentry_v2.ids import uuid7
+
+SCHEMA_ID = "sentry-v2/bundle/1"
+REDACTED = "[REDACTED]"
+
+DEFAULT_PATTERNS = (
+    # before the bearer pattern, which would leave "Authorization: [REDACTED]"
+    # for this one to swallow the next word after
+    r"(?i)authorization:\s*\S+(?:\s+\S+)?",
+    r"(?i)bearer\s+[a-z0-9._~+/-]+=*",
+    r"://[^/\s:@]+:[^/\s@]+@",
+    r"AKIA[0-9A-Z]{16}",
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|\Z)",
+    r"(?i)(password|passwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)=\S+",
+)
+
+
+class Redactor:
+    def __init__(self, patterns: Sequence[str]) -> None:
+        self._res = [re.compile(p) for p in patterns]
+
+    @classmethod
+    def from_config(cls, cfg: RedactionConfig) -> Redactor:
+        return cls((*DEFAULT_PATTERNS, *cfg.patterns) if cfg.use_defaults else cfg.patterns)
+
+    def scrub(self, text: str) -> str:
+        for r in self._res:
+            text = r.sub(REDACTED, text)
+        return text
+
+    def scrub_tree(self, obj: Any) -> Any:
+        """Return a copy of a JSON-like tree with every string scrubbed."""
+        if isinstance(obj, bytes):
+            return self.scrub(obj.decode(errors="replace"))
+        if isinstance(obj, str):
+            return self.scrub(obj)
+        if isinstance(obj, Mapping):
+            return {k: self.scrub_tree(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [self.scrub_tree(v) for v in obj]
+        if isinstance(obj, float):
+            return obj if math.isfinite(obj) else None  # NaN/inf are not valid JSON
+        if obj is None or isinstance(obj, (bool, int)):
+            return obj
+        return self.scrub(str(obj))
+
+
+@dataclass(frozen=True)
+class HostInfo:
+    hostname: str
+    machine_id: str | None
+    kernel: str
+    os_release: str | None
+
+    @classmethod
+    def collect(cls, root: Path = Path("/")) -> HostInfo:
+        try:
+            machine_id: str | None = (root / "etc/machine-id").read_text().strip()
+        except (OSError, ValueError):
+            machine_id = None
+        os_release = None
+        try:
+            for line in (root / "etc/os-release").read_text().splitlines():
+                if line.startswith("PRETTY_NAME="):
+                    os_release = line.partition("=")[2].strip().strip("\"'")
+        except (OSError, ValueError):
+            pass
+        return cls(os.uname().nodename, machine_id, os.uname().release, os_release)
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "hostname": self.hostname,
+            "machine_id": self.machine_id,
+            "kernel": self.kernel,
+            "os_release": self.os_release,
+        }
+
+
+@dataclass(frozen=True)
+class BundleContext:
+    psi: dict[str, dict[str, Any]]
+    unit_props: dict[str, Any] | None
+    journal_tail: list[dict[str, Any]]
+
+
+def _now() -> str:
+    return dt.datetime.now(dt.UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def _action(rec: Mapping[str, Any], redactor: Redactor) -> dict[str, Any]:
+    out: dict[str, Any] = json.loads(json.dumps(rec, default=str))
+    if isinstance(out.get("error"), str):
+        out["error"] = redactor.scrub(out["error"])
+    return out
+
+
+def _severity(records: Sequence[Mapping[str, Any]], incident: Mapping[str, Any]) -> str:
+    if any(r.get("status") == "rollback_failed" for r in records):
+        return "critical"
+    enforced = any(
+        r.get("mode") == "enforce" and r.get("status") in ("applied", "rolled_back")
+        for r in records
+    )
+    strong = any(c["confidence"] >= 0.8 for c in incident["correlations"])
+    return "warning" if enforced or strong else "info"
+
+
+def build_bundle(
+    incident: Incident,
+    records: Sequence[Mapping[str, Any]],
+    context: BundleContext,
+    host: HostInfo,
+    redactor: Redactor,
+) -> dict[str, Any]:
+    inc = json.loads(json.dumps(incident.to_dict()))  # tuples become lists
+    # Explicit scrub paths: ids and contexts must not be mangled.
+    scrub = redactor.scrub
+    trigger: dict[str, Any] = inc["trigger"]
+    if isinstance(trigger.get("raw"), str):
+        trigger["raw"] = scrub(trigger["raw"])
+    for ev in inc["related"]:
+        if isinstance(ev.get("raw"), str):
+            ev["raw"] = scrub(ev["raw"])
+    corrs = [{**c, "avc": {**c["avc"], "raw": scrub(c["avc"]["raw"])}} for c in inc["correlations"]]
+    inc["correlations"] = corrs
+    first = records[0] if records else {}
+    return {
+        "schema": SCHEMA_ID,
+        "id": uuid7(),
+        "ts": _now(),
+        "severity": _severity(records, inc),
+        "host": host.to_dict(),
+        "incident": inc,
+        "context": {
+            "psi": context.psi,
+            "unit": redactor.scrub_tree(context.unit_props),
+            "journal": redactor.scrub_tree(context.journal_tail),
+        },
+        "correlations": corrs,
+        "decision": {
+            "policy": first.get("policy"),
+            "mode": first.get("mode"),
+            "actions": [_action(r, redactor) for r in records],
+        },
+    }
+
+
+def build_alert_bundle(kind: str, detail: Mapping[str, Any], host: HostInfo) -> dict[str, Any]:
+    record = detail.get("record")
+    return {
+        "schema": SCHEMA_ID,
+        "id": uuid7(),
+        "ts": _now(),
+        "severity": "critical",
+        "host": host.to_dict(),
+        "incident": {"kind": "alert", "target": detail.get("target"), "alert": kind},
+        "context": {"psi": {}, "unit": None, "journal": []},
+        "correlations": [],
+        "decision": {"policy": None, "mode": None, "actions": [record] if record else []},
+    }

sentry_v2/cgroupfs.py

@@ -0,0 +1,81 @@
+"""Thin, testable access to the cgroup v2 filesystem and /proc."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from .events import PressureLine
+from .policy import target_matches
+
+UNIT_SUFFIXES = (".service", ".scope", ".slice")
+
+
+def parse_pressure(text: str) -> dict[str, PressureLine]:
+    """Parse a *.pressure file into {"some": ..., "full": ...}."""
+    out: dict[str, PressureLine] = {}
+    for line in text.splitlines():
+        kind, *fields = line.split()
+        kv = dict(f.split("=", 1) for f in fields)
+        out[kind] = PressureLine(
+            float(kv["avg10"]), float(kv["avg60"]), float(kv["avg300"]), int(kv["total"])
+        )
+    return out
+
+
+class CgroupFS:
+    def __init__(self, root: Path = Path("/sys/fs/cgroup"), proc: Path = Path("/proc")) -> None:
+        self.root = root
+        self.proc = proc
+
+    def psi_available(self) -> bool:
+        return os.access(self.proc / "pressure" / "memory", os.R_OK)
+
+    def glob(self, patterns: Iterable[str]) -> list[str]:
+        """Cgroup directories (relative paths) matching any pattern."""
+        pats = tuple(patterns)
+        found: list[str] = []
+        # Known limit: walks the whole cgroup tree, fine up to a few thousand
+        # cgroups per resolve (upgrade path: prune by each pattern's literal prefix).
+        for dirpath, _dirs, _files in os.walk(self.root):
+            rel = Path(dirpath).relative_to(self.root).as_posix()
+            if rel != "." and any(target_matches(p, rel) for p in pats):
+                found.append(rel)
+        return sorted(found)
+
+    def read_pressure(self, rel: str, resource: str) -> dict[str, PressureLine]:
+        return parse_pressure((self.root / rel / f"{resource}.pressure").read_text())
+
+    def read_system_pressure(self, resource: str) -> dict[str, PressureLine]:
+        """System-wide pressure from /proc/pressure, for the root cgroup."""
+        return parse_pressure((self.proc / "pressure" / resource).read_text())
+
+    def memory_current(self, rel: str) -> int:
+        return int((self.root / rel / "memory.current").read_text())
+
+    def pid_cgroup(self, pid: int) -> str | None:
+        try:
+            text = (self.proc / str(pid) / "cgroup").read_text()
+        except OSError:
+            return None
+        for line in text.splitlines():
+            if line.startswith("0::"):
+                return line[3:].strip("/")
+        return None
+
+    def unit_of(self, rel: str) -> str | None:
+        last = rel.rsplit("/", 1)[-1]
+        return last if last.endswith(UNIT_SUFFIXES) else None
+
+    def open_trigger(
+        self, rel: str, resource: str, kind: str, stall_us: int, window_us: int
+    ) -> int:
+        """Register a PSI trigger; the returned fd raises EPOLLPRI when it fires."""
+        fd = os.open(self.root / rel / f"{resource}.pressure", os.O_RDWR | os.O_NONBLOCK)
+        try:
+            os.write(fd, f"{kind} {stall_us} {window_us}\0".encode())
+        except OSError:
+            os.close(fd)
+            raise
+        return fd