ixt-cli 0.8.0__py3-none-any.whl

ixt/config/env_policy.py

@@ -0,0 +1,340 @@
+"""Per-tool environment variable policy."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import stat
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ixt.config.models import ToolRecord
+
+# Public names of the env vars the shim and CLI honour. Single source
+# of truth — referenced from tests, docs, and the warning text below.
+ENV_POLICY_QUIET = "IXT_POLICY_QUIET"
+ENV_DISABLE_BWRAP = "IXT_DISABLE_BWRAP"
+
+# Lines printed when env policy is active without bwrap, both at config
+# time (CLI) and at runtime (shim, throttled by a per-session marker
+# file). Kept as data so the two emitters stay in sync verbatim.
+DEGRADED_WARNING_LINES: list[str] = [
+    f"Warning: env policy active without bubblewrap (set {ENV_POLICY_QUIET}=1 to silence).",
+    "  Effective protection: hygiene only (logs, traces, naive telemetry).",
+    "  Active threats NOT blocked: /proc/$PPID/environ, /proc/*/environ",
+    "  reads, secret files (~/.aws, ~/.netrc, ~/.ssh, ...).",
+    "",
+    "  Install bubblewrap for effective protection:",
+    "    sudo apt install bubblewrap   # Debian/Ubuntu",
+    "    sudo dnf install bubblewrap   # Fedora/RHEL",
+]
+
+ENV_MODELS: dict[str, list[str]] = {
+    "os-common": [
+        "HOME",
+        "PATH",
+        "XDG_*",
+        "NO_COLOR",
+        "FORCE_COLOR",
+        "TERM",
+        "COLORTERM",
+        "LANG",
+        "LC_*",
+        "USER",
+        "LOGNAME",
+        "TMPDIR",
+        "SHELL",
+        "TZ",
+    ],
+}
+
+
+def _matches(name: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(name, p) for p in patterns)
+
+
+def _is_denied(name: str, deny: dict[str, dict]) -> bool:
+    for pattern, rule in deny.items():
+        exceptions: list[str] = rule.get("except", [])
+        if fnmatch.fnmatch(name, pattern) and not _matches(name, exceptions):
+            return True
+    return False
+
+
+def compute_env(
+    environ: dict[str, str],
+    base: str,
+    allow: list[str],
+    deny: dict[str, dict],
+) -> dict[str, str]:
+    """Return the filtered env dict for a tool invocation."""
+    if base == "all":
+        result = dict(environ)
+    elif base == "none":
+        result = {}
+    else:
+        model_patterns = ENV_MODELS.get(base, [])
+        result = {k: v for k, v in environ.items() if _matches(k, model_patterns)}
+
+    result.update({k: v for k, v in environ.items() if _matches(k, allow)})
+    result = {k: v for k, v in result.items() if not _is_denied(k, deny)}
+    return result
+
+
+def has_env_policy(record: ToolRecord) -> bool:
+    return record.env_base != "all" or bool(record.env_allow) or bool(record.env_deny)
+
+
+_SHIM_TEMPLATE = """\
+#!/usr/bin/env python3
+# ixt shim: {name}
+import fnmatch as _f, os as _os, shutil as _sh, sys as _sys
+
+_HERE = _os.path.dirname(_os.path.abspath(__file__))
+
+
+def _abs(p):
+    return p if _os.path.isabs(p) else _os.path.abspath(_os.path.join(_HERE, p))
+
+
+_R = _abs({real!r})
+_ED = _abs({env_dir!r})
+_B = {base!r}
+_A = {allow!r}
+_D = {deny!r}
+_M = {model!r}
+_FB = {fs_base!r}
+_FRO = {fs_ro!r}
+_FRW = {fs_rw!r}
+_FSC = {fs_scratch!r}
+
+# Read opt-out flags BEFORE any env filtering — they must work even with
+# a strict env policy that would otherwise drop them.
+_QUIET = bool(_os.environ.get({quiet_var!r}))
+_DISABLE_BWRAP = bool(_os.environ.get({disable_bwrap_var!r}))
+_WARNING_LINES = {warning_lines!r}
+
+
+def _m(n, ps):
+    return any(_f.fnmatch(n, p) for p in ps)
+
+
+_src = _os.environ
+if _B == "all":
+    _e = dict(_src)
+elif _B == "none":
+    _e = {{}}
+else:
+    _e = {{k: v for k, v in _src.items() if _m(k, _M)}}
+_e.update({{k: v for k, v in _src.items() if _m(k, _A)}})
+
+
+def _denied(n, d):
+    for pat, rule in d.items():
+        excs = rule.get("except", [])
+        if _f.fnmatch(n, pat) and not any(_f.fnmatch(n, e) for e in excs):
+            return True
+    return False
+
+
+_e = {{k: v for k, v in _e.items() if not _denied(k, _D)}}
+
+if _os.environ.get("IXT_SHIM_DEBUG") or _os.environ.get("IXT_SHIM_VERBOSE"):
+    _bl = {{k for k in _src if k not in _e}}
+    _n = {name!r}
+    print(f"[ixt shim: {{_n}}] env base={{_B!r}} allow={{_A}} deny={{_D}}", file=_sys.stderr)
+    _passed = ' '.join(sorted(_e))
+    print(f"[ixt shim: {{_n}}] env passed ({{len(_e)}} vars): {{_passed}}", file=_sys.stderr)
+    if _bl:
+        _blocked = ' '.join(sorted(_bl))
+        print(f"[ixt shim: {{_n}}] env blocked ({{len(_bl)}} vars): {{_blocked}}", file=_sys.stderr)
+    if _FB != "all":
+        _fs = f"ro={{_FRO}} rw={{_FRW}} scratch={{_FSC}}"
+        print(f"[ixt shim: {{_n}}] fs base={{_FB!r}} {{_fs}}", file=_sys.stderr)
+
+def _warn_degraded_runtime():
+    if _QUIET:
+        return
+    _state = _os.environ.get("XDG_STATE_HOME") or _os.path.expanduser("~/.local/state")
+    _marker_dir = _os.path.join(_state, "ixt")
+    try:
+        _sid = _os.getsid(0)
+    except OSError:
+        _sid = _os.getpid()  # rare fallback (no controlling tty)
+    _marker = _os.path.join(_marker_dir, "policy-warned-" + str(_sid))
+    if _os.path.exists(_marker):
+        return
+    for _line in _WARNING_LINES:
+        print("[ixt] " + _line if _line else "[ixt]", file=_sys.stderr)
+    try:
+        _os.makedirs(_marker_dir, exist_ok=True)
+        with open(_marker, "w"):
+            pass
+    except OSError:
+        pass
+
+
+_has_env = _B != "all" or _A or _D
+_has_fs = _FB != "all" or _FRO or _FRW or _FSC
+_bw = None if _DISABLE_BWRAP else _sh.which("bwrap")
+
+if (_has_env or _has_fs) and _bw:
+    # Sandbox path. Defense in depth: pass _e (filtered) to execve, not
+    # os.environ — so the bwrap process itself starts with the filtered
+    # env, and any /proc/<bwrap>/environ would also be clean.
+
+    # fs_base="none" with no extras → sandbox would be empty, bwrap can't
+    # exec the tool. Fail with a clear message.
+    if _FB == "none" and not _FRO and not _FRW and not _FSC:
+        print(
+            "[ixt] fs_base='none' requires at least one path via 'fs ro/rw/scratch'"
+            " — the sandbox would be empty.",
+            file=_sys.stderr,
+        )
+        print(
+            "[ixt]   Use 'ixt tool config <target> fs base app-minimal' for a sane default,",
+            file=_sys.stderr,
+        )
+        print(
+            "[ixt]   or 'ixt tool config <target> fs ro /usr/lib /lib /lib64 /usr/bin'"
+            " to build it manually.",
+            file=_sys.stderr,
+        )
+        _sys.exit(1)
+
+    _cwd = _os.getcwd()
+    # Sandbox constant — PID isolation + private /proc + die-with-parent.
+    # Applied for every code path that uses bwrap (fs preset OR env-only).
+    _ba = [_bw, "--unshare-pid", "--as-pid-1",
+           "--proc", "/proc",
+           "--die-with-parent"]
+    if _FB == "app-common":
+        # Almost-full host visibility, but tmpfs /tmp + ro-bind env_dir on
+        # top so the tool's own binary stays reachable when env_dir lives
+        # under /tmp (tempfile-based test setups, ephemeral CI runners).
+        _ba += ["--ro-bind", "/", "/",
+                "--bind", _cwd, _cwd,
+                "--tmpfs", "/tmp",
+                "--ro-bind", _ED, _ED,
+                "--dev", "/dev"]
+    elif _FB == "app-minimal":
+        # Strict minimum: env_dir + system libs + dynamic linker config.
+        # No $HOME, no cwd, no /etc complete, no /tmp, no /usr/bin.
+        # --ro-bind-try silently skips paths that don't exist on this host
+        # (e.g. /lib64 absent on pure-multilib distros) — saves stat() per
+        # invocation and keeps the option list static.
+        _ba += ["--ro-bind", _ED, _ED,
+                "--ro-bind-try", "/usr/lib", "/usr/lib",
+                "--ro-bind-try", "/usr/lib32", "/usr/lib32",
+                "--ro-bind-try", "/usr/lib64", "/usr/lib64",
+                "--ro-bind-try", "/lib", "/lib",
+                "--ro-bind-try", "/lib64", "/lib64",
+                "--ro-bind-try", "/etc/ld.so.cache", "/etc/ld.so.cache",
+                "--ro-bind-try", "/etc/ld.so.conf", "/etc/ld.so.conf",
+                "--ro-bind-try", "/etc/ld.so.conf.d", "/etc/ld.so.conf.d",
+                "--dev-bind", "/dev/null", "/dev/null",
+                "--dev-bind", "/dev/urandom", "/dev/urandom"]
+    elif _FB == "all":
+        # env-only via bwrap: full host fs visible (rw). The user opted
+        # in to env policy only; we add a sandbox just to close /proc
+        # leaks, not to restrict filesystem access.
+        _ba += ["--bind", "/", "/",
+                "--dev", "/dev"]
+    # _FB == "none" → expert mode: only the user-listed binds below.
+    for _p in _FRO:
+        _ap = _os.path.abspath(_os.path.expanduser(_p))
+        _ba += ["--ro-bind", _ap, _ap]
+    for _p in _FRW:
+        _ap = _os.path.abspath(_os.path.expanduser(_p))
+        _ba += ["--bind", _ap, _ap]
+    for _p in _FSC:
+        _ap = _os.path.abspath(_os.path.expanduser(_p))
+        _ba += ["--tmpfs", _ap]
+    _ba += ["--clearenv"]
+    for _k, _v in _e.items():
+        _ba += ["--setenv", _k, _v]
+    _ba += ["--", _R] + _sys.argv[1:]
+    _os.execve(_bw, _ba, _e)
+elif _has_fs:
+    # fs policy was requested but bwrap is unavailable — fs cannot be
+    # enforced without it. Fail hard with install instructions.
+    print("[ixt] bwrap not found — install bubblewrap to use filesystem isolation",
+          file=_sys.stderr)
+    print("[ixt]   Ubuntu/Debian:  sudo apt install bubblewrap", file=_sys.stderr)
+    print("[ixt]   Fedora/RHEL:    sudo dnf install bubblewrap", file=_sys.stderr)
+    print("[ixt]   Arch:           sudo pacman -S bubblewrap", file=_sys.stderr)
+    print("[ixt]   Alpine:         sudo apk add bubblewrap", file=_sys.stderr)
+    _sys.exit(1)
+elif _has_env:
+    # env-only without bwrap (or with IXT_DISABLE_BWRAP). The filtered
+    # env reaches the tool via execve, but /proc-based exfiltration is
+    # not blocked. Warn once per shell session.
+    _warn_degraded_runtime()
+    _os.execve(_R, [_R, *_sys.argv[1:]], _e)
+else:
+    # No policy → shouldn't reach the shim (a symlink would handle this).
+    # Fallback for safety.
+    _os.execve(_R, [_R, *_sys.argv[1:]], _e)
+"""
+
+
+def _path_from_shim_dir(path: str, shim_dir: Path | None) -> str:
+    if shim_dir is None:
+        return path
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        return path
+    return os.path.relpath(candidate, shim_dir)
+
+
+def generate_shim(
+    name: str,
+    real_path: str,
+    record: ToolRecord,
+    *,
+    shim_dir: Path | None = None,
+) -> str:
+    return _SHIM_TEMPLATE.format(
+        name=name,
+        real=_path_from_shim_dir(real_path, shim_dir),
+        env_dir=_path_from_shim_dir(record.env_dir, shim_dir),
+        base=record.env_base,
+        allow=record.env_allow,
+        deny=record.env_deny,
+        model=ENV_MODELS.get(record.env_base, []),
+        fs_base=record.fs_base,
+        fs_ro=record.fs_ro,
+        fs_rw=record.fs_rw,
+        fs_scratch=record.fs_scratch,
+        quiet_var=ENV_POLICY_QUIET,
+        disable_bwrap_var=ENV_DISABLE_BWRAP,
+        warning_lines=DEGRADED_WARNING_LINES,
+    )
+
+
+def _needs_wrapper(record: ToolRecord) -> bool:
+    from ixt.config.fs_policy import has_fs_policy
+
+    return has_env_policy(record) or has_fs_policy(record)
+
+
+def apply_policy(record: ToolRecord, bin_dir: Path) -> None:
+    """Replace symlinks with wrappers (or back) for all exposed bins of *record*."""
+    use_wrapper = _needs_wrapper(record)
+    for exposed_name, real_path in record.exposed_bins.items():
+        target = bin_dir / exposed_name
+        if target.exists() or target.is_symlink():
+            target.unlink()
+        if use_wrapper:
+            source = generate_shim(exposed_name, real_path, record, shim_dir=bin_dir)
+            target.write_text(source, encoding="utf-8")
+            target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        else:
+            source_path = Path(real_path)
+            link_source = (
+                os.path.relpath(source_path, target.parent)
+                if source_path.is_absolute()
+                else real_path
+            )
+            os.symlink(link_source, target)

ixt/config/flags.py

@@ -0,0 +1,29 @@
+"""Feature flags for experimental or gated functionality.
+
+Flags are opt-in via environment variables and default to OFF. They let
+us ship code paths that are complete but lack full E2E validation yet,
+without advertising them as stable.
+"""
+
+from __future__ import annotations
+
+import os
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+SETUP_TOML_ENV = "IXT_ENABLE_SETUP_TOML"
+
+
+def _is_env_flag_on(name: str) -> bool:
+    value = os.environ.get(name, "").strip().lower()
+    return value in _TRUE_VALUES
+
+
+def is_setup_toml_enabled() -> bool:
+    """Whether ``ixt.setup.toml`` support (tool-author contract) is active.
+
+    OFF by default in v0.1.0 — the feature is implemented and unit-tested
+    but lacks E2E coverage for hook execution. Set ``SETUP_TOML_ENV=1``
+    to enable both remote fetch and the ``--setup-file`` CLI flag.
+    """
+    return _is_env_flag_on(SETUP_TOML_ENV)

ixt/config/fs_policy.py

@@ -0,0 +1,17 @@
+"""Per-tool filesystem policy (bwrap-based)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ixt.config.models import ToolRecord
+
+
+def has_fs_policy(record: ToolRecord) -> bool:
+    return (
+        record.fs_base != "all"
+        or bool(record.fs_ro)
+        or bool(record.fs_rw)
+        or bool(record.fs_scratch)
+    )