putty-export 0.1.0__py3-none-any.whl

putty_export/__init__.py

@@ -0,0 +1,7 @@
+"""Export PuTTY session settings from Windows registry to OpenSSH config format."""
+
+from putty_export.reg_parser import parse_reg_file
+from putty_export.session_filter import filter_ssh_sessions
+from putty_export.ssh_config import build_ssh_config
+
+__all__ = ["parse_reg_file", "filter_ssh_sessions", "build_ssh_config"]

putty_export/cli.py

@@ -0,0 +1,55 @@
+"""CLI entrypoint: read .reg file, emit SSH config to stdout or file."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from putty_export.reg_parser import parse_reg_file
+from putty_export.session_filter import filter_ssh_sessions
+from putty_export.ssh_config import build_ssh_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Export PuTTY session settings from a Windows registry (.reg) file to OpenSSH config format.",
+    )
+    parser.add_argument(
+        "reg_file",
+        type=Path,
+        help="Path to the exported PuTTY Sessions .reg file",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="Write config to this file instead of stdout",
+    )
+    parser.add_argument(
+        "--include-default-settings",
+        action="store_true",
+        help="Include the 'Default Settings' template session if it has a hostname",
+    )
+    args = parser.parse_args()
+
+    if not args.reg_file.exists():
+        print(f"Error: file not found: {args.reg_file}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        keys = parse_reg_file(args.reg_file)
+    except OSError as e:
+        print(f"Error reading {args.reg_file}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    sessions = filter_ssh_sessions(keys, skip_default_settings=not args.include_default_settings)
+    config = build_ssh_config(sessions)
+
+    if args.output is not None:
+        args.output.write_text(config, encoding="utf-8")
+    else:
+        print(config)
+
+
+if __name__ == "__main__":
+    main()

putty_export/decoders.py

@@ -0,0 +1,48 @@
+"""Decode Windows .reg value types: hex(1) UTF-16LE strings and dword integers."""
+
+import re
+
+
+def decode_hex_string(raw: str) -> str:
+    """
+    Decode a hex(1) registry value (UTF-16LE) to a string.
+    Strips trailing null terminator. Returns empty string on invalid/empty input.
+    """
+    if not raw or not raw.strip():
+        return ""
+    raw = raw.strip()
+    parts = [p.strip() for p in re.split(r"[\s,]+", raw) if p.strip()]
+    try:
+        bytes_list = []
+        for part in parts:
+            if len(part) > 2:
+                continue
+            b = int(part, 16)
+            if 0 <= b <= 255:
+                bytes_list.append(b)
+            else:
+                return ""
+        if not bytes_list:
+            return ""
+        data = bytes(bytes_list)
+        s = data.decode("utf-16-le", errors="replace").rstrip("\x00")
+        return s
+    except (ValueError, UnicodeDecodeError):
+        return ""
+
+
+def decode_dword(raw: str) -> int:
+    """
+    Decode a dword registry value (8 hex digits) to an integer.
+    Returns 0 on invalid/empty input.
+    """
+    if not raw or not raw.strip():
+        return 0
+    raw = raw.strip()
+    m = re.match(r"^([0-9a-fA-F]{1,8})$", raw)
+    if not m:
+        return 0
+    try:
+        return int(m.group(1), 16)
+    except ValueError:
+        return 0

putty_export/reg_parser.py

@@ -0,0 +1,55 @@
+"""Parse Windows .reg files into a structure keyed by full key path and value name."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from putty_export.decoders import decode_dword, decode_hex_string
+
+# Match key line: [\Software\SimonTatham\PuTTY\Sessions\SessionName]
+KEY_LINE = re.compile(r"^\[(.*)\]$")
+# Match value line: "Name"=dword:00000001 or "Name"=hex(1):00,00,...
+VALUE_LINE = re.compile(r'^"([^"]+)"=(dword|hex\(1\)):(.+)$')
+
+
+def parse_reg_file(path: str | Path) -> dict[str, dict[str, Any]]:
+    """
+    Parse a .reg file and return a nested dict: keys[full_key_path][value_name] = decoded_value.
+    Decodes dword as int and hex(1) as UTF-16LE string. Other value types are ignored.
+    """
+    path = Path(path)
+    result: dict[str, dict[str, Any]] = {}
+    current_key: str | None = None
+
+    with open(path, "rb") as f:
+        first = f.read(2)
+        if first == b"\xff\xfe":
+            encoding = "utf-16-le"
+        elif first == b"\xfe\xff":
+            encoding = "utf-16"
+        else:
+            encoding = "utf-8"
+            f.seek(0)
+
+    with open(path, encoding=encoding, errors="replace") as f:
+        for line in f:
+            line = line.rstrip("\r\n")
+            key_m = KEY_LINE.match(line)
+            if key_m:
+                current_key = key_m.group(1).strip()
+                if current_key and current_key not in result:
+                    result[current_key] = {}
+                continue
+
+            if current_key is None:
+                continue
+
+            value_m = VALUE_LINE.match(line)
+            if value_m:
+                name, vtype, raw_value = value_m.group(1), value_m.group(2), value_m.group(3)
+                if vtype == "dword":
+                    result[current_key][name] = decode_dword(raw_value)
+                elif vtype == "hex(1)":
+                    result[current_key][name] = decode_hex_string(raw_value)
+
+    return result

