PyPSRP

0.9.1 · active · verified Thu Apr 09

PyPSRP is a Python library that provides client implementations for the PowerShell Remoting Protocol (PSRP) and the underlying WS-Management (WinRM) protocol. It allows Python applications to execute PowerShell commands and scripts on remote Windows machines. The current version is 0.9.1, and releases are made on an as-needed basis to add features or fix bugs.

Warnings

breaking PyPSRP requires Python 3.10 or newer. Attempting to install or run on older Python versions will result in dependency resolution failures or runtime errors.
Fix: Upgrade your Python environment to 3.10 or later.
gotcha WinRM and PowerShell Remoting require specific configurations on the target Windows host, including enabling WinRM (e.g., `winrm quickconfig` in an elevated PowerShell) and ensuring firewall rules allow traffic on ports 5985 (HTTP) or 5986 (HTTPS).
Fix: Ensure WinRM is enabled and configured correctly on the remote server. Verify network connectivity and firewall rules.
gotcha Remote PowerShell command errors (e.g., cmdlets failing) are not raised as Python exceptions by default. Instead, they are captured in the `ps.streams.error` or `ps.streams.warning` lists.
Fix: Always check `PowerShell.streams.error` and `PowerShell.streams.warning` after invoking a command to detect and handle remote errors gracefully.
gotcha Authentication can be complex. NTLM and Kerberos are supported, but Kerberos requires the `gssapi` dependency and proper Kerberos configuration (e.g., `krb5.conf`). SSL/TLS certificate verification can also be an issue, especially with self-signed certificates.
Fix: For Kerberos, install `pypsrp[kerberos]` and ensure your system's Kerberos client is configured. For SSL issues, consider setting `verify_ssl=False` in `connection_options` for testing (not recommended for production) or ensure a valid certificate chain.
gotcha PyPSRP provides both low-level WS-Management (WinRM) through `WSMan` and higher-level PowerShell Remoting through `RunspacePool` and `PowerShell`. Using `WSMan` directly for PowerShell commands will be significantly more complex as it doesn't handle the PowerShell serialization and object model.
Fix: For executing PowerShell scripts and cmdlets, always use `RunspacePool` and `PowerShell`. Use `WSMan` only if you need to interact with raw WinRM for non-PowerShell purposes (e.g., CIM operations).

Install

pip install pypsrp Standard Install
pip install pypsrp[kerberos] Install with Kerberos support

Imports

WSMan
```
from pypsrp.wsman import WSMan
```
The WSMan class moved to the wsman submodule from a top-level client module in earlier versions.
RunspacePool
```
from pypsrp.powershell import RunspacePool
```
The RunspacePool class moved to the powershell submodule from a top-level client module in earlier versions.
PowerShell
```
from pypsrp.powershell import PowerShell
```
The PowerShell class moved to the powershell submodule from a top-level client module in earlier versions.

Quickstart

This quickstart demonstrates how to connect to a remote Windows host using PowerShell Remoting (via `RunspacePool`) and execute a PowerShell command. It retrieves the status of the 'Background Intelligent Transfer Service' (BITS). Credentials are loaded from environment variables for security and portability. Remember to configure WinRM on the target host and ensure firewall rules allow the connection.

import os
from pypsrp.powershell import PowerShell, RunspacePool

# Set these environment variables for a runnable example:
# PYPSRP_HOST='your_windows_host'
# PYPSRP_USERNAME='your_username'
# PYPSRP_PASSWORD='your_password'

host = os.environ.get('PYPSRP_HOST', '')
username = os.environ.get('PYPSRP_USERNAME', '')
password = os.environ.get('PYPSRP_PASSWORD', '')

if not all([host, username, password]):
    print("Please set PYPSRP_HOST, PYPSRP_USERNAME, and PYPSRP_PASSWORD environment variables to run this quickstart.")
else:
    try:
        # Establish a PowerShell RunspacePool connection
        with RunspacePool(
            server=host,
            username=username,
            password=password,
            # For self-signed certificates or non-verified hosts, use verify_ssl=False
            # connection_options={'verify_ssl': False, 'connection_timeout': 30}
        ) as pool:
            print(f"Connected to {host} successfully.")
            # Create a PowerShell pipeline
            ps = PowerShell(pool)
            
            # Add a script to execute
            ps.add_script("Get-Service -Name bits | Select-Object Name, Status, DisplayName")
            
            # Invoke the script and get the output
            output = ps.invoke()
            
            print("\n--- Command Output ---")
            if output:
                for item in output:
                    print(item)
            else:
                print("No output from command.")

            # Check for any error or warning streams from PowerShell
            if ps.streams.error:
                print("\n--- PowerShell Errors ---")
                for error in ps.streams.error:
                    print(error.message)
            if ps.streams.warning:
                print("\n--- PowerShell Warnings ---")
                for warning in ps.streams.warning:
                    print(warning.message)

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →