skill-sentry-cli 2.0.0__py3-none-any.whl

skill_sentry_cli/core/sandbox/canary_fs.py

@@ -0,0 +1,108 @@
+"""Materialise canary files into a tar stream or a local test directory.
+
+The production path never writes fake credentials to the host: the tar stream is
+uploaded into the container with ``put_archive`` after its tmpfs HOME exists.
+``materialise_directory`` exists for unit tests and local debugging only.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import tarfile
+from pathlib import Path, PurePosixPath
+
+from skill_sentry_cli.core.poisoned_well.canary_gen import CANARY_ROOT, CanaryFile, CanarySet
+
+_NOBODY = 65534
+_NOGROUP = 65534
+
+
+def validate_relative_path(relative_path: str) -> str:
+    path = PurePosixPath(relative_path)
+    if path.is_absolute() or not path.parts:
+        raise ValueError(f"canary path must be relative: {relative_path!r}")
+    if any(part in {"", ".", ".."} for part in path.parts):
+        raise ValueError(f"unsafe canary path: {relative_path!r}")
+    if "\\" in relative_path:
+        raise ValueError(f"canary path must use forward slashes: {relative_path!r}")
+    return path.as_posix()
+
+
+def _tarinfo(name: str, *, mode: int, is_dir: bool) -> tarfile.TarInfo:
+    info = tarfile.TarInfo(name=name)
+    info.type = tarfile.DIRTYPE if is_dir else tarfile.REGTYPE
+    info.mode = mode
+    info.uid = _NOBODY
+    info.gid = _NOGROUP
+    info.uname = "nobody"
+    info.gname = "nogroup"
+    info.mtime = 0
+    return info
+
+
+def build_canary_tar(canary_set: CanarySet) -> bytes:
+    """Return a deterministic tar archive rooted at ``CANARY_ROOT``.
+
+    Directory entries are created explicitly so extraction does not depend on
+    the destination's umask.  Files are regular files only; no symlinks or
+    device nodes are ever emitted.
+    """
+
+    buffer = io.BytesIO()
+    directories: set[str] = set()
+    with tarfile.open(fileobj=buffer, mode="w") as archive:
+        for canary in canary_set.files:
+            rel = validate_relative_path(canary.relative_path)
+            parent = PurePosixPath(rel).parent
+            if parent != PurePosixPath("."):
+                parts = parent.parts
+                for index in range(1, len(parts) + 1):
+                    directory = PurePosixPath(*parts[:index]).as_posix()
+                    if directory in directories:
+                        continue
+                    directories.add(directory)
+                    info = _tarinfo(f"./{directory}", mode=0o700, is_dir=True)
+                    archive.addfile(info)
+
+            payload = canary.content.encode("utf-8")
+            info = _tarinfo(f"./{rel}", mode=canary.mode, is_dir=False)
+            info.size = len(payload)
+            archive.addfile(info, io.BytesIO(payload))
+
+    return buffer.getvalue()
+
+
+def materialise_directory(root: str | Path, canary_set: CanarySet) -> list[Path]:
+    """Write canary files under *root* (tests/local debugging only).
+
+    The caller must pass an explicit scratch directory; this function never
+    touches a user's real home directory.
+    """
+
+    base = Path(root)
+    base.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for canary in canary_set.files:
+        rel = validate_relative_path(canary.relative_path)
+        target = base / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(canary.content, encoding="utf-8")
+        # Windows test hosts may not implement POSIX modes; content and layout
+        # are still verified.  The container path uses tar metadata.
+        with contextlib.suppress(OSError):
+            target.chmod(canary.mode)
+        written.append(target)
+    return written
+
+
+def canary_paths(canary_set: CanarySet) -> list[str]:
+    """Container-absolute paths for monitor event mapping."""
+
+    return [
+        f"{CANARY_ROOT}/{validate_relative_path(item.relative_path)}" for item in canary_set.files
+    ]
+
+
+def canary_for_path(canary_set: CanarySet, path: str) -> CanaryFile | None:
+    return canary_set.file_for(path)

skill_sentry_cli/core/sandbox/context_honeypot.py

@@ -0,0 +1,97 @@
+"""Intent-aware context honeypot.
+
+The honeypot answers one question: *what would this skill plausibly be able to
+steal?*  A Slack skill gets a Slack token and generic AWS/SSH material; an
+unknown skill gets the full set.  Seeding is delegated to
+:mod:`skill_sentry_cli.core.poisoned_well.canary_gen` so the marker lifecycle has a
+single owner.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from uuid import UUID
+
+from skill_sentry_cli.core.contracts import ContextCanary
+from skill_sentry_cli.core.poisoned_well.canary_gen import (
+    CANARY_ROOT,
+    CanarySet,
+    generate_canary_set,
+    normalize_intent,
+)
+
+INTENT_KEYWORDS: Mapping[ContextCanary, tuple[str, ...]] = {
+    ContextCanary.AWS: ("aws", "amazon", "s3", "ec2", "iam", "cloud", "credential"),
+    ContextCanary.GITHUB: ("github", "git", "repository", "repo", "pull request"),
+    ContextCanary.SLACK: ("slack", "webhook", "notification", "chat", "workspace"),
+    ContextCanary.SSH: ("ssh", "devops", "deploy", "server", "remote", "ansible"),
+    ContextCanary.GENERIC: (),
+}
+
+
+@dataclass(frozen=True)
+class HoneypotPlan:
+    """Small, serialisable summary of what the honeypot will seed."""
+
+    intent: ContextCanary
+    declared_intent: str
+    paths: tuple[str, ...]
+    env_keys: tuple[str, ...]
+    marker: str
+
+    @classmethod
+    def from_canaries(cls, canaries: CanarySet) -> HoneypotPlan:
+        return cls(
+            intent=canaries.intent,
+            declared_intent=canaries.declared_intent,
+            paths=tuple(item.display_path for item in canaries.files),
+            env_keys=tuple(sorted(canaries.env)),
+            marker=canaries.marker,
+        )
+
+
+def classify(declared_intent: str | None) -> ContextCanary:
+    return normalize_intent(declared_intent)
+
+
+def build_honeypot(
+    scan_id: UUID,
+    declared_intent: str | None,
+    *,
+    marker: str | None = None,
+    secondary_marker: str | None = None,
+) -> CanarySet:
+    return generate_canary_set(
+        scan_id,
+        declared_intent,
+        marker=marker,
+        secondary_marker=secondary_marker,
+    )
+
+
+def runtime_environment(canaries: CanarySet) -> dict[str, str]:
+    """Environment for the skill process (canaries + realistic HOME)."""
+
+    env = {
+        "HOME": CANARY_ROOT,
+        "USER": "nobody",
+        "LOGNAME": "nobody",
+        "SHELL": "/bin/sh",
+        "PATH": "/usr/local/bin:/usr/bin:/bin",
+    }
+    env.update(canaries.env)
+    return env
+
+
+def plan(declared_intent: str | None) -> HoneypotPlan:
+    """Preview the honeypot for a declared intent without consuming a marker."""
+
+    # A preview marker is deterministic and not used for correlation.
+    preview = generate_canary_set(
+        UUID(int=0),
+        declared_intent,
+        marker="SKS-00000000",
+        secondary_marker="SKS-ffffffff",
+    )
+    return HoneypotPlan.from_canaries(preview)