putty_export/session_filter.py

@@ -0,0 +1,72 @@
+"""Filter parsed registry keys to SSH sessions only (Protocol=ssh, non-empty HostName)."""
+
+import re
+from urllib.parse import unquote
+
+# PuTTY sessions live under \Software\SimonTatham\PuTTY\Sessions\<SessionName>
+SESSIONS_PREFIX = r"\Software\SimonTatham\PuTTY\Sessions"
+SESSIONS_PREFIX_NORMALIZED = SESSIONS_PREFIX.lower().replace("/", "\\")
+
+
+def _normalize_key(key: str) -> str:
+    return key.replace("/", "\\").strip("\\").lower()
+
+
+def _session_name_from_key(full_key: str) -> str | None:
+    """Extract session name from key path. Returns None if not a session key."""
+    norm = _normalize_key(full_key)
+    prefix = SESSIONS_PREFIX_NORMALIZED.strip("\\")
+    if not norm.startswith(prefix):
+        return None
+    suffix = norm[len(prefix) :].strip("\\")
+    if not suffix:
+        return None
+    # Session name is the last segment in the original key
+    parts = full_key.replace("/", "\\").strip("\\").split("\\")
+    if len(parts) < 2:
+        return None
+    name = parts[-1]
+    return unquote(name)
+
+
+def filter_ssh_sessions(
+    keys: dict[str, dict[str, object]],
+    *,
+    skip_default_settings: bool = True,
+) -> dict[str, dict[str, object]]:
+    """
+    Return a dict of session_name -> session_values for keys that are SSH sessions:
+    - Key path is ...\\Sessions\\<Name> (not the bare Sessions key).
+    - Protocol (decoded string) equals "ssh" (case-insensitive).
+    - HostName (decoded string) is non-empty after strip.
+    - Optionally skip session name "Default Settings".
+    Duplicate session names: later key wins.
+    """
+    result: dict[str, dict[str, object]] = {}
+    norm_prefix = _normalize_key(SESSIONS_PREFIX).rstrip("\\")
+
+    for full_key, values in keys.items():
+        session_name = _session_name_from_key(full_key)
+        if session_name is None:
+            continue
+        if skip_default_settings and session_name == "Default Settings":
+            continue
+
+        protocol_val = values.get("Protocol")
+        if isinstance(protocol_val, str):
+            protocol = protocol_val.strip().lower()
+        else:
+            protocol = ""
+        if protocol != "ssh":
+            continue
+
+        hostname_val = values.get("HostName")
+        if isinstance(hostname_val, str):
+            hostname = hostname_val.strip()
+        else:
+            hostname = ""
+        if not hostname:
+            continue
+
+        result[session_name] = dict(values)
+    return result

putty_export/ssh_config.py

