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

skill_sentry_cli/core/evasion/__init__.py

@@ -0,0 +1,27 @@
+"""Sandbox-evasion probe classification and hard-evidence overrides."""
+
+from __future__ import annotations
+
+from skill_sentry_cli.core.evasion.detector import (
+    PROBE_COMMANDS,
+    PROBE_PATHS,
+    EvasionResult,
+    ProbeEvent,
+    classify_probe,
+    detect_probes,
+    is_probe_command,
+    is_probe_path,
+    probe_kind_for_path,
+)
+
+__all__ = [
+    "PROBE_COMMANDS",
+    "PROBE_PATHS",
+    "EvasionResult",
+    "ProbeEvent",
+    "classify_probe",
+    "detect_probes",
+    "is_probe_command",
+    "is_probe_path",
+    "probe_kind_for_path",
+]

skill_sentry_cli/core/evasion/detector.py

@@ -0,0 +1,210 @@
+"""Sandbox-evasion probe classification (docs/02 §2.3, docs/04 §4.5).
+
+Any observed probe is hard evidence and produces a ``MALICIOUS`` override with
+confidence 1.0.  A masquerade verification failure is *not* a probe and must be
+handled as an engine error by the runner; it can never produce a clean verdict.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import PurePosixPath
+from typing import Any
+
+from skill_sentry_cli.core.contracts import OverrideSignal, Stage, VerdictTier
+from skill_sentry_cli.core.sandbox.monitor import MonitorEvent
+
+PROBE_PATHS: dict[str, str] = {
+    "/.dockerenv": "docker_artifact",
+    "/proc/1/cgroup": "cgroup_probe",
+    "/proc/self/cgroup": "cgroup_probe",
+    "/proc/1/mountinfo": "mountinfo_probe",
+    "/proc/self/mountinfo": "mountinfo_probe",
+    "/proc/bus/input/devices": "vm_artifact",
+    "/sys/class/dmi/id/product_name": "vm_artifact",
+    "/sys/class/dmi/id/sys_vendor": "vm_artifact",
+    "/sys/class/dmi/id/board_vendor": "vm_artifact",
+    "/sys/hypervisor/type": "vm_artifact",
+    "/dev/kmsg": "kernel_probe",
+}
+
+PROBE_COMMANDS: frozenset[str] = frozenset(
+    {
+        "df",
+        "mount",
+        "lsblk",
+        "systemd-detect-virt",
+        "dmidecode",
+        "lscpu",
+    }
+)
+
+_PROBE_PATH_PREFIXES = (
+    "/proc/1/cgroup",
+    "/proc/self/cgroup",
+    "/proc/1/mountinfo",
+    "/proc/self/mountinfo",
+    "/proc/bus/input",
+    "/sys/class/dmi/id/",
+    "/sys/hypervisor/",
+)
+
+
+@dataclass(frozen=True)
+class ProbeEvent:
+    ts: datetime
+    kind: str
+    target: str
+    process: str | None = None
+    detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class EvasionResult:
+    detected: bool
+    probes: tuple[ProbeEvent, ...] = ()
+    masquerade_failed: bool = False
+    error: str | None = None
+
+    @property
+    def targets(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(probe.target for probe in self.probes))
+
+    @property
+    def kinds(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(probe.kind for probe in self.probes))
+
+    def to_override(self) -> OverrideSignal | None:
+        if not self.detected:
+            return None
+        targets = ", ".join(self.targets)
+        return OverrideSignal(
+            verdict=VerdictTier.MALICIOUS,
+            confidence=1.0,
+            reason=f"Sandbox evasion probe detected ({targets}).",
+            source=Stage.EVASION,
+            evidence={
+                "probes": [
+                    {
+                        "ts": probe.ts.isoformat(),
+                        "kind": probe.kind,
+                        "target": probe.target,
+                        "process": probe.process,
+                    }
+                    for probe in self.probes
+                ],
+                "sandboxEvasionDetected": True,
+            },
+        )
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "evasionDetected": self.detected,
+            "probes": list(self.targets),
+            "probeKinds": list(self.kinds),
+            "masqueradeFailed": self.masquerade_failed,
+            "error": self.error,
+        }
+
+    @classmethod
+    def engine_error(cls, message: str) -> EvasionResult:
+        return cls(detected=False, masquerade_failed=True, error=message)
+
+
+def is_probe_path(path: str) -> bool:
+    clean = path.rstrip("/") or "/"
+    if clean in PROBE_PATHS:
+        return True
+    return any(clean.startswith(prefix) for prefix in _PROBE_PATH_PREFIXES)
+
+
+def probe_kind_for_path(path: str) -> str | None:
+    clean = path.rstrip("/") or "/"
+    if clean in PROBE_PATHS:
+        return PROBE_PATHS[clean]
+    for prefix in _PROBE_PATH_PREFIXES:
+        if clean.startswith(prefix):
+            return "vm_artifact" if prefix.startswith("/sys/") else "filesystem_probe"
+    return None
+
+
+def _command_basename(command: str) -> str:
+    # Commands may be an argv list flattened by the shim, or a shell string.
+    first = command.strip().split()[0] if command.strip() else ""
+    return PurePosixPath(first).name
+
+
+def is_probe_command(command: str) -> bool:
+    return _command_basename(command) in PROBE_COMMANDS
+
+
+def classify_probe(
+    target: str,
+    *,
+    ts: datetime,
+    process: str | None = None,
+    detail: dict[str, Any] | None = None,
+) -> ProbeEvent | None:
+    detail = detail or {}
+    if detail.get("kind") == "command" or is_probe_command(target):
+        base = _command_basename(target)
+        if base in PROBE_COMMANDS:
+            return ProbeEvent(
+                ts=ts,
+                kind="command_probe",
+                target=base,
+                process=process,
+                detail=detail,
+            )
+    if is_probe_path(target):
+        return ProbeEvent(
+            ts=ts,
+            kind=probe_kind_for_path(target) or "filesystem_probe",
+            target=target,
+            process=process,
+            detail=detail,
+        )
+    return None
+
+
+def detect_probes(events: list[MonitorEvent]) -> EvasionResult:
+    probes: list[ProbeEvent] = []
+    seen: set[tuple[str, str]] = set()
+    for event in events:
+        target = event.path_or_channel
+        if not target:
+            continue
+        if event.event_type == "probe_detected":
+            probe = classify_probe(
+                target,
+                ts=event.ts,
+                process=event.process,
+                detail=event.detail,
+            )
+        else:
+            # Defence in depth: a shim version that logs an open instead of a
+            # probe event is still treated as a probe.
+            probe = classify_probe(
+                target,
+                ts=event.ts,
+                process=event.process,
+                detail=event.detail,
+            )
+        if probe is None:
+            continue
+        key = (probe.kind, probe.target)
+        if key in seen:
+            continue
+        seen.add(key)
+        probes.append(probe)
+    probes.sort(key=lambda probe: probe.ts)
+    return EvasionResult(detected=bool(probes), probes=tuple(probes))
+
+
+def probe_summary_pattern() -> re.Pattern[str]:
+    """Readable pattern used by docs/tests to keep the probe list discoverable."""
+
+    names = "|".join(sorted(re.escape(name) for name in PROBE_COMMANDS))
+    return re.compile(rf"(^|[;&|]\s*)(?:{names})(\s|$)")

skill_sentry_cli/core/exit_codes.py

@@ -0,0 +1,13 @@
+"""CLI exit codes (docs/07-cli-reference.md §7.5)."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    VERDICT = 1
+    USAGE = 2
+    OPERATIONAL = 3
+    MODEL_UNAVAILABLE = 4