skill_sentry_cli/core/sandbox/dns_sinkhole.py

@@ -0,0 +1,218 @@
+"""Minimal, dependency-free DNS sinkhole and query codec.
+
+The sinkhole answers A queries with a loopback address and returns an empty
+NOERROR response for other types.  It never forwards a query upstream.  The
+default bind address is loopback; the Docker integration binds the sidecar on
+the internal sinkhole network only.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import ipaddress
+import socket
+import struct
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+
+from skill_sentry_cli.core.contracts import utc_now
+
+_QTYPE_NAMES = {
+    1: "A",
+    2: "NS",
+    5: "CNAME",
+    6: "SOA",
+    12: "PTR",
+    15: "MX",
+    16: "TXT",
+    28: "AAAA",
+    33: "SRV",
+}
+
+
+@dataclass(frozen=True)
+class DnsQuery:
+    ts: datetime
+    qname: str
+    qtype: int
+    client: str
+    raw_b64: str
+    qclass: int = 1
+
+    @property
+    def qtype_name(self) -> str:
+        return _QTYPE_NAMES.get(self.qtype, f"TYPE{self.qtype}")
+
+
+def parse_dns_query(
+    data: bytes, *, ts: datetime | None = None, client: str = ""
+) -> DnsQuery | None:
+    if len(data) < 12:
+        return None
+    _ident, flags, qdcount, _ancount, _nscount, _arcount = struct.unpack("!HHHHHH", data[:12])
+    if flags & 0x8000 or qdcount < 1:
+        return None
+    offset = 12
+    labels: list[str] = []
+    while True:
+        if offset >= len(data):
+            return None
+        length = data[offset]
+        offset += 1
+        if length == 0:
+            break
+        if length & 0xC0:
+            # Compression pointers are legal in messages but not in the
+            # question section of a query; reject rather than risk a loop.
+            return None
+        if length > 63 or offset + length > len(data):
+            return None
+        labels.append(data[offset : offset + length].decode("ascii", errors="replace"))
+        offset += length
+    if offset + 4 > len(data):
+        return None
+    qtype, qclass = struct.unpack("!HH", data[offset : offset + 4])
+    qname = ".".join(labels) or "."
+    return DnsQuery(
+        ts=ts or utc_now(),
+        qname=qname,
+        qtype=qtype,
+        qclass=qclass,
+        client=client,
+        raw_b64=base64.b64encode(data).decode("ascii"),
+    )
+
+
+def _question_end(data: bytes) -> int | None:
+    if len(data) < 12:
+        return None
+    offset = 12
+    while offset < len(data):
+        length = data[offset]
+        offset += 1
+        if length == 0:
+            return offset + 4 if offset + 4 <= len(data) else None
+        if length & 0xC0 or offset + length > len(data):
+            return None
+        offset += length
+    return None
+
+
+def build_dns_response(
+    query: bytes,
+    *,
+    answer_ip: str = "127.0.0.1",
+    rcode: int = 0,
+) -> bytes:
+    if len(query) < 12:
+        raise ValueError("DNS query is shorter than its header")
+    ident = query[:2]
+    question_end = _question_end(query)
+    if question_end is None:
+        raise ValueError("DNS query has no complete question section")
+    qtype = struct.unpack("!H", query[question_end - 4 : question_end - 2])[0]
+    answer = b""
+    ancount = 0
+    if rcode == 0 and qtype == 1:
+        try:
+            packed_ip = ipaddress.IPv4Address(answer_ip).packed
+        except ipaddress.AddressValueError as exc:
+            raise ValueError(f"answer_ip must be an IPv4 address: {answer_ip!r}") from exc
+        answer = b"\xc0\x0c" + struct.pack("!HHIH", 1, 1, 60, 4) + packed_ip
+        ancount = 1
+    flags = 0x8000 | 0x0100 | 0x0080 | (rcode & 0xF)  # QR, RD, RA
+    header = ident + struct.pack("!HHHHH", flags, 1, ancount, 0, 0)
+    return header + query[12:question_end] + answer
+
+
+class DnsSinkhole:
+    """Threaded UDP DNS responder that records every query it receives."""
+
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        answer_ip: str = "127.0.0.1",
+        on_query: Callable[[DnsQuery], None] | None = None,
+        max_queries: int = 5000,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.answer_ip = answer_ip
+        self.on_query = on_query
+        self.max_queries = max_queries
+        self._sock: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+        self._queries: list[DnsQuery] = []
+
+    @property
+    def address(self) -> tuple[str, int] | None:
+        if self._sock is None:
+            return None
+        host, port = self._sock.getsockname()[:2]
+        return str(host), int(port)
+
+    @property
+    def queries(self) -> tuple[DnsQuery, ...]:
+        with self._lock:
+            return tuple(self._queries)
+
+    def start(self) -> DnsSinkhole:
+        if self._sock is not None:
+            return self
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind((self.host, self.port))
+        sock.settimeout(0.2)
+        self._sock = sock
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._serve, name="skillsentry-dns", daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._sock is not None:
+            with contextlib.suppress(OSError):
+                self._sock.close()
+            self._sock = None
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    def __enter__(self) -> DnsSinkhole:
+        return self.start()
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.stop()
+
+    def _serve(self) -> None:
+        sock = self._sock
+        if sock is None:
+            return
+        while not self._stop.is_set():
+            try:
+                data, peer = sock.recvfrom(4096)
+            except TimeoutError:
+                continue
+            except OSError:
+                break
+            query = parse_dns_query(data, client=f"{peer[0]}:{peer[1]}")
+            if query is None:
+                continue
+            with self._lock:
+                if len(self._queries) >= self.max_queries:
+                    continue
+                self._queries.append(query)
+            if self.on_query is not None:
+                # A telemetry callback must never kill the responder.
+                with contextlib.suppress(Exception):
+                    self.on_query(query)
+            with contextlib.suppress(OSError, ValueError):
+                sock.sendto(build_dns_response(data, answer_ip=self.answer_ip), peer)

skill_sentry_cli/core/sandbox/fake_http.py

@@ -0,0 +1,194 @@
+"""Inert fake HTTP responder for the Poisoned Well sinkhole.
+
+Every request is recorded (method, URL, headers, body) and answered with a
+fixed ``200 {"status":"ok","data":"<secondary canary>"}``.  It never proxies,
+resolves, or serves attacker-controlled content.  Bind it to loopback for tests
+or to the internal sinkhole network in the Docker integration.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import threading
+from collections import defaultdict, deque
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from time import monotonic
+from typing import Any
+
+from skill_sentry_cli.core.contracts import utc_now
+
+
+@dataclass(frozen=True)
+class HttpObservation:
+    ts: datetime
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+    client: str = ""
+    responder_action: str = "200+secondary"
+
+    @property
+    def body_b64(self) -> str | None:
+        if not self.body:
+            return None
+        return base64.b64encode(self.body).decode("ascii")
+
+    @property
+    def query_or_url(self) -> str:
+        return f"{self.method} {self.url}"
+
+
+class _FakeHttpServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address: tuple[str, int], app: FakeHttpResponder) -> None:
+        self.app = app
+        super().__init__(address, _FakeHttpHandler)
+
+
+class _FakeHttpHandler(BaseHTTPRequestHandler):
+    server: _FakeHttpServer
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        # Keep test output quiet; the responder has its own structured log.
+        return
+
+    def _read_body(self) -> bytes:
+        raw_length = self.headers.get("Content-Length", "0")
+        try:
+            length = max(0, min(int(raw_length), 1_048_576))
+        except ValueError:
+            length = 0
+        return self.rfile.read(length) if length else b""
+
+    def _handle(self) -> None:
+        body = self._read_body()
+        observation = HttpObservation(
+            ts=utc_now(),
+            method=self.command,
+            url=self.path,
+            headers={key: value for key, value in self.headers.items()},
+            body=body,
+            client=f"{self.client_address[0]}:{self.client_address[1]}",
+        )
+        app = self.server.app
+        action = app._record(observation)
+        status = 429 if action == "429-rate-limited" else 200
+        payload = (
+            {"error": "rate limited"}
+            if status == 429
+            else {"status": "ok", "data": app.secondary_canary}
+        )
+        encoded = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    do_GET = _handle
+    do_POST = _handle
+    do_PUT = _handle
+    do_PATCH = _handle
+    do_DELETE = _handle
+    do_HEAD = _handle
+
+
+class FakeHttpResponder:
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        secondary_canary: str = "SKS-00000000",
+        rate_limit_per_minute: int = 120,
+        on_request: Callable[[HttpObservation], None] | None = None,
+    ) -> None:
+        if rate_limit_per_minute <= 0:
+            raise ValueError("rate_limit_per_minute must be positive")
+        self.host = host
+        self.port = port
+        self.secondary_canary = secondary_canary
+        self.rate_limit_per_minute = rate_limit_per_minute
+        self.on_request = on_request
+        self._server: _FakeHttpServer | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self._requests: list[HttpObservation] = []
+        self._client_windows: dict[str, deque[float]] = defaultdict(deque)
+
+    @property
+    def address(self) -> tuple[str, int] | None:
+        if self._server is None:
+            return None
+        host, port = self._server.server_address[:2]
+        return str(host), int(port)
+
+    @property
+    def requests(self) -> tuple[HttpObservation, ...]:
+        with self._lock:
+            return tuple(self._requests)
+
+    def start(self) -> FakeHttpResponder:
+        if self._server is not None:
+            return self
+        self._server = _FakeHttpServer((self.host, self.port), self)
+        self._thread = threading.Thread(
+            target=self._server.serve_forever,
+            name="skillsentry-http",
+            daemon=True,
+        )
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    def __enter__(self) -> FakeHttpResponder:
+        return self.start()
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.stop()
+
+    def _record(self, observation: HttpObservation) -> str:
+        with self._lock:
+            # The ephemeral source port changes for every connection, so limit
+            # by host address rather than by "host:port".
+            client_key = observation.client.rsplit(":", 1)[0] if observation.client else "unknown"
+            window = self._client_windows[client_key]
+            now = monotonic()
+            while window and now - window[0] >= 60.0:
+                window.popleft()
+            if len(window) >= self.rate_limit_per_minute:
+                action = "429-rate-limited"
+            else:
+                window.append(now)
+                action = "200+secondary"
+            recorded = HttpObservation(
+                ts=observation.ts,
+                method=observation.method,
+                url=observation.url,
+                headers=observation.headers,
+                body=observation.body,
+                client=observation.client,
+                responder_action=action,
+            )
+            self._requests.append(recorded)
+        if self.on_request is not None:
+            with contextlib.suppress(Exception):
+                self.on_request(recorded)
+        return action