@@ -0,0 +1,154 @@
+"""Build OpenSSH config text from filtered PuTTY session data."""
+
+import re
+from typing import Any
+
+
+def _get_str(data: dict[str, Any], key: str, default: str = "") -> str:
+    v = data.get(key)
+    if isinstance(v, str):
+        return v.strip()
+    return default
+
+
+def _get_int(data: dict[str, Any], key: str, default: int = 0) -> int:
+    v = data.get(key)
+    if isinstance(v, int):
+        return v
+    if isinstance(v, str) and v.strip().isdigit():
+        return int(v.strip())
+    return default
+
+
+def _quote_value(s: str) -> str:
+    """Quote value if it contains spaces or special characters."""
+    if not s:
+        return '""'
+    if re.search(r'[\s#"\\]', s):
+        return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return s
+
+
+def _build_proxy_directive(data: dict[str, Any]) -> str | None:
+    """Build ProxyCommand or ProxyJump line. Returns None if no proxy."""
+    method = _get_int(data, "ProxyMethod", 0)
+    host = _get_str(data, "ProxyHost")
+    if method == 0 or not host:
+        return None
+    port = _get_int(data, "ProxyPort", 80)
+    username = _get_str(data, "ProxyUsername")
+
+    if method == 5:
+        # SSH proxy (jump host)
+        if username:
+            return f"  ProxyJump {username}@{host}"
+        return f"  ProxyJump {host}"
+
+    if method == 1:
+        # SOCKS 4/5
+        return f"  ProxyCommand nc -x {host}:{port} %h %p"
+    if method == 2:
+        # HTTP CONNECT
+        return f"  ProxyCommand connect -H {host}:{port} %h %p"
+    if method in (3, 4):
+        # Telnet or Local: use ProxyTelnetCommand (custom command)
+        cmd = _get_str(data, "ProxyTelnetCommand")
+        if cmd:
+            cmd = cmd.replace("%host", "%h").replace("%port", "%p")
+            return f"  ProxyCommand {cmd}"
+        return None
+    return None
+
+
+def _parse_port_forwardings(raw: str) -> list[tuple[str, str]]:
+    """
+    Parse PortForwardings string. Returns list of (directive_name, value).
+    Format: Lport=host:port, Rport=host:port, Dport. Optional bind: Lbind:port=host:port.
+    """
+    if not raw or not raw.strip():
+        return []
+    result = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if part.startswith("L"):
+            rest = part[1:]
+            if "=" in rest:
+                left, right = rest.split("=", 1)
+                # left can be "port" or "bind:port"
+                result.append(("LocalForward", f"{left.strip()} {right.strip()}"))
+            else:
+                result.append(("LocalForward", rest))
+        elif part.startswith("R"):
+            rest = part[1:]
+            if "=" in rest:
+                left, right = rest.split("=", 1)
+                result.append(("RemoteForward", f"{left.strip()} {right.strip()}"))
+            else:
+                result.append(("RemoteForward", rest))
+        elif part.startswith("D"):
+            port = part[1:].strip()
+            if port:
+                result.append(("DynamicForward", port))
+    return result
+
+
+def _identity_file_path(path: str) -> str:
+    """Normalize path: backslashes to forward slashes for cross-platform hint."""
+    if not path:
+        return path
+    return path.replace("\\", "/")
+
+
+def build_host_block(session_name: str, data: dict[str, Any]) -> str:
+    """Build one Host block for a single session. session_name becomes the Host alias."""
+    lines = [f"Host {_quote_value(session_name)}"]
+
+    hostname = _get_str(data, "HostName")
+    if hostname:
+        lines.append(f"  HostName {hostname}")
+
+    port = _get_int(data, "PortNumber", 22)
+    if port != 22:
+        lines.append(f"  Port {port}")
+    else:
+        lines.append("  Port 22")
+
+    user = _get_str(data, "UserName")
+    if user:
+        lines.append(f"  User {user}")
+
+    identity = _get_str(data, "PublicKeyFile")
+    if identity:
+        lines.append(f"  IdentityFile {_quote_value(_identity_file_path(identity))}")
+
+    proxy = _build_proxy_directive(data)
+    if proxy:
+        lines.append(proxy)
+
+    port_fwd = _get_str(data, "PortForwardings")
+    for directive, value in _parse_port_forwardings(port_fwd):
+        lines.append(f"  {directive} {value}")
+
+    agent_fwd = _get_int(data, "AgentFwd", 0)
+    if agent_fwd:
+        lines.append("  ForwardAgent yes")
+
+    compression = _get_int(data, "Compression", 0)
+    if compression:
+        lines.append("  Compression yes")
+
+    x11 = _get_int(data, "X11Forward", 0)
+    if x11:
+        lines.append("  ForwardX11 yes")
+
+    return "\n".join(lines)
+
+
+def build_ssh_config(sessions: dict[str, dict[str, Any]]) -> str:
+    """Build full SSH config from sessions dict (session_name -> values)."""
+    blocks = []
+    for name in sorted(sessions.keys()):
+        blocks.append(build_host_block(name, sessions[name]))
+    return "\n\n".join(blocks)

