Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion devcapsule-src/devcapsule/commands/github_ssh.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.")
Expand Down
2 changes: 1 addition & 1 deletion devcapsule-src/devcapsule/commands/project.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions devcapsule-src/devcapsule/configuration/review.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 0 additions & 4 deletions devcapsule-src/devcapsule/github_proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
8 changes: 7 additions & 1 deletion devcapsule-src/devcapsule/launch/pycharm/_launcher.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 = (
Expand Down
170 changes: 166 additions & 4 deletions devcapsule-src/tests/integration/test_github_proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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', '--'])}
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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,
)
42 changes: 42 additions & 0 deletions devcapsule-src/tests/unit/devcapsule/test_github_proxy.py
Original file line number Diff line number Diff line change
@@ -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
37 changes: 28 additions & 9 deletions devcapsule-src/tests/unit/devcapsule/test_github_transport.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'",
Expand All @@ -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'},
Expand All @@ -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')
Expand Down