diff --git a/devcapsule-src/devcapsule/commands/github_ssh.py b/devcapsule-src/devcapsule/commands/github_ssh.py index e36fd1fc..443c0e90 100644 --- a/devcapsule-src/devcapsule/commands/github_ssh.py +++ b/devcapsule-src/devcapsule/commands/github_ssh.py @@ -23,8 +23,16 @@ class GitHubSshCommand(Command): def run(cls, arguments: argparse.Namespace, context: object | None) -> int: try: request = parse_git_ssh(arguments.ssh_arguments) - if request is None: + except GitHubTransportError as error: + raise CliError( + f"GitHub proxy: {error} Host keys must be trusted and encrypted keys unlocked on the host." + ) from error + if request is None: + try: return subprocess.run(["ssh", *arguments.ssh_arguments], check=False).returncode + except OSError as error: + raise CliError(f"Capsule SSH: {error}") from error + try: path = os.environ.get(SOCKET_ENV) if not path: raise GitHubTransportError("No authorized GitHub proxy. Enable github-ssh on the host launcher.") diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 0bfda896..7a3a2150 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -1236,7 +1236,7 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: class ConfigDenyCommand(Command): name = "deny" capsule_access: ClassVar[CapsuleAccess] = CapsuleAccess.MUTATES - help = "Deny a host access for this checkout, recorded: network, docker-daemon, development-sudo, host-browser, host-x11." + help = "Deny a host access for this checkout, recorded: network, docker-daemon, development-sudo, host-browser, host-x11, github-ssh." @classmethod def configure(cls, parser: argparse.ArgumentParser) -> None: diff --git a/devcapsule-src/devcapsule/configuration/review.py b/devcapsule-src/devcapsule/configuration/review.py index 0814e3e1..5ffac617 100644 --- a/devcapsule-src/devcapsule/configuration/review.py +++ b/devcapsule-src/devcapsule/configuration/review.py @@ -20,6 +20,8 @@ from .trust import HomeTrust from .values import RuntimeEffects, resolve_configuration_values +__all__ = ["HostAccess", "ConfigurationReview", "review_configuration"] + @dataclass(frozen=True) class HostAccess: diff --git a/devcapsule-src/devcapsule/github_proxy.py b/devcapsule-src/devcapsule/github_proxy.py index 83d2ba40..9939b28c 100644 --- a/devcapsule-src/devcapsule/github_proxy.py +++ b/devcapsule-src/devcapsule/github_proxy.py @@ -45,10 +45,6 @@ def _read_exact(connection: socket.socket, length: int) -> bytes: return bytes(chunks) -def _send_frame(connection: socket.socket, kind: bytes, payload: bytes) -> None: - connection.sendall(kind + struct.pack("!I", len(payload)) + payload) - - class GitHubBroker: """One session's GitHub bridge. Close cancels active children and removes its socket. diff --git a/devcapsule-src/devcapsule/launch/pycharm/_launcher.py b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py index 4be254ee..9df6045a 100644 --- a/devcapsule-src/devcapsule/launch/pycharm/_launcher.py +++ b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py @@ -729,6 +729,8 @@ def describe_run_command(command: list[str], config: PycharmRunConfig, ) if config.host_browser_socket is not None: comments.append("Host-browser socket requires a live broker; a broker owned by this invocation stops on return.") + if config.github_socket is not None: + comments.append("GitHub SSH socket requires a live broker; a broker owned by this invocation stops on return.") if config.display_transport == CONTAINED_DISPLAY_TRANSPORT: comments.append("Contained display needs its temporary token file; the chosen host port is not reserved for later use.") if config.console_host_port is not None: @@ -2329,7 +2331,11 @@ def print_storage_summary(config: PycharmRunConfig) -> None: Enabled through a URL-only HTTP(S) broker. Any process running as the capsule user can ask the physical host to navigate its default browser.""" if config.github_socket is not None: - host_browser_disclosure += "\n GitHub SSH: host-authenticated Git fetch/push proxy (all repositories your host identity can access)." + host_browser_disclosure += """ + +GitHub SSH integration: + Host-authenticated Git fetch/push proxy (all repositories your host identity + can access); private keys stay on the host.""" host_browser_disclosure += display_disclosure(config) + console_disclosure(config) if config.interactive_state_mounts: component_id = ( diff --git a/devcapsule-src/tests/integration/test_github_proxy.py b/devcapsule-src/tests/integration/test_github_proxy.py index c98f1c07..ed7dd727 100644 --- a/devcapsule-src/tests/integration/test_github_proxy.py +++ b/devcapsule-src/tests/integration/test_github_proxy.py @@ -8,13 +8,18 @@ from contextlib import contextmanager import os from pathlib import Path +import selectors import shlex +import shutil import socket +import stat import struct import subprocess import sys import tempfile +import time from collections.abc import Iterator +from typing import IO import pytest @@ -72,9 +77,11 @@ def test_real_git_clone_fetch_and_push_through_capsule_adapter(tmp_path: Path) - """Real Git clone, fetch and push transfer repository objects through the broker.""" env = _environment(tmp_path) bare = tmp_path / 'remote.git' - subprocess.run(['git', 'init', '--bare', '--initial-branch=main', str(bare)], env=env, check=True, capture_output=True) + git_bin = shutil.which('git') + assert git_bin is not None + subprocess.run([git_bin, 'init', '--bare', '--initial-branch=main', str(bare)], env=env, check=True, capture_output=True) # This stand-in uses only the validated service; the repository is fixed by the fixture. - program = f"import os, shlex, sys\nservice = shlex.split(sys.argv[-1])[0]\nos.execv('/usr/bin/git', ['git', service.removeprefix('git-'), {str(bare)!r}])\n" + program = f"import os, shlex, sys\nservice = shlex.split(sys.argv[-1])[0]\nos.execv({git_bin!r}, ['git', service.removeprefix('git-'), {str(bare)!r}])\n" with _broker(tmp_path, program) as (path, _): git_env = {**env, SOCKET_ENV: str(path), 'GIT_SSH_VARIANT': 'ssh', 'GIT_SSH_COMMAND': shlex.join([sys.executable, '-m', 'devcapsule', 'github-ssh', '--'])} @@ -118,12 +125,147 @@ def test_oversized_handshake_is_refused_without_reading_body(tmp_path: Path) -> assert connection.recv(1) == b'' +def _process_running(pid: int) -> bool: + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + # An orphaned grandchild cannot be waitpid'd by the broker and stays a + # zombie until PID 1 reaps it; treat 'Z' as terminated, not running. + try: + status = Path(f'/proc/{pid}/status').read_text(encoding='utf-8') + except OSError: + return False + for line in status.splitlines(): + if line.startswith('State:') and line.split(':', 1)[1].lstrip().startswith('Z'): + return False + return True + + +def _wait_pids_stopped(pids: list[int], timeout: float = 2.0) -> None: + deadline = time.monotonic() + timeout + remaining = list(pids) + while remaining and time.monotonic() < deadline: + remaining = [pid for pid in remaining if _process_running(pid)] + if remaining: + time.sleep(0.02) + assert not remaining, f"Processes still running after cleanup: {remaining}" + + +def _read_ready_line(stream: IO[bytes], expected: bytes, timeout: float = 5.0) -> None: + fd = stream.fileno() + received = bytearray() + deadline = time.monotonic() + timeout + with selectors.DefaultSelector() as selector: + selector.register(fd, selectors.EVENT_READ) + while len(received) < len(expected): + remaining = deadline - time.monotonic() + if remaining <= 0 or not selector.select(remaining): + raise TimeoutError( + f"Timed out waiting {timeout}s for ready signal {expected!r}; received {bytes(received)!r}" + ) + chunk = os.read(fd, len(expected) - len(received)) + if not chunk: + break + received.extend(chunk) + assert bytes(received) == expected + + def test_operation_deadline_stops_a_stalled_ssh_process(tmp_path: Path) -> None: - """A stalled host SSH process is killed and the capsule receives failure within the bound.""" - with _broker(tmp_path, 'import time\ntime.sleep(60)\n', operation_timeout=0.2) as (path, env): + """A stalled host SSH process and its descendant are terminated within the deadline (assumes fixture startup completes within 0.5s).""" + pid_file = tmp_path / 'pids' + program = ( + "import os, subprocess, sys, time\n" + "from pathlib import Path\n" + "grandchild = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)'])\n" + f"Path({str(pid_file)!r}).write_text(f'{{os.getpid()}}\\n{{grandchild.pid}}\\n')\n" + "time.sleep(60)\n" + ) + with _broker(tmp_path, program, operation_timeout=0.5) as (path, env): result = _client(path, env) assert result.returncode != 0 assert b'connection ended' in result.stderr + assert pid_file.exists(), "Fixture did not finish recording PIDs before the 0.5s operation deadline." + pids = [int(line) for line in pid_file.read_text().splitlines() if line] + assert len(pids) == 2 + _wait_pids_stopped(pids) + + +def test_broker_shutdown_cancels_active_ssh_process_group(tmp_path: Path) -> None: + """Closing the broker terminates an active host SSH transfer so no process in its group remains running.""" + started = tmp_path / 'started' + program = ( + "import os, subprocess, sys, time\n" + "from pathlib import Path\n" + "grandchild = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)'])\n" + f"Path({str(started)!r}).write_text(f'{{os.getpid()}}\\n{{grandchild.pid}}\\n')\n" + "sys.stdout.buffer.write(b'ready\\n')\n" + "sys.stdout.buffer.flush()\n" + "time.sleep(60)\n" + ) + client: subprocess.Popen[bytes] | None = None + try: + with _broker(tmp_path, program, operation_timeout=30) as (path, env): + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + client = subprocess.Popen( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + 'git@github.com', "git-upload-pack 'acme/repo.git'"], + env={**env, SOCKET_ENV: str(path)}, + stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + ) + assert client.stdout is not None + _read_ready_line(client.stdout, b'ready\n', timeout=5.0) + returncode = client.wait(timeout=5) + client.communicate(timeout=5) + assert returncode != 0 + finally: + if client is not None: + if client.poll() is None: + client.kill() + client.communicate(timeout=5) + for pipe in (client.stdin, client.stdout, client.stderr): + if pipe is not None and not pipe.closed: + pipe.close() + pids = [int(line) for line in started.read_text().splitlines() if line] + assert len(pids) == 2 + _wait_pids_stopped(pids) + + +def test_capsule_adapter_refuses_when_proxy_is_not_authorized(tmp_path: Path) -> None: + """Without an authorized proxy socket in the environment, GitHub SSH fails rather than running SSH.""" + result = subprocess.run( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + 'git@github.com', "git-upload-pack 'acme/repo.git'"], + env=_environment(tmp_path), + input=b'', capture_output=True, timeout=15, + ) + assert result.returncode != 0 + assert b'No authorized GitHub proxy' in result.stderr + + +def test_capsule_adapter_falls_back_to_capsule_ssh_for_other_hosts(tmp_path: Path) -> None: + """Non-GitHub destinations execute the capsule's own ssh binary without touching the proxy.""" + bin_dir = tmp_path / 'bin' + bin_dir.mkdir() + ssh_stub = bin_dir / 'ssh' + args_file = tmp_path / 'ssh_args' + ssh_stub.write_text( + f"#!{sys.executable}\n" + "import json, sys\n" + "from pathlib import Path\n" + f"Path({str(args_file)!r}).write_text(json.dumps(sys.argv[1:]))\n" + "sys.exit(4)\n" + ) + ssh_stub.chmod(0o700) + env = _environment(tmp_path) + env['PATH'] = f"{bin_dir}:{env['PATH']}" + result = subprocess.run( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + '-p', '2222', 'git@example.test', "git-upload-pack 'acme/repo.git'"], + env=env, input=b'', capture_output=True, timeout=15, + ) + assert result.returncode == 4 + assert args_file.read_text() == '["-p", "2222", "git@example.test", "git-upload-pack \'acme/repo.git\'"]' def test_broker_shutdown_closes_incomplete_requests(tmp_path: Path) -> None: @@ -161,3 +303,23 @@ def test_launcher_exposes_the_socket_only_with_the_grant(tmp_path: Path, enabled assert (f'type=bind,src={path},dst={SOCKET_DESTINATION},ro' in args) is enabled assert args[args.index('--user') + 1] == ('0:0' if rootless else f'{os.getuid()}:{os.getgid()}') assert not any('.ssh' in arg or 'SSH_AUTH_SOCK=' in arg for arg in args) + + +def test_launcher_rejects_environment_conflicts_with_github_ssh(tmp_path: Path) -> None: + """Additional environment cannot override GitHub SSH transport variables when enabled.""" + from devcapsule.launch.pycharm._launcher import PycharmRunError, PycharmRunOptions, DockerMode, build_run_config + from devcapsule.platforms import Platform + + project = tmp_path / 'project' + project.mkdir() + with _broker(tmp_path, 'raise AssertionError("no transfer expected")\n') as (path, env): + env = {**env, 'DISPLAY': ':1', 'PYCHARM_GIT_IDENTITY_FROM_HOST': '0', SOCKET_ENV: str(path)} + with pytest.raises(PycharmRunError, match="GitHub SSH"): + build_run_config( + PycharmRunOptions( + project=project, capsule_platform=Platform.LINUX_AMD64, + docker_mode=DockerMode.none, enable_sudo=False, network_mode='bridge', + enable_github_ssh=True, additional_environment={'GIT_SSH_COMMAND': 'ssh'}, + ), + env, + ) diff --git a/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py b/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py new file mode 100644 index 00000000..a38d868d --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py @@ -0,0 +1,42 @@ +"""Unit tests of ``devcapsule.github_proxy``: pure gating decisions of ``github_ssh_bridge``. + +No sockets are bound and no subprocesses start; every outcome follows from the +explicit arguments passed to ``github_ssh_bridge``. +""" +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.github_proxy import SOCKET_DESTINATION, SOCKET_ENV, github_ssh_bridge +from devcapsule.github_transport import GitHubTransportError + + +def test_disabled_bridge_yields_none_regardless_of_host_capabilities() -> None: + """When github-ssh is denied, the bridge yields no socket even on unsupported or containerized hosts.""" + with github_ssh_bridge({}, enabled=False, containerized=True, binds_unix_sockets=False) as path: + assert path is None + + +def test_docker_desktop_bridge_is_refused_when_enabled() -> None: + """Enabling github-ssh on a host that cannot bind Unix sockets fails loudly instead of degrading.""" + with pytest.raises(GitHubTransportError, match="Docker Desktop"): + with github_ssh_bridge({}, enabled=True, containerized=False, binds_unix_sockets=False): + pass + + +@pytest.mark.parametrize("environment", [{}, {SOCKET_ENV: "/tmp/forged.sock"}]) +def test_containerized_bridge_requires_an_inherited_canonical_socket(environment: dict[str, str]) -> None: + """An inner capsule cannot enable github-ssh without the launcher's canonical socket variable.""" + assert str(SOCKET_DESTINATION) != "/tmp/forged.sock" + with pytest.raises(GitHubTransportError, match="outside launcher"): + with github_ssh_bridge(environment, enabled=True, containerized=True, binds_unix_sockets=True): + pass + + +def test_host_bridge_requires_openssh_on_path(tmp_path: Path) -> None: + """Enabling github-ssh on the host fails clearly when OpenSSH is absent from an empty PATH directory.""" + with pytest.raises(GitHubTransportError, match="OpenSSH"): + with github_ssh_bridge({"PATH": str(tmp_path)}, enabled=True, containerized=False, binds_unix_sockets=True): + pass diff --git a/devcapsule-src/tests/unit/devcapsule/test_github_transport.py b/devcapsule-src/tests/unit/devcapsule/test_github_transport.py index 695e8997..30560161 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_github_transport.py +++ b/devcapsule-src/tests/unit/devcapsule/test_github_transport.py @@ -6,12 +6,15 @@ from devcapsule.github_transport import GitHubRequest, GitHubTransportError, decode_request, parse_git_ssh -@pytest.mark.parametrize('command,service', [("git-upload-pack 'acme/widgets.git'", 'git-upload-pack'), - ("git-receive-pack '/acme/widgets'", 'git-receive-pack')]) -def test_git_arguments_select_only_the_service_and_repository(command: str, service: str) -> None: - """Git's destination and v2 request admit a GitHub transfer with no SSH option forwarding.""" - request = parse_git_ssh(['-o', 'SendEnv=GIT_PROTOCOL', 'git@github.com', command]) - assert request == GitHubRequest(service, 'acme/widgets.git' if service == 'git-upload-pack' else 'acme/widgets') +@pytest.mark.parametrize('arguments,expected', [ + (['-o', 'SendEnv=GIT_PROTOCOL', 'git@github.com', "git-upload-pack 'acme/widgets.git'"], + GitHubRequest('git-upload-pack', 'acme/widgets.git')), + (['-oSendEnv=GIT_PROTOCOL', '-p', '22', 'github.com', "git-receive-pack '/acme/widgets'"], + GitHubRequest('git-receive-pack', 'acme/widgets')), +]) +def test_git_arguments_select_only_the_service_and_repository(arguments: list[str], expected: GitHubRequest) -> None: + """Git's destination, standard port 22, and v2 request admit a GitHub transfer with no SSH option forwarding.""" + assert parse_git_ssh(arguments) == expected @pytest.mark.parametrize('command', ["sh 'acme/repo'", "git-upload-pack 'acme/repo'; id", "git-upload-pack 'a/../b'", @@ -33,9 +36,13 @@ def test_capsule_ssh_options_cannot_change_host_execution(arguments: list[str]) parse_git_ssh(arguments) -def test_other_git_hosts_are_not_forwarded_to_the_host() -> None: - """A different destination selects the capsule's ordinary SSH fallback.""" - assert parse_git_ssh(['git@example.test', "git-upload-pack 'acme/repo'"]) is None +@pytest.mark.parametrize('arguments', [ + ['git@example.test', "git-upload-pack 'acme/repo'"], + ['-p', '2222', 'git@example.test', "git-upload-pack 'acme/repo'"], +]) +def test_other_git_hosts_are_not_forwarded_to_the_host(arguments: list[str]) -> None: + """A different destination, including with a custom port, selects the capsule's ordinary SSH fallback.""" + assert parse_git_ssh(arguments) is None @pytest.mark.parametrize('document', [{}, {'version': True, 'service': 'git-upload-pack', 'repository': 'a/b'}, @@ -62,6 +69,18 @@ def test_host_command_keeps_verification_and_disables_forwarding() -> None: assert '-oControlPath=none' in command +@pytest.mark.parametrize('payload', [ + b'{', + b'\xff', + b'[]', + json.dumps({'version': 1, 'service': 'git-upload-pack', 'repository': 'a/' + 'b' * 255}).encode(), +]) +def test_wire_validation_rejects_malformed_and_oversized_repository_payloads(payload: bytes) -> None: + """Malformed JSON, non-object frames and overlong repository paths are refused on the wire.""" + with pytest.raises(GitHubTransportError): + decode_request(payload) + + def test_valid_wire_request_roundtrips() -> None: """Encoding a valid request carries exactly the service and repository contract.""" request = GitHubRequest('git-receive-pack', 'acme/widgets.git')