💫 Toolkit to help you get started with SDD or any other process!
fix: confine event hook script paths to the project tree (#4133)
Sebastien Tardifae6033384f56
diff --git a/src/specify_cli/events.py b/src/specify_cli/events.pyindex dafd29bed..83da04d4f 100644--- a/src/specify_cli/events.py+++ b/src/specify_cli/events.py@@ -17,7 +17,7 @@ import shutilimport sysimport subprocessimport platform-from pathlib import Path+from pathlib import Path, PurePosixPath, PureWindowsPathfrom typing import TYPE_CHECKING, Anyimport yaml@@ -30,6 +30,11 @@ logger = logging.getLogger(__name__)# -- Constants -------------------------------------------------------------+# Generated hook dispatchers refuse to delegate unless this name is True.+# An older installed specify_cli.events (uvx-init plus a stale global+# install) would otherwise run unconfined script tokens.+EVENT_SCRIPT_PATH_CONFINEMENT = True+EVENTS_DISPATCHER_DIR = Path(".specify")EVENTS_DISPATCHER_FILENAME = "events.py"# POSIX-form (forward-slash) relative path so it matches manifest keys, which@@ -83,7 +88,22 @@ import shleximport shutilimport subprocessimport sys-from pathlib import Path+from pathlib import Path, PurePosixPath, PureWindowsPath+++def _script_under_base(base, token, project_root):+ """Return token resolved under base, or None if it leaves the project."""+ posix_path = PurePosixPath(token)+ win_path = PureWindowsPath(token)+ if posix_path.anchor or win_path.anchor:+ return None+ try:+ root = project_root.resolve()+ candidate = (base / token).resolve()+ candidate.relative_to(root)+ except (OSError, ValueError):+ return None+ return candidatedef _find_command_template(command_name, project_root):@@ -228,8 +248,8 @@ def _resolve_argv(template_path, project_root, ext_id):return Noneif not tokens:return None- script_abs = base / tokens[0]- if not script_abs.exists():+ script_abs = _script_under_base(base, tokens[0], project_root)+ if script_abs is None or not script_abs.exists():return Nonerest = tokens[1:]@@ -361,8 +381,15 @@ def main():# Preferred path: specify_cli is importable (durable install) — delegate to# the full resolver, which also handles extension manifests whose file stem# differs from the command name and the project's custom script selection.+ # Require EVENT_SCRIPT_PATH_CONFINEMENT so a stale global install cannot+ # bypass the generated dispatcher's path guard.try:- from specify_cli.events import resolve_and_run_event_command+ from specify_cli.events import (+ EVENT_SCRIPT_PATH_CONFINEMENT as _confine_ok,+ resolve_and_run_event_command,+ )+ if _confine_ok is not True:+ raise ImportError("specify_cli.events lacks script path confinement")sys.exit(resolve_and_run_event_command(command_name, _event_name, payload, project_root, timeout=timeout, envelope=envelope, native_event=native_event@@ -541,6 +568,30 @@ def _find_command_template(command_name: str, project_root: Path) -> tuple[Pathreturn None, None+def _confine_event_script_path(+ project_root: Path, base: Path, token: str+) -> Path | None:+ """Resolve *token* under *base*, or None if it leaves the project.++ Rejects anchored tokens (absolute, drive, UNC) so ``Path`` cannot+ discard *base*. ``..`` is allowed when the resolved path stays inside+ *project_root*, which is how extension templates reach core scripts+ via ``../../scripts/...``. Keep the generated ``_script_under_base``+ in sync.+ """+ posix_path = PurePosixPath(token)+ win_path = PureWindowsPath(token)+ if posix_path.anchor or win_path.anchor:+ return None+ try:+ root = project_root.resolve()+ candidate = (base / token).resolve()+ candidate.relative_to(root)+ except (OSError, ValueError):+ return None+ return candidate++def _resolve_event_command_argv(template_path: Path, project_root: Path, ext_id: str | None) -> list[str] | None:@@ -609,8 +660,8 @@ def _resolve_event_command_argv(return Noneif not tokens:return None- script_abs = base / tokens[0]- if not script_abs.exists():+ script_abs = _confine_event_script_path(project_root, base, tokens[0])+ if script_abs is None or not script_abs.exists():return Nonerest_args = tokens[1:]diff --git a/tests/integrations/test_events.py b/tests/integrations/test_events.pyindex 5dfc497b9..f74aeaaa3 100644--- a/tests/integrations/test_events.py+++ b/tests/integrations/test_events.py@@ -1388,8 +1388,10 @@ class TestCommandRunner:{"pre_tool_use": [{"command": "speckit.tdd.validate"}]},)content = (tmp_path / EVENTS_DISPATCHER_REL).read_text()- # Delegates to specify_cli when importable.- assert "from specify_cli.events import resolve_and_run_event_command" in content+ # Delegates to specify_cli when importable and confinement is present.+ assert "EVENT_SCRIPT_PATH_CONFINEMENT" in content+ assert "from specify_cli.events import" in content+ assert "resolve_and_run_event_command" in contentassert "except (ImportError, TypeError):" in content# Inline stdlib fallback resolver for one-time/temporary installs.assert "_run_inline" in content@@ -1454,6 +1456,53 @@ class TestCommandRunner:assert out_file.exists(), f"inline fallback did not run script; stderr={result.stderr!r} rc={result.returncode}"assert out_file.read_text() == '{"tool_name":"x"}'+ def test_dispatcher_ignores_stale_specify_cli_without_confinement(self, tmp_path):+ """A generated dispatcher must not delegate to an older specify_cli+ that lacks EVENT_SCRIPT_PATH_CONFINEMENT (uvx-init plus stale+ global install). Absolute script tokens stay rejected."""+ import subprocess as _sp+ import sys as _sys++ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ dispatcher = tmp_path / EVENTS_DISPATCHER_REL+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ ran = tmp_path / "stale-ran"+ (cmd_dir / "boot.md").write_text(+ "---\ndescription: \"Boot\"\nscripts:\n sh: /tmp/outside.sh\n---\nBody\n",+ encoding="utf-8",+ )++ fake_dir = tmp_path / "_stale_pkg"+ pkg = fake_dir / "specify_cli"+ pkg.mkdir(parents=True)+ (pkg / "__init__.py").write_text("", encoding="utf-8")+ (pkg / "events.py").write_text(+ "def resolve_and_run_event_command(*_a, **_k):\n"+ f" open({str(ran)!r}, 'w').write('delegated')\n"+ " return 0\n",+ encoding="utf-8",+ )+ env = dict(os.environ)+ env["PYTHONPATH"] = str(fake_dir)+ result = _sp.run(+ [_sys.executable, str(dispatcher), "speckit.boot", "session_start", "60"],+ input="{}",+ capture_output=True,+ text=True,+ env=env,+ cwd=str(tmp_path),+ )+ assert not ran.exists(), f"stale package ran; stderr={result.stderr!r}"+def test_dispatcher_threads_per_handler_timeout(self, tmp_path):"""S4: the generated dispatcher reads an optional 4th timeout arg anduses it for the inner subprocess, instead of a fixed 120s cap that@@ -1522,6 +1571,173 @@ class TestCommandRunner:else:assert PurePath(argv[0]).as_posix().endswith(".specify/scripts/bash/boot.sh")+ def test_absolute_script_token_returns_none(self, tmp_path):+ """An absolute first ``scripts:`` token must not run a host binary."""+ from specify_cli.events import _resolve_event_command_argv++ outside = tmp_path.parent / "outside-event-script.sh"+ outside.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ f"scripts:\n sh: {outside.as_posix()}\n"+ "---\nBody\n",+ encoding="utf-8",+ )++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)++ assert argv is None++ def test_dotdot_script_token_outside_project_returns_none(self, tmp_path):+ """A ``..`` walk out of the project root must not resolve."""+ from specify_cli.events import _resolve_event_command_argv++ outside = tmp_path.parent / "outside-event-script.sh"+ outside.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n sh: ../../outside-event-script.sh\n"+ "---\nBody\n",+ encoding="utf-8",+ )++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)++ assert argv is None++ def test_extension_dotdot_to_core_scripts_resolves(self, tmp_path):+ """Extension templates may reach core scripts via ``../../scripts/...``."""+ from specify_cli.events import _resolve_event_command_argv++ ext_id = "my-ext"+ cmd_dir = tmp_path / ".specify" / "extensions" / ext_id / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n sh: ../../scripts/bash/helper.sh\n"+ "---\nBody\n",+ encoding="utf-8",+ )+ helper_dir = tmp_path / ".specify" / "scripts" / "bash"+ helper_dir.mkdir(parents=True)+ (helper_dir / "helper.sh").write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, ext_id)++ assert argv is not None+ script_arg = argv[1] if platform.system().lower().startswith("win") else argv[0]+ assert PurePath(script_arg).as_posix().endswith(".specify/scripts/bash/helper.sh")++ def test_symlink_escape_returns_none(self, tmp_path):+ """A relative token that resolves through a symlink out of the project+ must not run the host target."""+ from specify_cli.events import _resolve_event_command_argv++ host = tmp_path.parent / "host-event-script.sh"+ host.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")+ script_dir = tmp_path / ".specify" / "scripts"+ script_dir.mkdir(parents=True)+ sneak = script_dir / "sneak.sh"+ try:+ sneak.symlink_to(host)+ except OSError:+ pytest.skip("symlinks are not available")+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n sh: scripts/sneak.sh\n"+ "---\nBody\n",+ encoding="utf-8",+ )++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)++ assert argv is None++ def test_windows_drive_script_token_returns_none(self, tmp_path):+ """A Windows-anchored first token must not discard the project base."""+ from specify_cli.events import _resolve_event_command_argv++ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n sh: C:/Windows/System32/cmd.exe\n"+ "---\nBody\n",+ encoding="utf-8",+ )++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)++ assert argv is None++ def test_dispatcher_template_confines_script_token(self):+ """The stdlib fallback dispatcher must carry the same confinement."""+ from specify_cli.events import _EVENTS_DISPATCHER_TEMPLATE++ assert "_script_under_base" in _EVENTS_DISPATCHER_TEMPLATE+ assert "PureWindowsPath" in _EVENTS_DISPATCHER_TEMPLATE++ def test_dispatcher_inline_rejects_absolute_script(self, tmp_path):+ """Inline fallback must not execute an absolute first ``scripts:`` token."""+ import subprocess as _sp+ import sys as _sys++ if platform.system().lower().startswith("win"):+ return++ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ dispatcher = tmp_path / EVENTS_DISPATCHER_REL+ marker = tmp_path / "should-not-run.out"+ host = tmp_path.parent / "host-boot.sh"+ host.write_text(+ f"#!/bin/sh\necho ran > {shlex.quote(str(marker))}\nexit 0\n",+ encoding="utf-8",+ )+ host.chmod(0o755)+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ f"scripts:\n sh: {host.as_posix()}\n"+ "---\nBody\n",+ encoding="utf-8",+ )+ fake_dir = tmp_path / "_fake"+ (fake_dir / "specify_cli").mkdir(parents=True)+ (fake_dir / "specify_cli" / "__init__.py").write_text("", encoding="utf-8")+ env = dict(os.environ)+ env["PYTHONPATH"] = str(fake_dir)+ result = _sp.run(+ [_sys.executable, str(dispatcher), "speckit.boot", "session_start", "60"],+ input="{}",+ capture_output=True,+ text=True,+ env=env,+ cwd=str(tmp_path),+ )+ assert result.returncode == 0, result.stderr+ assert not marker.exists()+# -- Merge/teardown idempotency & safety (Tier 3) ----------------------------