skill_sentry_cli/core/models/__init__.py

@@ -0,0 +1,20 @@
+"""Model plumbing (I2): providers, schema validation, and backend selection."""
+
+from skill_sentry_cli.core.models.base import ModelClient, ModelError, ModelUnavailable
+from skill_sentry_cli.core.models.gemma_cloud import GemmaCloud
+from skill_sentry_cli.core.models.gemma_local import GemmaLocal
+from skill_sentry_cli.core.models.image_utils import ImagePreparationError, load_image_for_model
+from skill_sentry_cli.core.models.mock import MockGemma
+from skill_sentry_cli.core.models.selector import select_model
+
+__all__ = [
+    "GemmaCloud",
+    "GemmaLocal",
+    "ImagePreparationError",
+    "MockGemma",
+    "ModelClient",
+    "ModelError",
+    "ModelUnavailable",
+    "load_image_for_model",
+    "select_model",
+]

skill_sentry_cli/core/models/_json.py

@@ -0,0 +1,147 @@
+"""Small, dependency-free JSON helpers shared by the model clients.
+
+The real model backends must never hand malformed data to Dev 2's analyzers.
+This module parses model text defensively and validates the common JSON Schema
+features used by the I2 prompts.  It is deliberately not a full JSON Schema
+implementation; unsupported keywords are ignored rather than rejecting a
+useful response.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def parse_json_object(text: str) -> dict[str, Any]:
+    """Parse a model response into a JSON object.
+
+    Models occasionally wrap JSON in Markdown fences or surround it with a
+    sentence.  We first try the whole string, then the first ``{`` through the
+    last ``}``.  Anything that is not an object is rejected: the I2 contract
+    only permits objects.
+    """
+
+    candidate = _strip_fences(text).strip()
+    for value in (candidate, _object_slice(candidate)):
+        if not value:
+            continue
+        try:
+            parsed = json.loads(value)
+        except (TypeError, ValueError):
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    raise ValueError("model response is not a JSON object")
+
+
+def validate_json(instance: Any, schema: dict[str, Any]) -> None:
+    """Validate ``instance`` against the JSON Schema subset we emit.
+
+    Raises ``ValueError`` with a path to the first mismatch.  ``$ref`` is
+    intentionally not supported; the prompts use flat, self-contained schemas.
+    """
+
+    _validate(instance, schema, "$", schema)
+
+
+def _validate(instance: Any, schema: Any, path: str, root: dict[str, Any]) -> None:
+    if schema is True or schema == {}:
+        return
+    if schema is False:
+        raise ValueError(f"{path}: schema forbids any value")
+    if not isinstance(schema, dict):
+        return
+
+    if "const" in schema and instance != schema["const"]:
+        raise ValueError(f"{path}: expected constant {schema['const']!r}")
+    if "enum" in schema and instance not in schema["enum"]:
+        raise ValueError(f"{path}: value is not in enum")
+
+    expected = schema.get("type")
+    if expected is not None and not _matches_type(instance, expected):
+        raise ValueError(f"{path}: expected {expected}, got {type(instance).__name__}")
+
+    if isinstance(instance, dict):
+        _validate_object(instance, schema, path, root)
+    elif isinstance(instance, list):
+        item_schema = schema.get("items")
+        if item_schema is not None:
+            for index, item in enumerate(instance):
+                _validate(item, item_schema, f"{path}[{index}]", root)
+
+    if isinstance(instance, str):
+        if "minLength" in schema and len(instance) < int(schema["minLength"]):
+            raise ValueError(f"{path}: string is too short")
+        if "maxLength" in schema and len(instance) > int(schema["maxLength"]):
+            raise ValueError(f"{path}: string is too long")
+    if isinstance(instance, (int, float)) and not isinstance(instance, bool):
+        if "minimum" in schema and instance < schema["minimum"]:
+            raise ValueError(f"{path}: number is below minimum")
+        if "maximum" in schema and instance > schema["maximum"]:
+            raise ValueError(f"{path}: number is above maximum")
+
+
+def _validate_object(
+    instance: dict[str, Any], schema: dict[str, Any], path: str, root: dict[str, Any]
+) -> None:
+    required = schema.get("required") or []
+    for key in required:
+        if key not in instance:
+            raise ValueError(f"{path}: missing required property {key!r}")
+
+    properties = schema.get("properties") or {}
+    if not isinstance(properties, dict):
+        properties = {}
+    for key, value in instance.items():
+        if key in properties:
+            _validate(value, properties[key], f"{path}.{key}", root)
+            continue
+        additional = schema.get("additionalProperties", True)
+        if additional is False:
+            raise ValueError(f"{path}: unexpected property {key!r}")
+        if isinstance(additional, dict):
+            _validate(value, additional, f"{path}.{key}", root)
+
+
+def _matches_type(value: Any, expected: Any) -> bool:
+    choices = expected if isinstance(expected, list) else [expected]
+    for choice in choices:
+        if choice == "object" and isinstance(value, dict):
+            return True
+        if choice == "array" and isinstance(value, list):
+            return True
+        if choice == "string" and isinstance(value, str):
+            return True
+        if choice == "integer" and isinstance(value, int) and not isinstance(value, bool):
+            return True
+        if choice == "number" and isinstance(value, (int, float)) and not isinstance(value, bool):
+            return True
+        if choice == "boolean" and isinstance(value, bool):
+            return True
+        if choice == "null" and value is None:
+            return True
+    return False
+
+
+def _strip_fences(text: str) -> str:
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return stripped
+    lines = stripped.splitlines()
+    if lines and lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].strip() == "```":
+        lines = lines[:-1]
+    return "\n".join(lines).strip()
+
+
+def _object_slice(text: str) -> str:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end <= start:
+        return ""
+    return text[start : end + 1]
+
+
+__all__ = ["parse_json_object", "validate_json"]

skill_sentry_cli/core/models/base.py

@@ -0,0 +1,50 @@
+"""Model-client interface **I2** (producer: Dev 1; consumer: Dev 2).
+
+``generate_json`` must return a dict matching the supplied JSON Schema.
+``analyze_image`` returns OCR text, normalised bounding boxes and findings.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from skill_sentry_cli.core.contracts import ImageAnalysis
+
+
+class ModelError(RuntimeError):
+    """Base class for model failures."""
+
+
+class ModelUnavailable(ModelError):
+    """No backend is reachable (callers must emit a ``*-unavailable`` finding)."""
+
+
+@runtime_checkable
+class ModelClient(Protocol):
+    """Typed interface between Dev 2's analyzers and Dev 1's model plumbing."""
+
+    backend: str
+    model_version: str
+
+    def generate_json(
+        self,
+        system: str,
+        user: str,
+        schema: dict[str, Any],
+        retries: int = 1,
+    ) -> dict[str, Any]:
+        """Run a text completion constrained to ``schema``.
+
+        Implementations must retry once on malformed JSON, then raise
+        :class:`ModelUnavailable`.
+        """
+        ...
+
+    def analyze_image(self, path: str | Path, prompt: str) -> ImageAnalysis:
+        """OCR and classify one image (path on disk, no network fetch)."""
+        ...
+
+    def health(self) -> bool:
+        """Cheap liveness probe; must not raise."""
+        ...