fluidattacks-agent 0.1.2__py3-none-any.whl

fluidattacks_agent/settings.py

@@ -0,0 +1,119 @@
+"""Read what the workload was told about the probe, and believe little of it."""
+
+import os
+import stat
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final
+
+ENDPOINT: Final = "FLUIDATTACKS_AGENT_ENDPOINT"
+TOKEN: Final = "FLUIDATTACKS_AGENT_TOKEN"  # noqa: S105
+TOKEN_FILE: Final = "FLUIDATTACKS_AGENT_TOKEN_FILE"  # noqa: S105
+GROUP: Final = "FLUIDATTACKS_AGENT_GROUP"
+WORKLOAD: Final = "FLUIDATTACKS_AGENT_WORKLOAD"
+
+# evidence about what a workload runs is not something to hand to a listener
+# that cannot prove who it is
+SCHEME: Final = "https://"
+
+# a value the workload names, and a file it points at: both are bounded because
+# both are read into a process that may not spend the memory
+MAX_SETTING: Final = 4096
+
+
+@dataclass(frozen=True, slots=True)
+class Secret:
+    """A credential that no repr, no log and no traceback can spell."""
+
+    # out of the repr rather than out of reach: nothing stops the one place
+    # that spends it from reading it, and slots keep it out of a logger's walk
+    held: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class Delivery:
+    """Where reports go, and what the workload says it is."""
+
+    endpoint: str
+    token: Secret
+    group: str | None
+    workload: str | None
+
+
+def _readable(named: str) -> bool:
+    # all of these travel in a request, where a byte above ascii has to be
+    # encoded by whatever carries it and a control byte ends the line early
+    return bool(named) and len(named) <= MAX_SETTING and named.isascii() and named.isprintable()
+
+
+def _setting(held: Mapping[str, str], key: str) -> str | None:
+    value = held.get(key)
+    if value is None:
+        return None
+    named = value.strip()
+    return named if _readable(named) else None
+
+
+def _token(held: Mapping[str, str]) -> Secret | None:
+    # not _setting: a path is not going into a request, so what a header can
+    # carry is not the question to ask of one
+    path = held.get(TOKEN_FILE, "").strip()
+    if not path:
+        # a blank is what a chart renders for a setting nobody filled in, so it
+        # names nothing and the variable is still the place to look
+        return _credential(held.get(TOKEN))
+    if len(path) > MAX_SETTING:
+        return None
+    return _held(path)
+
+
+def _held(path: str) -> Secret | None:
+    try:
+        # a path can name something a read never returns from, and finding that
+        # out by waiting is a start the workload does not come back from
+        opened = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+        with os.fdopen(opened, encoding="utf-8", errors="strict") as fh:
+            if not stat.S_ISREG(os.fstat(fh.fileno()).st_mode):
+                return None
+            return _credential(fh.read(MAX_SETTING + 1))
+    except (OSError, ValueError):
+        # never the value, only that there was not one: what is put in a message
+        # here is put wherever the host sends what it cannot read
+        return None
+
+
+def _credential(value: str | None) -> Secret | None:
+    if value is None:
+        return None
+    named = value.strip()
+    # a credential travels in a header, so a blank inside one would end the line
+    # and start something the workload wrote
+    return Secret(named) if _readable(named) else None
+
+
+def asked(environ: Mapping[str, str] | None = None) -> bool:
+    """Say whether the workload asked for its reports to be delivered at all."""
+    try:
+        held = os.environ if environ is None else environ
+        return _setting(held, ENDPOINT) is not None or ENDPOINT in held
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def delivery(environ: Mapping[str, str] | None = None) -> Delivery | None:
+    """Read where reports go, or nothing at all if it cannot be read whole."""
+    try:
+        held = os.environ if environ is None else environ
+        endpoint = _setting(held, ENDPOINT)
+        token = _token(held)
+        if endpoint is None or token is None or not endpoint.startswith(SCHEME):
+            return None
+        return Delivery(
+            endpoint=endpoint,
+            token=token,
+            group=_setting(held, GROUP),
+            workload=_setting(held, WORKLOAD),
+        )
+    except Exception:  # noqa: BLE001
+        # a setting that cannot be read is not one to act on
+        return None

fluidattacks_agent/sink.py

