github2gerrit 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

github2gerrit/ssh_agent_setup.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+
+"""
+SSH agent-based authentication for github2gerrit.
+
+This module provides functionality to use SSH agent for authentication
+instead of writing private keys to disk, which is more secure and
+avoids file permission issues in CI environments.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .gitutils import CommandError
+from .gitutils import run_cmd
+from .ssh_common import augment_known_hosts_with_bracketed_entries
+
+
+log = logging.getLogger(__name__)
+
+
+class SSHAgentError(Exception):
+    """Raised when SSH agent operations fail."""
+
+
+# Error message constants to comply with TRY003
+_MSG_PARSE_FAILED = "Failed to parse ssh-agent output"
+_MSG_START_FAILED = "Failed to start SSH agent: {error}"
+_MSG_NOT_STARTED = "SSH agent not started"
+_MSG_ADD_FAILED = "ssh-add failed: {error}"
+_MSG_ADD_TIMEOUT = "ssh-add timed out"
+_MSG_ADD_KEY_FAILED = "Failed to add key to SSH agent: {error}"
+_MSG_SETUP_HOSTS_FAILED = "Failed to setup known hosts: {error}"
+_MSG_HOSTS_NOT_CONFIGURED = "Known hosts not configured"
+_MSG_LIST_FAILED = "Failed to list keys: {error}"
+_MSG_NO_KEYS_LOADED = "No keys were loaded into SSH agent"
+_MSG_SSH_AGENT_NOT_FOUND = "ssh-agent not found in PATH"
+_MSG_SSH_ADD_NOT_FOUND = "ssh-add not found in PATH"
+
+
+class SSHAgentManager:
+    """Manages SSH agent lifecycle and key loading for secure authentication."""
+
+    def __init__(self, workspace: Path):
+        """Initialize SSH agent manager.
+
+        Args:
+            workspace: The workspace directory for storing temporary files
+        """
+        self.workspace = workspace
+        self.agent_pid: int | None = None
+        self.auth_sock: str | None = None
+        self.known_hosts_path: Path | None = None
+        self._original_env: dict[str, str] = {}
+
+    def start_agent(self) -> None:
+        """Start a new SSH agent process."""
+        try:
+            # Locate ssh-agent executable
+            ssh_agent_path = shutil.which("ssh-agent")
+            if not ssh_agent_path:
+                _raise_ssh_agent_not_found()
+            assert ssh_agent_path is not None  # for mypy  # noqa: S101
+
+            # Start ssh-agent and capture its output
+            result = run_cmd([ssh_agent_path, "-s"], timeout=10)
+
+            # Parse the ssh-agent output to get environment variables
+            for line in result.stdout.strip().split("\n"):
+                if line.startswith("SSH_AUTH_SOCK="):
+                    # Format: SSH_AUTH_SOCK=/path/to/socket; export SSH_AUTH_SOCK;
+                    value = line.split("=", 1)[1].split(";")[0].strip()
+                    self.auth_sock = value
+                elif line.startswith("SSH_AGENT_PID="):
+                    # Format: SSH_AGENT_PID=12345; export SSH_AGENT_PID;
+                    value = line.split("=", 1)[1].split(";")[0].strip()
+                    self.agent_pid = int(value)
+
+            if not self.auth_sock or not self.agent_pid:
+                _raise_parse_error()
+
+            # Store original environment
+            self._original_env = {
+                "SSH_AUTH_SOCK": os.environ.get("SSH_AUTH_SOCK", ""),
+                "SSH_AGENT_PID": os.environ.get("SSH_AGENT_PID", ""),
+            }
+
+            # Set environment variables for this process
+            if self.auth_sock:
+                os.environ["SSH_AUTH_SOCK"] = self.auth_sock
+            if self.agent_pid:
+                os.environ["SSH_AGENT_PID"] = str(self.agent_pid)
+
+            log.debug("Started SSH agent with PID %d, socket %s", self.agent_pid, self.auth_sock)
+
+        except Exception as exc:
+            raise SSHAgentError(_MSG_START_FAILED.format(error=exc)) from exc
+
+    def add_key(self, private_key_content: str) -> None:
+        """Add a private key to the SSH agent.
+
+        Args:
+            private_key_content: The private key content as a string
+        """
+        if not self.auth_sock:
+            raise SSHAgentError(_MSG_NOT_STARTED)
+
+        # Locate ssh-add executable
+        ssh_add_path = shutil.which("ssh-add")
+        if not ssh_add_path:
+            _raise_ssh_add_not_found()
+        assert ssh_add_path is not None  # for mypy  # noqa: S101
+
+        process = None
+        try:
+            # Use ssh-add with stdin to add the key
+            process = subprocess.Popen(  # noqa: S603
+                [ssh_add_path, "-"],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                env={
+                    **os.environ,
+                    "SSH_AUTH_SOCK": self.auth_sock,
+                    "SSH_AGENT_PID": str(self.agent_pid),
+                },
+            )
+
+            stdout, stderr = process.communicate(input=private_key_content.strip() + "\n", timeout=10)
+
+            if process.returncode != 0:
+                _raise_add_key_error(stderr)
+
+            log.debug("Successfully added SSH key to agent")
+
+        except subprocess.TimeoutExpired as exc:
+            if process:
+                process.kill()
+            raise SSHAgentError(_MSG_ADD_TIMEOUT) from exc
+        except Exception as exc:
+            raise SSHAgentError(_MSG_ADD_KEY_FAILED.format(error=exc)) from exc
+
+    def setup_known_hosts(self, known_hosts_content: str) -> None:
+        """Setup known hosts file.
+
+        Args:
+            known_hosts_content: The known hosts content
+        """
+        try:
+            # Create tool-specific SSH directory
+            tool_ssh_dir = self.workspace / ".ssh-g2g"
+            tool_ssh_dir.mkdir(mode=0o700, exist_ok=True)
+
+            # Write known hosts file (normalize/augment with [host]:port entries)
+            self.known_hosts_path = tool_ssh_dir / "known_hosts"
+            host = (os.getenv("GERRIT_SERVER") or "").strip()
+            port = (os.getenv("GERRIT_SERVER_PORT") or "29418").strip()
+            try:
+                port_int = int(port)
+            except Exception:
+                port_int = 29418
+
+            # Use centralized augmentation logic
+            augmented_content = augment_known_hosts_with_bracketed_entries(known_hosts_content, host, port_int)
+
+            with open(self.known_hosts_path, "w", encoding="utf-8") as f:
+                f.write(augmented_content)
+            self.known_hosts_path.chmod(0o644)
+
+            log.debug("Known hosts written to %s", self.known_hosts_path)
+
+        except Exception as exc:
+            raise SSHAgentError(_MSG_SETUP_HOSTS_FAILED.format(error=exc)) from exc
+
+    def get_git_ssh_command(self) -> str:
+        """Generate GIT_SSH_COMMAND for SSH agent-based authentication.
+
+        Returns:
+            SSH command string for git operations
+        """
+        if not self.known_hosts_path:
+            raise SSHAgentError(_MSG_HOSTS_NOT_CONFIGURED)
+
+        ssh_options = [
+            "-F /dev/null",
+            f"-o UserKnownHostsFile={self.known_hosts_path}",
+            "-o IdentitiesOnly=no",  # Allow SSH agent
+            "-o BatchMode=yes",
+            "-o PreferredAuthentications=publickey",
+            "-o StrictHostKeyChecking=yes",
+            "-o PasswordAuthentication=no",
+            "-o PubkeyAcceptedKeyTypes=+ssh-rsa",
+            "-o ConnectTimeout=10",
+        ]
+
+        return f"ssh {' '.join(ssh_options)}"
+
+    def get_ssh_env(self) -> dict[str, str]:
+        """Get environment variables for SSH operations.
+
+        Returns:
+            Dictionary of environment variables
+        """
+        if not self.auth_sock:
+            raise SSHAgentError(_MSG_NOT_STARTED)
+
+        return {
+            "SSH_AUTH_SOCK": self.auth_sock,
+            "SSH_AGENT_PID": str(self.agent_pid),
+        }
+
+    def list_keys(self) -> str:
+        """List keys currently loaded in the agent.
+
+        Returns:
+            Output from ssh-add -l
+        """
+        if not self.auth_sock:
+            raise SSHAgentError(_MSG_NOT_STARTED)
+
+        try:
+            # Locate ssh-add executable
+            ssh_add_path = shutil.which("ssh-add")
+            if not ssh_add_path:
+                _raise_ssh_add_not_found()
+            assert ssh_add_path is not None  # for mypy  # noqa: S101
+
+            result = run_cmd(
+                [ssh_add_path, "-l"],
+                env={
+                    **os.environ,
+                    "SSH_AUTH_SOCK": self.auth_sock,
+                    "SSH_AGENT_PID": str(self.agent_pid),
+                },
+                timeout=5,
+            )
+        except CommandError as exc:
+            if exc.returncode == 1:
+                return "No keys loaded"
+            raise SSHAgentError(_MSG_LIST_FAILED.format(error=exc)) from exc
+        except Exception as exc:
+            raise SSHAgentError(_MSG_LIST_FAILED.format(error=exc)) from exc
+        else:
+            return result.stdout
+
+    def cleanup(self) -> None:
+        """Clean up SSH agent and temporary files."""
+        try:
+            # Kill SSH agent if we started it
+            if self.agent_pid:
+                try:
+                    run_cmd(["/bin/kill", str(self.agent_pid)], timeout=5)
+                    log.debug("SSH agent (PID %d) terminated", self.agent_pid)
+                except Exception as exc:
+                    log.warning("Failed to kill SSH agent: %s", exc)
+
+            # Restore original environment
+            for key, value in self._original_env.items():
+                if value:
+                    os.environ[key] = value
+                elif key in os.environ:
+                    del os.environ[key]
+
+            # Clean up temporary files
+            tool_ssh_dir = self.workspace / ".ssh-g2g"
+            if tool_ssh_dir.exists():
+                import shutil
+
+                shutil.rmtree(tool_ssh_dir)
+                log.debug("Cleaned up temporary SSH directory: %s", tool_ssh_dir)
+
+        except Exception as exc:
+            log.warning("Failed to clean up SSH agent: %s", exc)
+        finally:
+            self.agent_pid = None
+            self.auth_sock = None
+            self.known_hosts_path = None
+
+
+def setup_ssh_agent_auth(workspace: Path, private_key_content: str, known_hosts_content: str) -> SSHAgentManager:
+    """Setup SSH agent-based authentication.
+
+    Args:
+        workspace: The workspace directory
+        private_key_content: SSH private key content
+        known_hosts_content: Known hosts content
+
+    Returns:
+        Configured SSHAgentManager instance
+
+    Raises:
+        SSHAgentError: If setup fails
+    """
+    manager = SSHAgentManager(workspace)
+
+    try:
+        # Start SSH agent
+        manager.start_agent()
+
+        # Add the private key
+        manager.add_key(private_key_content)
+
+        # Setup known hosts
+        manager.setup_known_hosts(known_hosts_content)
+
+        # Verify key was added
+        keys_list = manager.list_keys()
+        if "No keys loaded" in keys_list:
+            _raise_no_keys_error()
+
+        log.info("SSH agent authentication configured successfully")
+        log.debug("Loaded keys: %s", keys_list)
+
+    except Exception:
+        # Clean up on failure
+        manager.cleanup()
+        raise
+    else:
+        return manager
+
+
+def _raise_parse_error() -> None:
+    """Raise SSH agent parse error."""
+    raise SSHAgentError(_MSG_PARSE_FAILED)
+
+
+def _raise_add_key_error(stderr: str) -> None:
+    """Raise SSH key addition error."""
+    raise SSHAgentError(_MSG_ADD_FAILED.format(error=stderr))
+
+
+def _raise_ssh_agent_not_found() -> None:
+    """Raise SSH agent not found error."""
+    raise SSHAgentError(_MSG_SSH_AGENT_NOT_FOUND)
+
+
+def _raise_ssh_add_not_found() -> None:
+    """Raise SSH add not found error."""
+    raise SSHAgentError(_MSG_SSH_ADD_NOT_FOUND)
+
+
+def _raise_no_keys_error() -> None:
+    """Raise no keys loaded error."""
+    raise SSHAgentError(_MSG_NO_KEYS_LOADED)

github2gerrit/ssh_common.py

@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+
+"""Common SSH utilities for consistent SSH configuration across modules.
+
+This module provides shared SSH functionality to avoid duplication between
+CLI and core SSH setup routines, ensuring consistent behavior and options.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+
+log = logging.getLogger(__name__)
+
+
+def build_ssh_options(
+    key_path: str | Path | None = None,
+    known_hosts_path: str | Path | None = None,
+    identities_only: bool = True,
+    strict_host_checking: bool = True,
+    batch_mode: bool = True,
+    connect_timeout: int = 10,
+    additional_options: list[str] | None = None,
+    respect_user_ssh_config: bool | None = None,
+) -> list[str]:
+    """Build a list of SSH options for secure, isolated SSH configuration.
+
+    Args:
+        key_path: Path to SSH private key file
+        known_hosts_path: Path to known_hosts file
+        identities_only: Only use specified identities (prevents agent scanning)
+        strict_host_checking: Enable strict host key checking
+        batch_mode: Enable batch mode (non-interactive)
+        connect_timeout: Connection timeout in seconds
+        additional_options: Additional SSH options to include
+        respect_user_ssh_config: If True, respect user SSH config; if None, check G2G_RESPECT_USER_SSH env var
+
+    Returns:
+        List of SSH option strings suitable for ssh command line
+    """
+    # Check if we should respect user SSH config
+    if respect_user_ssh_config is None:
+        respect_user_ssh_config = os.getenv("G2G_RESPECT_USER_SSH", "false").lower() in ("true", "1", "yes")
+
+    options = []
+    if not respect_user_ssh_config:
+        options.append("-F /dev/null")  # Ignore user SSH config
+
+    if key_path:
+        options.append(f"-i {key_path}")
+
+    if known_hosts_path:
+        options.append(f"-o UserKnownHostsFile={known_hosts_path}")
+
+    if identities_only and not respect_user_ssh_config:
+        options.extend(
+            [
+                "-o IdentitiesOnly=yes",  # Critical: prevents SSH agent scanning
+                "-o IdentityAgent=none",
+            ]
+        )
+
+    if batch_mode:
+        options.append("-o BatchMode=yes")
+
+    options.extend(
+        [
+            "-o PreferredAuthentications=publickey",
+            "-o PasswordAuthentication=no",
+            "-o PubkeyAcceptedKeyTypes=+ssh-rsa",
+            f"-o ConnectTimeout={connect_timeout}",
+        ]
+    )
+
+    if strict_host_checking:
+        options.append("-o StrictHostKeyChecking=yes")
+
+    if additional_options:
+        options.extend(additional_options)
+
+    return options
+
+
+def build_git_ssh_command(
+    key_path: str | Path | None = None,
+    known_hosts_path: str | Path | None = None,
+    identities_only: bool = True,
+    strict_host_checking: bool = True,
+    batch_mode: bool = True,
+    connect_timeout: int = 10,
+    additional_options: list[str] | None = None,
+    respect_user_ssh_config: bool | None = None,
+) -> str:
+    """Build GIT_SSH_COMMAND for secure, isolated SSH configuration.
+
+    This prevents SSH from scanning the user's SSH agent or using
+    unintended keys by setting appropriate SSH options, unless
+    respect_user_ssh_config is True.
+
+    Args:
+        key_path: Path to SSH private key file
+        known_hosts_path: Path to known_hosts file
+        identities_only: Only use specified identities (prevents agent scanning)
+        strict_host_checking: Enable strict host key checking
+        batch_mode: Enable batch mode (non-interactive)
+        connect_timeout: Connection timeout in seconds
+        additional_options: Additional SSH options to include
+        respect_user_ssh_config: If True, respect user SSH config; if None, check G2G_RESPECT_USER_SSH env var
+
+    Returns:
+        Complete SSH command string suitable for GIT_SSH_COMMAND
+    """
+    ssh_options = build_ssh_options(
+        key_path=key_path,
+        known_hosts_path=known_hosts_path,
+        identities_only=identities_only,
+        strict_host_checking=strict_host_checking,
+        batch_mode=batch_mode,
+        connect_timeout=connect_timeout,
+        additional_options=additional_options,
+        respect_user_ssh_config=respect_user_ssh_config,
+    )
+
+    ssh_cmd = f"ssh {' '.join(ssh_options)}"
+
+    # Log masked version for security
+    if key_path:
+        masked_cmd = ssh_cmd.replace(str(key_path), "[KEY_PATH]")
+        log.debug("Generated SSH command: %s", masked_cmd)
+    else:
+        log.debug("Generated SSH command: %s", ssh_cmd)
+
+    return ssh_cmd
+
+
+def build_non_interactive_ssh_env() -> dict[str, str]:
+    """Build environment variables for non-interactive SSH operations.
+
+    This creates an environment that prevents SSH from using agents,
+    asking for passwords, or displaying prompts.
+
+    Returns:
+        Dictionary of environment variables for non-interactive SSH
+    """
+    return {
+        "SSH_AUTH_SOCK": "",
+        "SSH_AGENT_PID": "",
+        "SSH_ASKPASS": "/usr/bin/false",
+        "DISPLAY": "",
+        "SSH_ASKPASS_REQUIRE": "never",
+    }
+
+
+def augment_known_hosts_with_bracketed_entries(
+    known_hosts_content: str,
+    hostname: str,
+    port: int = 22,
+) -> str:
+    """Augment known_hosts content with bracketed [host]:port entries for non-standard ports.
+
+    This function adds bracketed [host]:port variants for existing plain host entries
+    to satisfy StrictHostKeyChecking with non-standard SSH ports.
+
+    Args:
+        known_hosts_content: Original known_hosts content
+        hostname: Hostname to augment
+        port: SSH port (default 22)
+
+    Returns:
+        Augmented known_hosts content (always normalized to end with single newline)
+    """
+    if not known_hosts_content.strip():
+        return known_hosts_content
+
+    original_lines = [ln.rstrip() for ln in known_hosts_content.strip().splitlines() if ln.strip()]
+    augmented = list(original_lines)
+
+    # Add bracketed [host]:port variants for non-standard ports if hostname provided
+    if hostname and original_lines:
+        bracket_prefix = f"[{hostname}]:{port} "
+        plain_prefix = f"{hostname} "
+        existing = set(augmented)
+
+        for ln in original_lines:
+            if ln.startswith(plain_prefix):
+                suffix = ln[len(plain_prefix) :]
+                candidate = bracket_prefix + suffix
+                if candidate not in existing:
+                    augmented.append(candidate)
+                    existing.add(candidate)
+
+    # Always normalize to strip + newline for consistency
+    return "\n".join(augmented).strip() + "\n"
+
+
+def merge_known_hosts_content(
+    base_content: str,
+    additional_content: str,
+) -> str:
+    """Merge additional known_hosts content into base content without duplicates.
+
+    Args:
+        base_content: Original known_hosts content
+        additional_content: Additional content to merge
+
+    Returns:
+        Merged known_hosts content
+    """
+    if not additional_content or not additional_content.strip():
+        return base_content
+
+    if not base_content or not base_content.strip():
+        return additional_content.strip() + "\n"
+
+    existing_lines = [ln for ln in base_content.splitlines() if ln.strip()]
+    existing_set = set(existing_lines)
+
+    for ln in additional_content.splitlines():
+        s = ln.strip()
+        if s and s not in existing_set:
+            existing_lines.append(s)
+            existing_set.add(s)
+
+    return "\n".join(existing_lines).strip() + "\n"
+
+
+def augment_known_hosts(
+    known_hosts_path: Path,
+    hostname: str,
+    port: int = 22,
+) -> None:
+    """Augment known_hosts file with host key for the given hostname.
+
+    Args:
+        known_hosts_path: Path to known_hosts file
+        hostname: Hostname to add to known_hosts
+        port: SSH port (default 22)
+    """
+    # This is a placeholder for known hosts augmentation logic
+    # The actual implementation would use ssh-keyscan or similar
+    # to fetch and add host keys to the known_hosts file
+    log.debug("Would augment known_hosts at %s with %s:%d", known_hosts_path, hostname, port)

github2gerrit/ssh_discovery.py

@@ -16,6 +16,8 @@ import os
 import socket
 from pathlib import Path
 
+from .external_api import ApiType
+from .external_api import external_api_call
 from .gitutils import CommandError
 from .gitutils import run_cmd
 
@@ -50,6 +52,7 @@ def is_host_reachable(hostname: str, port: int, timeout: int = 5) -> bool:
         return False
 
 
+@external_api_call(ApiType.SSH, "fetch_ssh_host_keys")
 def fetch_ssh_host_keys(hostname: str, port: int = 22, timeout: int = 10) -> str:
     """
     Fetch SSH host keys for a given hostname and port using ssh-keyscan.
@@ -168,6 +171,7 @@ def extract_gerrit_info_from_gitreview(content: str) -> tuple[str, int] | None:
     return (hostname, port) if hostname else None
 
 
+@external_api_call(ApiType.SSH, "discover_and_save_host_keys")
 def discover_and_save_host_keys(hostname: str, port: int, organization: str, config_path: str | None = None) -> str:
     """
     Discover SSH host keys and save them to the organization's configuration.