winrmxfer 0.1.0__py3-none-any.whl

winrmxfer/__init__.py

@@ -0,0 +1,4 @@
+from .client import WinRMFileClient
+
+__all__ = ["WinRMFileClient"]
+__version__ = "0.1.0"

winrmxfer/client.py

@@ -0,0 +1,221 @@
+import base64
+from pathlib import Path
+from typing import Callable, Optional
+
+import winrm
+
+# pywinrm encodes the PS script as UTF-16LE then base64 for -EncodedCommand,
+# giving ~8/3x expansion. With ~250 bytes of PS overhead per chunk, 2 KB of raw
+# data → ~8000 chars of encoded command, just under the WinRM shell limit.
+DEFAULT_CHUNK_SIZE = 2 * 1024
+
+
+class WinRMFileClient:
+    """File transfer client over WinRM using base64-encoded PowerShell commands.
+
+    Can be constructed in two ways:
+
+        # From credentials — the client creates the session internally.
+        client = WinRMFileClient("host", "user", "pass", transport="ntlm")
+
+        # From an existing winrm.Session.
+        session = winrm.Session("http://host:5985/wsman", auth=("user", "pass"))
+        client = WinRMFileClient(session=session)
+    """
+
+    def __init__(
+        self,
+        host: str = "",
+        username: str = "",
+        password: str = "",
+        transport: str = "ntlm",
+        port: int = 5985,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        session: Optional[winrm.Session] = None,
+        **session_kwargs,
+    ):
+        self.chunk_size = chunk_size
+        if session is not None:
+            self.session = session
+        else:
+            if not host:
+                raise ValueError(
+                    "Provide either 'host'/'username'/'password' or an existing 'session'."
+                )
+            self.session = winrm.Session(
+                target=f"http://{host}:{port}/wsman",
+                auth=(username, password),
+                transport=transport,
+                **session_kwargs,
+            )
+
+    def _run_ps(self, script: str) -> str:
+        result = self.session.run_ps(script)
+        if result.status_code != 0:
+            err = result.std_err.decode("utf-8", errors="replace").strip()
+            raise RuntimeError(f"PowerShell error (exit {result.status_code}): {err}")
+        return result.std_out.decode("utf-8", errors="replace").strip()
+
+    @staticmethod
+    def _esc(path: str) -> str:
+        """Escape single quotes for PowerShell single-quoted strings."""
+        return path.replace("'", "''")
+
+    def upload(
+        self,
+        local_path: str | Path,
+        remote_path: str,
+        progress: Optional[Callable[[int, int], None]] = None,
+    ) -> None:
+        """Upload a local file to the remote machine.
+
+        Args:
+            local_path: Path to the local source file.
+            remote_path: Destination path on the remote Windows machine.
+            progress: Optional callback(current_chunk, total_chunks) for progress reporting.
+        """
+        with open(local_path, "rb") as f:
+            data = f.read()
+
+        # Encode each raw chunk separately so every piece is valid base64.
+        raw_chunks = [
+            data[i : i + self.chunk_size] for i in range(0, len(data), self.chunk_size)
+        ]
+        chunks = [base64.b64encode(c).decode("ascii") for c in raw_chunks]
+
+        remote = self._esc(remote_path)
+        total = len(chunks)
+
+        # Create parent directory, then write first chunk (or empty file).
+        mkdir_ps = f"""$dir = Split-Path '{remote}' -Parent
+if ($dir -and !(Test-Path $dir)) {{ New-Item -ItemType Directory -Path $dir -Force | Out-Null }}"""
+
+        if not data:
+            self._run_ps(f"{mkdir_ps}\n[System.IO.File]::Create('{remote}').Close()")
+        else:
+            self._run_ps(
+                f"{mkdir_ps}\n[System.IO.File]::WriteAllBytes('{remote}', [System.Convert]::FromBase64String('{chunks[0]}'))"
+            )
+        if progress:
+            progress(1, total)
+
+        for i, chunk in enumerate(chunks[1:], start=2):
+            self._run_ps(f"""
+$path = '{remote}'
+$bytes = [System.Convert]::FromBase64String('{chunk}')
+$stream = [System.IO.File]::Open($path, [System.IO.FileMode]::Append)
+try {{
+    $stream.Write($bytes, 0, $bytes.Length)
+}} finally {{
+    $stream.Close()
+}}
+""")
+            if progress:
+                progress(i, total)
+
+    def download(
+        self,
+        remote_path: str,
+        local_path: str | Path,
+        progress: Optional[Callable[[int, int], None]] = None,
+    ) -> None:
+        """Download a file from the remote machine.
+
+        Args:
+            remote_path: Source path on the remote Windows machine.
+            local_path: Destination path on the local machine.
+            progress: Optional callback(current_chunk, total_chunks) for progress reporting.
+        """
+        remote = self._esc(remote_path)
+        local_path = Path(local_path)
+
+        size_str = self._run_ps(f"(Get-Item '{remote}').Length")
+        file_size = int(size_str)
+
+        if local_path.parent:
+            local_path.parent.mkdir(parents=True, exist_ok=True)
+
+        total = max((file_size + self.chunk_size - 1) // self.chunk_size, 1)
+
+        with open(local_path, "wb") as f:
+            offset = 0
+            chunk_num = 0
+            while offset < file_size:
+                b64 = self._run_ps(f"""
+$path = '{remote}'
+$offset = {offset}
+$count = {self.chunk_size}
+$stream = [System.IO.File]::OpenRead($path)
+try {{
+    $buf = New-Object byte[] $count
+    [void]$stream.Seek($offset, [System.IO.SeekOrigin]::Begin)
+    $read = $stream.Read($buf, 0, $count)
+    [System.Convert]::ToBase64String($buf, 0, $read)
+}} finally {{
+    $stream.Close()
+}}
+""")
+                chunk_data = base64.b64decode(b64)
+                f.write(chunk_data)
+                offset += len(chunk_data)
+                chunk_num += 1
+                if progress:
+                    progress(chunk_num, total)
+
+            # Handle empty file
+            if file_size == 0:
+                pass
+
+    def mkdir(self, remote_path: str, parents: bool = True) -> None:
+        """Create a directory on the remote machine."""
+        remote = self._esc(remote_path)
+        force = "-Force" if parents else ""
+        self._run_ps(
+            f"New-Item -ItemType Directory -Path '{remote}' {force} | Out-Null"
+        )
+
+    def remove(self, remote_path: str, recursive: bool = False) -> None:
+        """Remove a file or directory on the remote machine."""
+        remote = self._esc(remote_path)
+        recurse = "-Recurse" if recursive else ""
+        self._run_ps(f"Remove-Item -Path '{remote}' -Force {recurse}")
+
+    def exists(self, remote_path: str) -> bool:
+        """Return True if the remote path exists."""
+        remote = self._esc(remote_path)
+        return self._run_ps(f"Test-Path '{remote}'").lower() == "true"
+
+    def listdir(self, remote_path: str) -> list[str]:
+        """List names of files and directories in a remote directory."""
+        remote = self._esc(remote_path)
+        output = self._run_ps(
+            f"Get-ChildItem -Path '{remote}' | Select-Object -ExpandProperty Name"
+        )
+        return output.splitlines() if output else []
+
+    def move(self, remote_src: str, remote_dst: str) -> None:
+        """Move a file or directory on the remote machine."""
+        src = self._esc(remote_src)
+        dst = self._esc(remote_dst)
+        self._run_ps(f"Move-Item -Path '{src}' -Destination '{dst}' -Force")
+
+    def copy(self, remote_src: str, remote_dst: str, recursive: bool = False) -> None:
+        """Copy a file or directory on the remote machine."""
+        src = self._esc(remote_src)
+        dst = self._esc(remote_dst)
+        recurse = "-Recurse" if recursive else ""
+        self._run_ps(f"Copy-Item -Path '{src}' -Destination '{dst}' -Force {recurse}")
+
+    def stat(self, remote_path: str) -> dict:
+        """Return basic metadata for a remote path (size, is_dir, last_write)."""
+        remote = self._esc(remote_path)
+        output = self._run_ps(f"""
+$item = Get-Item '{remote}'
+"$($item.PSIsContainer)|$($item.Length)|$($item.LastWriteTimeUtc.ToString('o'))"
+""")
+        is_dir_str, size_str, mtime_str = output.split("|", 2)
+        return {
+            "is_dir": is_dir_str.lower() == "true",
+            "size": int(size_str) if size_str else 0,
+            "last_write_utc": mtime_str.strip(),
+        }

winrmxfer-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: winrmxfer
+Version: 0.1.0
+Summary: File transfer over WinRM using base64-encoded PowerShell commands
+Author: Nagy Szabolcs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Dungscer/WinRMXfer
+Project-URL: Issues, https://github.com/Dungscer/WinRMXfer/issues
+Keywords: winrm,powershell,file-transfer,windows,pywinrm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywinrm>=0.4
+Provides-Extra: kerberos
+Requires-Dist: pywinrm[kerberos]; extra == "kerberos"
+Provides-Extra: credssp
+Requires-Dist: pywinrm[credssp]; extra == "credssp"
+Dynamic: license-file
+
+# winrmxfer
+
+A Python package for transferring files over WinRM (Windows Remote Management).
+
+This package originated from a university thesis project where file transfer over WinRM was required as part of automating tasks on remote Windows machines. The solution — encoding file data as base64 and sending it through PowerShell commands — proved useful enough to be packaged as a standalone library.
+
+## Installation
+
+```bash
+pip install winrmxfer
+```
+
+## Requirements
+
+- Python 3.10+
+- [pywinrm](https://github.com/diyan/pywinrm)
+- WinRM enabled and configured on the target Windows machine
+
+## Quick start
+
+```python
+from winrmxfer import WinRMFileClient
+
+# Option 1 — pass credentials, the client creates the WinRM session internally
+client = WinRMFileClient(
+    host="192.168.1.100",
+    username="Administrator",
+    password="s3cr3t",
+    transport="ntlm",   # ntlm (default), basic, kerberos, credssp
+)
+
+# Option 2 — pass an existing winrm.Session
+import winrm
+session = winrm.Session("http://192.168.1.100:5985/wsman", auth=("Administrator", "s3cr3t"))
+client = WinRMFileClient(session=session)
+
+# Upload a file
+client.upload("local_file.zip", r"C:\Users\Administrator\Desktop\file.zip")
+
+# Download a file
+client.download(r"C:\logs\app.log", "app.log")
+```
+
+## API
+
+### `WinRMFileClient(host="", username="", password="", transport="ntlm", port=5985, chunk_size=2048, session=None)`
+
+Creates a new client. Pass either `host`/`username`/`password` to create a session internally, or an existing `winrm.Session` via the `session` parameter. `chunk_size` controls how many raw bytes are sent per WinRM round-trip (default 2 KB, tuned to stay within PowerShell's `-EncodedCommand` limit).
+
+---
+
+### File transfer
+
+#### `upload(local_path, remote_path, progress=None)`
+
+Upload a local file to the remote machine. Large files are automatically split into chunks.
+
+```python
+def progress(current_chunk, total_chunks):
+    print(f"{current_chunk}/{total_chunks}")
+
+client.upload("archive.tar.gz", r"C:\Temp\archive.tar.gz", progress=progress)
+```
+
+#### `download(remote_path, local_path, progress=None)`
+
+Download a file from the remote machine. Parent directories on the local side are created automatically.
+
+```python
+client.download(r"C:\Temp\report.pdf", "downloads/report.pdf")
+```
+
+---
+
+### Remote filesystem operations
+
+#### `exists(remote_path) → bool`
+
+Return `True` if the remote path exists.
+
+#### `stat(remote_path) → dict`
+
+Return basic metadata: `is_dir`, `size` (bytes), `last_write_utc`.
+
+#### `mkdir(remote_path, parents=True)`
+
+Create a directory. With `parents=True` (default), intermediate directories are created as needed.
+
+#### `listdir(remote_path) → list[str]`
+
+List the names of files and directories inside a remote directory.
+
+#### `move(remote_src, remote_dst)`
+
+Move a file or directory on the remote machine.
+
+#### `copy(remote_src, remote_dst, recursive=False)`
+
+Copy a file or directory on the remote machine.
+
+#### `remove(remote_path, recursive=False)`
+
+Delete a file or directory. Use `recursive=True` to remove a directory tree.
+
+---
+
+## How it works
+
+WinRM does not have a built-in file transfer mechanism. `winrmxfer` works around this by:
+
+1. Reading the local file and splitting it into chunks (default 2 KB).
+2. Base64-encoding each chunk.
+3. Sending a PowerShell command per chunk that decodes the base64 and writes the bytes to the remote file using `[System.IO.File]` methods.
+4. Downloads work in reverse: PowerShell reads chunks from the remote file, base64-encodes them, and the client decodes and reassembles the result locally.
+
+The 2 KB chunk size is chosen because `pywinrm` wraps every PowerShell script in a UTF-16LE + base64 encoded `-EncodedCommand`, producing roughly 8× the script size as a command-line argument. Larger chunks exceed the WinRM shell's command-line length limit.
+
+## WinRM setup on Windows
+
+```powershell
+# Run as Administrator
+Enable-PSRemoting -Force
+Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*" -Force
+```
+
+For basic authentication (lab use only):
+```powershell
+Set-Item WSMan:\localhost\Service\Auth\Basic -Value $true
+Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value $true
+```
+
+## Running the tests
+
+The test suite runs against a real WinRM target:
+
+```bash
+pip install pytest
+python -m pytest tests/ -v \
+    --host 127.0.0.1 \
+    --username Administrator \
+    --password s3cr3t \
+    --port 5985
+```
+
+Credentials can also be provided via environment variables: `WINRM_HOST`, `WINRM_PORT`, `WINRM_USER`, `WINRM_PASS`, `WINRM_TRANSPORT`.
+
+## Publishing
+
+Releases are published to PyPI by the GitHub Actions workflow in `.github/workflows/publish.yml`.
+
+- It runs when a tag matching `v*` is pushed (e.g. `git tag v0.1.1 && git push origin v0.1.1`).
+- The build job runs `python -m build` and produces a wheel and an sdist artifact.
+- The publish job uploads them to PyPI using OIDC Trusted Publishing, so no `PYPI_TOKEN` secret is needed.
+
+One-time setup on PyPI:
+1. PyPI → your project → Publishing → "Add a new publisher".
+2. Enter the GitHub repository, the workflow name `publish.yml` and the environment `pypi`.
+
+One-time setup on GitHub:
+- Repository Settings → Environments → create an environment named `pypi` (optionally restrict it to `v*` tags).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

winrmxfer-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+winrmxfer/__init__.py,sha256=CzjxxgJv3n__M_7ii6INv_V6uXyVOzbUcZEMhroiClE,89
+winrmxfer/client.py,sha256=fGBsTObms7PmYjlh7DJFpsuR7ZhLmxrMcdYB_LCUvCo,8046
+winrmxfer-0.1.0.dist-info/licenses/LICENSE,sha256=45mCYN3HW4Sxg4usPT3iMheQ1fsbD5vbzw1AykTf25w,1070
+winrmxfer-0.1.0.dist-info/METADATA,sha256=ClcFP32kx44pRcaUg-gN6o-b1vYj2pNU3FVGwnBUs7M,6177
+winrmxfer-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+winrmxfer-0.1.0.dist-info/top_level.txt,sha256=mQ2qOGm_wIqpdWMd2L7hPSxKImpFFtSs26P1ZpvbtVI,10
+winrmxfer-0.1.0.dist-info/RECORD,,

winrmxfer-0.1.0.dist-info/WHEEL

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

winrmxfer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nagy Szabolcs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

winrmxfer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+winrmxfer