@@ -0,0 +1,163 @@
+"""Leave a report where something can pick it up, or refuse and say which."""
+
+import contextlib
+import errno
+import os
+import stat
+from dataclasses import dataclass, field
+from typing import Final, Protocol
+
+# the path is a contract with the agent that drains it
+REPORT_DIR: Final = "/tmp/.watches-exec"  # noqa: S108
+REPORT_SUFFIX: Final = ".report"
+STAGE_SUFFIX: Final = ".tmp"
+
+# reports of its own, bytes any report holds, and entries it will walk to count
+MAX_OUTSTANDING: Final = 64
+MAX_OUTSTANDING_BYTES: Final = 8 << 20
+MAX_ENTRIES: Final = 4096
+
+SHARED: Final = 0o077
+
+
+class Stalled(OSError):
+    """Nothing was taken, and what was not taken is still owed."""
+
+
+class Sink(Protocol):
+    """Somewhere a report can go, which may refuse it and must never lie."""
+
+    def write(self, text: str) -> None: ...
+
+
+def ours(status: os.stat_result) -> bool:
+    """Say whether what the status describes is ours alone to write."""
+    return status.st_uid == os.geteuid() and not status.st_mode & SHARED
+
+
+@dataclass(frozen=True)
+class Held:
+    """What one directory entry costs, and whether the sink left it there."""
+
+    size: int
+    mine: bool
+
+
+def _held(entry: os.DirEntry[str], stem: str) -> Held:
+    if not entry.name.endswith(REPORT_SUFFIX):
+        return Held(size=0, mine=False)
+    try:
+        status = entry.stat(follow_symlinks=False)
+    except OSError:
+        return Held(size=0, mine=False)
+    if not stat.S_ISREG(status.st_mode):
+        return Held(size=0, mine=False)
+    return Held(size=status.st_size, mine=entry.name.startswith(stem))
+
+
+class Holding:
+    """A sink for a workload that asked for delivery, which nothing yet does."""
+
+    def write(self, text: str) -> None:
+        """Take nothing, and be counted for it."""
+        raise Stalled(errno.ENOSYS, "nothing delivers yet", len(text))
+
+
+@dataclass
+class FileSink:
+    """Reports left in a directory of our own for the agent to drain."""
+
+    directory: str | os.PathLike[str] = REPORT_DIR
+    written: int = 0
+    # so a report of ours cannot be named by anything that did not write it,
+    # and a reused pid never counts its predecessor's against itself
+    token: str = field(default_factory=lambda: os.urandom(8).hex())
+
+    def write(self, text: str) -> None:
+        """Take a report, unless what is already here says to stop."""
+        directory = self._open_directory()
+        try:
+            # installed on its own nothing drains this, so the ceiling is ours
+            if self._piled(directory):
+                raise Stalled(errno.ENOSPC, "reports outstanding")
+            self._write_into(directory, text)
+        finally:
+            os.close(directory)
+
+    def _open_directory(self) -> int:
+        # every way this can fail is a flush that did not land, and one that
+        # said so as anything else was a mute nothing counted: a directory this
+        # cannot use costs an attacker one bit of its mode
+        try:
+            with contextlib.suppress(FileExistsError):
+                os.mkdir(self.directory, 0o700)  # noqa: PTH102
+            handle = os.open(self.directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        except OSError as refused:
+            raise Stalled(errno.EACCES, "no directory", str(self.directory)) from refused
+        # the mode a directory was made with says nothing about one that was
+        # already there, and the descriptor is what the answer has to be about
+        if ours(os.fstat(handle)):
+            return handle
+        os.close(handle)
+        raise Stalled(errno.EACCES, "not ours", str(self.directory))
+
+    def _piled(self, directory: int) -> bool:
+        mine = 0
+        bytes_held = 0
+        walked = 0
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                walked += 1
+                # too full to keep writing into, whoever filled it
+                if walked > MAX_ENTRIES:
+                    return True
+                held = _held(entry, self._stem())
+                bytes_held += held.size
+                mine += int(held.mine)
+                if mine >= MAX_OUTSTANDING or bytes_held >= MAX_OUTSTANDING_BYTES:
+                    return True
+        return False
+
+    def _stem(self) -> str:
+        return f"{os.getpid()}-{self.token}-"
+
+    def _write_into(self, directory: int, text: str) -> None:
+        payload = text.encode()
+        stem = f"{self._stem()}{self.written}"
+        staged = stem + STAGE_SUFFIX
+        # spent the moment it is tried: what sits under a name is not always
+        # ours to clear, and coming back to one forever is how one silences us
+        self.written += 1
+        try:
+            self._stage(directory, staged, payload)
+            os.replace(
+                staged,
+                stem + REPORT_SUFFIX,
+                src_dir_fd=directory,
+                dst_dir_fd=directory,
+            )
+        except OSError as refused:
+            # nothing will ever read what a failed attempt staged, and the name
+            # it holds counts against the entries this is willing to walk
+            with contextlib.suppress(OSError):
+                os.unlink(staged, dir_fd=directory)
+            raise Stalled(errno.ENOSPC, "not taken", staged) from refused
+
+    def _stage(self, directory: int, name: str, payload: bytes) -> None:
+        handle = self._create(directory, name)
+        try:
+            written = os.write(handle, payload)
+        finally:
+            os.close(handle)
+        # os.write does not raise on a partial write, and the statement is the
+        # last line, so a truncation takes it first
+        if written != len(payload):
+            raise OSError(errno.ENOSPC, "short write", name)
+
+    def _create(self, directory: int, name: str) -> int:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        try:
+            return os.open(name, flags, 0o600, dir_fd=directory)
+        except FileExistsError:
+            os.unlink(name, dir_fd=directory)
+            return os.open(name, flags, 0o600, dir_fd=directory)