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

skill_sentry_cli/core/sandbox/instructions.py

@@ -0,0 +1,170 @@
+"""Sandbox execution plan (INT-4).
+
+The plan says what the sandbox is asked to check and why.  Baseline checks are
+always present.  Checks derived from deterministic anchors only add to them, and
+nothing can remove a baseline check.  Only the declared entrypoint may run, and a
+plan that fails validation blocks execution, so the stage degrades instead of
+running with a partial or unsafe plan.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from skill_sentry_cli.core.contracts import StageResult
+from skill_sentry_cli.core.parser import SkillPackage
+
+MAX_CHECK_TIMEOUT_S = 600
+
+
+class InstructionCategory(str, Enum):
+    TRIGGER_EXECUTION = "TRIGGER_EXECUTION"
+    CREDENTIAL_CANARY_MONITOR = "CREDENTIAL_CANARY_MONITOR"
+    DNS_SINKHOLE_WATCH = "DNS_SINKHOLE_WATCH"
+    HTTP_EXFIL_MONITOR = "HTTP_EXFIL_MONITOR"
+    EVASION_PROBE_WATCH = "EVASION_PROBE_WATCH"
+
+
+class InstructionSource(str, Enum):
+    BASELINE = "baseline"
+    DETERMINISTIC_ANCHOR = "deterministicAnchor"
+
+
+BASELINE_CATEGORIES: tuple[InstructionCategory, ...] = (
+    InstructionCategory.TRIGGER_EXECUTION,
+    InstructionCategory.CREDENTIAL_CANARY_MONITOR,
+    InstructionCategory.DNS_SINKHOLE_WATCH,
+    InstructionCategory.HTTP_EXFIL_MONITOR,
+    InstructionCategory.EVASION_PROBE_WATCH,
+)
+
+# Anchor finding types that call for an extra watch, on top of the baseline.
+_ANCHOR_WATCHES: dict[str, InstructionCategory] = {
+    "credential-path": InstructionCategory.CREDENTIAL_CANARY_MONITOR,
+    "secret-access": InstructionCategory.CREDENTIAL_CANARY_MONITOR,
+    "dns-lookup": InstructionCategory.DNS_SINKHOLE_WATCH,
+    "exfil-http-post": InstructionCategory.HTTP_EXFIL_MONITOR,
+    "raw-socket": InstructionCategory.HTTP_EXFIL_MONITOR,
+    "reverse-shell": InstructionCategory.HTTP_EXFIL_MONITOR,
+    "sandbox-artifact": InstructionCategory.EVASION_PROBE_WATCH,
+}
+
+
+class SandboxActionInstruction(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    instruction_id: str = Field(min_length=1, max_length=80)
+    category: InstructionCategory
+    reason: str = Field(min_length=1, max_length=500)
+    source: InstructionSource
+    check: str = Field(min_length=1, max_length=200)
+    timeout_s: int = Field(ge=1, le=MAX_CHECK_TIMEOUT_S)
+    required: bool
+
+
+class SandboxExecutionPlan(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    instructions: list[SandboxActionInstruction] = Field(default_factory=list)
+    baseline_instructions: list[SandboxActionInstruction] = Field(default_factory=list)
+    declared_entrypoint: list[str] = Field(default_factory=list)
+    canary_context: str = ""
+    validation_status: Literal["valid", "invalid"] = "invalid"
+    problems: list[str] = Field(default_factory=list)
+
+
+def _baseline(timeout_s: int) -> list[SandboxActionInstruction]:
+    return [
+        SandboxActionInstruction(
+            instruction_id=f"baseline-{category.value.lower()}",
+            category=category,
+            reason="always checked for every skill",
+            source=InstructionSource.BASELINE,
+            check=category.value,
+            timeout_s=timeout_s,
+            required=True,
+        )
+        for category in BASELINE_CATEGORIES
+    ]
+
+
+def build_plan(
+    package: SkillPackage,
+    anchors: StageResult,
+    *,
+    timeout_s: int,
+) -> SandboxExecutionPlan:
+    """Build and validate the plan for one skill.
+
+    Anchor-derived watches are additive and optional.  The plan is valid only when
+    every baseline category is present, the entrypoint is declared, and every
+    timeout is within bounds.
+    """
+
+    timeout = max(1, min(int(timeout_s), MAX_CHECK_TIMEOUT_S))
+    baseline = _baseline(timeout)
+    additions: list[SandboxActionInstruction] = []
+    seen: set[tuple[str, str]] = set()
+    for finding in anchors.findings:
+        category = _ANCHOR_WATCHES.get(finding.finding_type or "")
+        if category is None:
+            continue
+        key = (category.value, finding.evidence.file or "")
+        if key in seen:
+            continue
+        seen.add(key)
+        additions.append(
+            SandboxActionInstruction(
+                instruction_id=f"anchor-{len(additions) + 1}-{category.value.lower()}",
+                category=category,
+                reason=(finding.message or "deterministic anchor")[:500],
+                source=InstructionSource.DETERMINISTIC_ANCHOR,
+                check=category.value,
+                timeout_s=timeout,
+                required=False,
+            )
+        )
+
+    plan = SandboxExecutionPlan(
+        instructions=baseline + additions,
+        baseline_instructions=baseline,
+        declared_entrypoint=list(package.entrypoint or []),
+        canary_context=(package.declared_intent or "")[:200],
+    )
+    problems = validate_plan(plan)
+    plan.problems = problems
+    plan.validation_status = "invalid" if problems else "valid"
+    return plan
+
+
+def validate_plan(plan: SandboxExecutionPlan) -> list[str]:
+    """Return the reasons a plan must not run; an empty list means it may run."""
+
+    problems: list[str] = []
+    if not plan.declared_entrypoint:
+        problems.append(
+            "no declared entrypoint, so the scripts were not executed; declare 'entrypoint:' "
+            "in SKILL.md so they can be tested. A fallback command is never guessed"
+        )
+    present = {instruction.category for instruction in plan.baseline_instructions}
+    missing = [category.value for category in BASELINE_CATEGORIES if category not in present]
+    if missing:
+        problems.append(f"baseline checks missing: {', '.join(missing)}")
+    for instruction in plan.instructions:
+        if not 1 <= instruction.timeout_s <= MAX_CHECK_TIMEOUT_S:
+            problems.append(f"timeout out of bounds for {instruction.instruction_id}")
+    return problems
+
+
+__all__ = [
+    "BASELINE_CATEGORIES",
+    "InstructionCategory",
+    "InstructionSource",
+    "SandboxActionInstruction",
+    "SandboxExecutionPlan",
+    "build_plan",
+    "validate_plan",
+]

skill_sentry_cli/core/sandbox/masquerade.py

@@ -0,0 +1,265 @@
+"""Masquerade configuration, shim source, and verification helpers.
+
+The shim hides ``/.dockerenv`` and redirects fake ``/proc`` views while logging
+canary reads and sandbox probes.  A failed verification is an **engine error**:
+the runner must not continue and must never emit a clean verdict.
+"""
+
+from __future__ import annotations
+
+import base64
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+ASSET_DIR = Path(__file__).resolve().parent / "assets"
+MASQUERADE_SOURCE_PATH = ASSET_DIR / "masquerade.c"
+RUN_SCRIPT_PATH = ASSET_DIR / "run_skill.sh"
+DOCKERFILE_PATH = ASSET_DIR / "Dockerfile.sandbox"
+
+SHIM_PATH = "/opt/skillsentry/masquerade.so"
+SHIM_LOG_PATH = "/tmp/skillsentry/events.jsonl"
+FAKE_CGROUP_PATH = "/tmp/skillsentry/cgroup"
+FAKE_MOUNTINFO_PATH = "/tmp/skillsentry/mountinfo"
+DOCKERENV_PATH = "/.dockerenv"
+CGROUP_PATH = "/proc/1/cgroup"
+MOUNTINFO_PATH = "/proc/self/mountinfo"
+
+FAKE_CGROUP_CONTENT = "0::/\n"
+FAKE_MOUNTINFO_CONTENT = (
+    "1 0 0:1 / / ext4 rw,relatime 0 0\n"
+    "2 1 0:2 / /proc proc rw,nosuid,nodev,noexec,relatime 0 0\n"
+    "3 1 0:3 / /sys sysfs ro,nosuid,nodev,noexec,relatime 0 0\n"
+    "4 1 0:4 / /tmp tmpfs rw,nosuid,nodev,noexec,relatime 0 0\n"
+    "5 1 0:5 / /home/sandbox tmpfs rw,nosuid,nodev,noexec,relatime 0 0\n"
+)
+
+
+class MasqueradeUnavailable(RuntimeError):
+    """The shim cannot be built or is absent from the image."""
+
+
+class MasqueradeError(RuntimeError):
+    """The shim is present but its hides/redirects did not verify."""
+
+
+@dataclass(frozen=True)
+class MasqueradeConfig:
+    shim_path: str = SHIM_PATH
+    require_shim: bool = True
+    dockerenv_source: str = "/dev/null"
+    dockerenv_target: str = DOCKERENV_PATH
+
+    def environment(self) -> dict[str, str]:
+        return {"LD_PRELOAD": self.shim_path}
+
+    def volumes(self) -> dict[str, dict[str, str]]:
+        # Docker 29+ rejects bind mounts whose target is inside /proc, so the
+        # fake cgroup/mountinfo views are served by the shim's path redirect
+        # rather than host bind mounts.
+        return {
+            self.dockerenv_source: {
+                "bind": self.dockerenv_target,
+                "mode": "ro",
+            }
+        }
+
+    def tmpfs(self) -> dict[str, str]:
+        # Kept as an extension point for callers that need a directory tmpfs.
+        return {}
+
+
+@dataclass(frozen=True)
+class MasqueradeCheck:
+    dockerenv_hidden: bool
+    cgroup_fake: bool
+    mountinfo_clean: bool
+    shim_present: bool
+    errors: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "dockerenvHidden": self.dockerenv_hidden,
+            "cgroupFake": self.cgroup_fake,
+            "mountinfoClean": self.mountinfo_clean,
+            "shimPresent": self.shim_present,
+            "errors": list(self.errors),
+        }
+
+
+def source_text() -> str:
+    return MASQUERADE_SOURCE_PATH.read_text(encoding="utf-8")
+
+
+def run_script_text() -> str:
+    return RUN_SCRIPT_PATH.read_text(encoding="utf-8")
+
+
+def compile_shim(
+    *,
+    source: str | Path | None = None,
+    output: str | Path | None = None,
+    compiler: str | None = None,
+) -> Path:
+    """Compile the shim with a local gcc (development/CI packaging helper)."""
+
+    gcc = compiler or shutil.which("gcc")
+    if not gcc:
+        raise MasqueradeUnavailable("gcc is unavailable; use the sandbox Docker image")
+    source_path = Path(source or MASQUERADE_SOURCE_PATH)
+    output_path = Path(output or (ASSET_DIR / "masquerade.so"))
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        completed = subprocess.run(
+            [
+                gcc,
+                "-shared",
+                "-fPIC",
+                "-O2",
+                "-Wall",
+                "-Wextra",
+                "-o",
+                str(output_path),
+                str(source_path),
+                "-ldl",
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise MasqueradeUnavailable(f"could not run gcc: {exc}") from exc
+    if completed.returncode != 0:
+        raise MasqueradeUnavailable(
+            f"gcc failed ({completed.returncode}): {completed.stderr.strip()}"
+        )
+    return output_path
+
+
+def _decode_b64(value: str) -> str:
+    try:
+        return base64.b64decode(value.encode("ascii"), validate=False).decode(
+            "utf-8", errors="replace"
+        )
+    except (ValueError, UnicodeError):
+        return ""
+
+
+def verify_outputs(
+    *,
+    dockerenv_exists: bool,
+    cgroup: str,
+    mountinfo: str,
+    shim_present: bool,
+    require_shim: bool = True,
+) -> MasqueradeCheck:
+    errors: list[str] = []
+    dockerenv_hidden = not dockerenv_exists
+    if not dockerenv_hidden:
+        errors.append("/.dockerenv is visible to the skill")
+
+    lowered_cgroup = cgroup.lower()
+    cgroup_fake = bool(cgroup.strip()) and not any(
+        marker in lowered_cgroup for marker in ("docker", "containerd", "kubepods")
+    )
+    if not cgroup_fake:
+        errors.append("/proc/1/cgroup still exposes container markers")
+
+    lowered_mountinfo = mountinfo.lower()
+    mountinfo_clean = not any(
+        marker in lowered_mountinfo
+        for marker in ("docker", "containerd", "overlay", "kubepods", "skillsentry")
+    )
+    if not mountinfo_clean:
+        errors.append("/proc/self/mountinfo still exposes container markers")
+
+    if require_shim and not shim_present:
+        errors.append("masquerade shim is missing from the sandbox image")
+
+    return MasqueradeCheck(
+        dockerenv_hidden=dockerenv_hidden,
+        cgroup_fake=cgroup_fake,
+        mountinfo_clean=mountinfo_clean,
+        shim_present=shim_present,
+        errors=tuple(errors),
+    )
+
+
+def verification_script(shim_path: str = SHIM_PATH) -> str:
+    """POSIX shell probe used by :func:`verify_container`."""
+
+    return f"""
+if [ -e {DOCKERENV_PATH} ]; then d=present; else d=absent; fi
+if [ -f {shim_path} ]; then s=present; else s=missing; fi
+c=$(base64 < {CGROUP_PATH} 2>/dev/null | tr -d '\\n')
+m=$(base64 < {MOUNTINFO_PATH} 2>/dev/null | tr -d '\\n')
+printf 'SKILLSENTRY_DOCKERENV=%s\\n' "$d"
+printf 'SKILLSENTRY_SHIM=%s\\n' "$s"
+printf 'SKILLSENTRY_CGROUP=%s\\n' "$c"
+printf 'SKILLSENTRY_MOUNTINFO=%s\\n' "$m"
+""".strip()
+
+
+def parse_verification_output(
+    text: str | bytes,
+    *,
+    require_shim: bool = True,
+) -> MasqueradeCheck:
+    if isinstance(text, bytes):
+        text = text.decode("utf-8", errors="replace")
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        if key.startswith("SKILLSENTRY_"):
+            values[key] = value.strip()
+    return verify_outputs(
+        dockerenv_exists=values.get("SKILLSENTRY_DOCKERENV") != "absent",
+        cgroup=_decode_b64(values.get("SKILLSENTRY_CGROUP", "")),
+        mountinfo=_decode_b64(values.get("SKILLSENTRY_MOUNTINFO", "")),
+        shim_present=values.get("SKILLSENTRY_SHIM") == "present",
+        require_shim=require_shim,
+    )
+
+
+def verify_container(
+    container: Any,
+    *,
+    config: MasqueradeConfig | None = None,
+    user: str = "65534:65534",
+) -> MasqueradeCheck:
+    """Run the verification probe in a started container."""
+
+    config = config or MasqueradeConfig()
+    result = container.exec_run(
+        ["/bin/sh", "-c", verification_script(config.shim_path)],
+        user=user,
+        environment=config.environment(),
+    )
+    if isinstance(result.output, bytes):
+        output = result.output.decode("utf-8", errors="replace")
+    else:
+        output = str(result.output or "")
+    if result.exit_code not in (0, None):
+        return MasqueradeCheck(
+            dockerenv_hidden=False,
+            cgroup_fake=False,
+            mountinfo_clean=False,
+            shim_present=False,
+            errors=(f"masquerade probe exited {result.exit_code}: {output.strip()}",),
+        )
+    return parse_verification_output(output, require_shim=config.require_shim)
+
+
+def require_masquerade(check: MasqueradeCheck) -> None:
+    if not check.ok:
+        raise MasqueradeError("; ".join(check.errors))