putty_export-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: putty-export
+Version: 0.1.0
+Summary: Export PuTTY session settings from Windows registry to OpenSSH config format
+Author: putty-export
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# putty-export
+
+Export PuTTY session settings from a Windows registry (.reg) file to OpenSSH `~/.ssh/config` format.
+
+## Usage
+
+```bash
+# Print SSH config to stdout
+putty-export putty_sessions.reg
+
+# Write to a file
+putty-export putty_sessions.reg -o ~/.ssh/config
+
+# Include the "Default Settings" template session (normally skipped)
+putty-export putty_sessions.reg --include-default-settings -o config
+```
+
+## Exporting PuTTY sessions from Windows
+
+1. Open **Registry Editor** (`regedit.exe`).
+2. Navigate to `HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions`.
+3. Right-click **Sessions** and choose **Export**.
+4. Save as a `.reg` file (e.g. `putty_sessions.reg`) and transfer it to the machine where you run `putty-export`.
+
+## PuTTY → OpenSSH mapping
+
+| PuTTY (registry)              | OpenSSH config                | Notes |
+|--------------------------------|-------------------------------|-------|
+| Session name (from key path)   | `Host`                        | URL-decoded (e.g. `%20` → space). |
+| HostName                       | `HostName`                    | Decoded from UTF-16LE. |
+| PortNumber                     | `Port`                        | Default 22 if missing. |
+| UserName                       | `User`                        | Omitted if empty. |
+| PublicKeyFile                  | `IdentityFile`                | Path normalized to forward slashes. See [Keys](#keys) below. |
+| ProxyMethod + ProxyHost/Port/Username | `ProxyCommand` or `ProxyJump` | See [Proxy](#proxy) below. |
+| PortForwardings                | `LocalForward` / `RemoteForward` / `DynamicForward` | Comma-separated: `Lport=host:port`, `Rport=host:port`, `Dport`. |
+| AgentFwd                       | `ForwardAgent`                 | 1 → yes (omitted when 0). |
+| Compression                    | `Compression`                 | 1 → yes (omitted when 0). |
+| X11Forward                     | `ForwardX11`                  | 1 → yes (omitted when 0). |
+
+### Keys
+
+- **IdentityFile** is written with the path from PuTTY (backslashes converted to forward slashes). PuTTY uses `.ppk` keys; OpenSSH uses PEM/OpenSSH format. Convert keys with:
+  ```bash
+  puttygen key.ppk -O private-openssh -o ~/.ssh/key_openssh
+  ```
+  Then point `IdentityFile` at the converted file, or replace the path in the generated config.
+
+### Proxy
+
+- **ProxyMethod** 0 = none (no directive). 1 = SOCKS → `ProxyCommand nc -x host:port %h %p`. 2 = HTTP CONNECT → `ProxyCommand connect -H host:port %h %p`. 3/4 = Telnet/Local → `ProxyCommand` from ProxyTelnetCommand. 5 = SSH proxy → `ProxyJump user@host`.
+- **ProxyPassword** is not stored in SSH config. Use key-based auth or other means for proxy/jump host authentication.
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies (stdlib only).
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Development
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+

putty_export-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+putty_export/__init__.py,sha256=aAgr_9AKx5RqQwErZa9m3oIN6gNmmysQcZ9zgGyeGEc,322
+putty_export/cli.py,sha256=YVf-zC0AL8idjshB8fqTAm-0oVBehxHS0P_cN4QxFRk,1585
+putty_export/decoders.py,sha256=_StamXINcs7tdjrxGDPJL9BOcj_liTGBuEzDRe4eUmY,1318
+putty_export/reg_parser.py,sha256=ne5U1Tg7JKsCpL7sjSxQDl-gjcTNJZu4Yb-nLU0lNxw,1926
+putty_export/session_filter.py,sha256=bJXF9JKFGNt3AC8Vae93m5A-0gW1EO8DhtMvM46uAy8,2429
+putty_export/ssh_config.py,sha256=RkOmCyM20vkxzgWMVEGxN3fhGFZrd2xy9ojiiUPV6Gc,4823
+putty_export-0.1.0.dist-info/METADATA,sha256=D_3I4cgI2m_yxJvfL9q-fPiFosrc8WBhd_OzmZqqAHg,3763
+putty_export-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+putty_export-0.1.0.dist-info/entry_points.txt,sha256=IOAoXLkXJhM5SEKe0PhwhpX9IjsrlgjqDxEKjfwSxdY,55
+putty_export-0.1.0.dist-info/top_level.txt,sha256=cCSHNEpHUPVIDEjiB0aL-UT05f8BNW5oJxOl5s0L95Q,13
+putty_export-0.1.0.dist-info/RECORD,,

putty_export-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

putty_export-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+putty-export = putty_export.cli:main

putty_export-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+putty_export