# pypsrp - Python PowerShell Remoting Protocol Client library
[](https://github.com/jborean93/pypsrp/actions/workflows/ci.yml)
[](https://codecov.io/gh/jborean93/pypsrp)
[](https://badge.fury.io/py/pypsrp)
pypsrp is a Python client for the PowerShell Remoting Protocol (PSRP) and
Windows Remote Management (WinRM) service. It allows your to execute commands
on a remote Windows host from any machine that can run Python.
This library exposes 4 different types of APIs;
* A simple client API that can copy files to and from the remote Windows host as well as execute processes and PowerShell scripts
* A WSMan interface to execute various WSMan calls like `Send`, `Create`, `Connect`, `Disconnect`, etc
* A Windows Remote Shell (WinRS) layer that executes cmd commands and executables using the base WinRM protocol
* A PowerShell Remoting Protocol (PSRP) layer allows you to create remote Runspace Pools and PowerShell pipelines
At a basic level, you can use this library to;
* Execute a cmd command
* Run another executable
* Execute PowerShell scripts
* Copy a file from the localhost to the remote Windows host
* Fetch a file from the remote Windows host to the localhost
* Create a Runspace Pool that contains one or multiple PowerShell pipelines and execute them asynchronously
* Support for a reference host base implementation of PSRP for interactive scripts
Currently this library only supports the WSMan transport method but is designed
to support SSH at some point in the future (PR's are welcome). By default it
supports the following authentication methods with WSMan;
* Basic
* Certificate
* NTLM
It also supports `Negotiate/Kerberos`, and `CredSSP` but require extra
libraries to be installed.
## Requirements
See `How to Install` for more details
* CPython 3.6+
* [cryptography](https://github.com/pyca/cryptography)
* [pyspnego](https://github.com/jborean93/pyspnego)
* [requests](https://github.com/requests/requests)
### Optional Requirements
The following Python libraries can be installed to add extra features that do
not come with the base package:
* [python-gssapi](https://github.com/pythongssapi/python-gssapi) for Kerberos authentication on Linux
* [pykrb5](https://github.com/jborean93/pykrb5) for Kerberos authentication on Linux
* [requests-credssp](https://github.com/jborean93/requests-credssp) for CredSSP authentication
## How to Install
To install pypsrp with all the basic features, run:
```bash
pip install pypsrp
```
### Kerberos Authentication
While pypsrp supports Kerberos authentication, it isn't included by default for
Linux hosts due to it's reliance on system packages to be present.
To install these packages, depending on your distribution, run one of the following script blocks.
For Debian/Ubuntu
```bash
# For Python 2
apt-get install gcc python-dev libkrb5-dev
# For Python 3
apt-get install gcc python3-dev libkrb5-dev
# To add NTLM to the GSSAPI SPNEGO auth run
apt-get install gss-ntlmssp
```
For RHEL/Centos
```bash
yum install gcc python-devel krb5-devel
# To add NTLM to the GSSAPI SPNEGO auth run
yum install gssntlmssp
```
For Fedora
```bash
dnf install gcc python-devel krb5-devel
# To add NTLM to the GSSAPI SPNEGO auth run
dnf install gssntlmssp
```
For Arch Linux
```bash
pacman -S gcc krb5
```
Once installed you can install the Python packages with
```bash
pip install pypsrp[kerberos]
```
Kerberos also needs to be configured to talk to the domain but that is outside
the scope of this page.
### CredSSP Authentication
Like Kerberos auth, CredSSP is supported but isn't included by default. To add
support for CredSSP auth try to run the following
```bash
pip install pypsrp[credssp]
```
If that fails you may need to update pip and setuptools to a newer version
`pip install -U pip setuptools`.
## How to Use
There are 3 main components that are in use within this library;
* `Transport`: Handles the raw transport of messages to and from the server
* `Shell`: Handles the WSMV or PSRP protocol details used to create the remote shell that processes are run on, uses `Connection` to send the details
* `Process`: Runs the process or script within a shell
### Connection
Currently only the connection that is supported is the WSMan protocol over HTTP
through `pypsrp.wsman.WSMan` and offers mostly all the same features in the
WSMV spec including;
* Basic, Certificate, Negotiate, Kerberos, and CredSSP authentication
* TLS encryption
* Message encryption with Negotiate, Kerberos, and CredSSP authentication
* Definable proxy
These are the options that can be used to setup `WSMan`;
* `server`: The hostname or IP address of the host to connect to
* `max_envelope_size`: The maximum envelope size, in bytes, that can be sent to the server, default is `153600`
* `operation_timeout`: The operation timeout, in seconds, of each WSMan operation, default is `20`. This should always be lower than `read_timeout`.
* `port`: The port to connect to, default is `5986` if `ssl=True` else `5985`
* `username`: The username to connect with, required for all auths except `certificate` and optionally required for `negotiate/kerberos`
* `password`: The password for `username`. Due to a bug on MacOS/Heimdal GSSAPI implementations, this will persist in the user's ccache when using Negotiate or Kerberos authentication, run `kdestroy` manually to remove this
* `ssl`: Whether to connect over `https` or `https`, default is `True`
* `path`: The WinRM path to connect to, default is `wsman`
* `auth`: The authentication protocol to use, default is `negotiate`, choices are `basic`, `certificate`, `negotiate`, `ntlm`, `kerberos`, `credssp`
* `cert_validation`: Whether to validate the server's SSL certificate, default is `True`. Can be `False` to not validate or a path to a PEM file of trusted certificates
* `connection_timeout`: The timeout for creating a HTTP connection, default is `30`
* `read_timeout`: The timeout for receiving a response from the server after a request has been made, default is `30`
* `encryption`: Controls the encryption settings, default is `auto`, choices are `auto`, `always`, `never`. Set to `always` to always run message encryption even over HTTPS, `never` to never use message encryption even over HTTP
* `proxy`: The proxy URL used to connect to the remote host
* `no_proxy`: Whether to ignore any environment proxy variable and connect directly to the host, default is `False`
* `locale`: The `wsmv:Locale` value to set on each WSMan request. This specifies the language in which the cleint wants response text to be translated, default is `en-US`
* `data_locale`: The `wsmv:DataLocale` value to set on each WSMan request. This specifies the format in which numerical data is presented in the response text, default is the value of `locale`
* `reconnection_retries`: Number of retries on a connection problem, default is `0`
* `reconnection_backoff`: Number of seconds to backoff in between reconnection attempts (first sleeps X, then sleeps 2*X, 4*X, 8*X, ...), default is `2.0`
* `certificate_key_pem`: The path to the certificate key used in `certificate` authentication
* `certificate_pem`: The path to the certificate used in `certificate` authentication
* `credssp_auth_mechanism`: The sub-auth mechanism used in CredSSP, default is `auto`, choices are `auto`, `ntlm`, or `kerberos`
* `credssp_disable_tlsv1_2`: Whether to used CredSSP auth over the insecure TLSv1.0, default is `False`
* `credssp_minimum_version`: The minimum CredSSP server version that the client will connect to, default is `2`
* `negotiate_delegate`: Whether to negotiate the credential to the host, default is `False`. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set
* `negotiate_hostname_override`: The hostname used to calculate the host SPN when authenticating the host with Kerberos auth. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set
* `negotiate_send_cbt`: Whether to binding the channel binding token (HTTPS only) to the auth or ignore, default is `True`
* `negotiate_service`: Override the service part of the calculated SPN used when authenticating the server, default is `WSMAN`. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set
When running over HTTP, this library will enforce encryption by default but if
that is not supported (Basic auth) or isn't available on the host then either
use HTTPS or disable encryption with `encryption="never"`.
There are plans to add support for SSH as a connection but this still needs to
be implemented. SSH will work on hosts that are running PowerShell Core but
not the standard PowerShell.
### Shell
There are two shells that can be used in this library, `pypsrp.shell.WinRS` and
`pypsrp.powershell.RunspacePool`.
`WinRS` is a cmd shell that can be used to issue cmd commands, including but
not limited to other executables. Here are the options that can be used to
configure a `WinRS` shell;
* `wsman`: WinRS only works over WSMan, so this is the `pypsrp.wsman.WSMan` object to run the commands over
* `resource_uri`: The resource uri of the shell, defaults to `http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd`
* `id`: The ID if the shell, this should be kept as `None` as it is created dynamically by the server
* `input_streams`: The input stream(s) of the shell, default is `stdin`
* `output_streams`: The output stream(s) of the shell, default is `stdout, stderr`
* `codepage`: The codepage of the shell, default is the default of the host
* `environment`: A dictionary of environment key/values to set for the remote shell
* `idle_time_out`: THe idle timeout in seconds of the shell
* `lifetime`: The total lifetime of the shell
* `name`: The name (description only) of the shell
* `no_profile`: Whether to create the shell with the user profile loaded or not
* `working_directory`: The default working directory of the created shell
`RunspacePool` is a shell used by the PSRP protocol, it is designed to be a
close implementation of the .NET
[System.Management.Automation.Runspaces.RunspacePool](https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.runspacepool?view=powershellsdk-1.1.0)
class. The methods and properties are similar and can mostly do the same thing.
Here are the options that can be used to configure a `RunspacePool` shell;
* `connection`: The connection object used by the RunspacePool to send commands to the remote server, currently only supports `WSMan`
* `apartment_state`: The int value of `pypsrp.complex_objects.ApartmentState` for the remote thread, default is `UNKNOWN`
* `thread_options`: The int value of `pypsrp.complex_objects.ThreadOptions` that specifies the type of thread to create, default is `DEFAULT`
* `host`: The local host info implementation, default is no host
* `configuration_name`: The configuration name to connect to, default is `Microsoft.PowerShell` and can be used to specify the Just Enough Administration (JEA) to connect to
* `min_runspaces`: The minimuum number of runspaces that a pool can hold, default is 1
* `max_runspaces`: The maximum number of runspaces that a pool can hold. Each PowerShell pipeline is run in a single Runspace, default is 1
* `session_key_timeout_ms`: The maximum time to wait for a session key transfer from the server
### Process
There are two process objects that can be used, `pypsrp.shell.Process` for the
`WinRS` shell and `pypsrp.powershell.PowerShell` for the `RunspacePool` shell.
These objects are ultimately used to execute commands, processes, or scripts on
the remote host.
`Process` is used with the `WinRS` shell to execute a cmd command or another
executable. The following options are used to configure the `Process` object;
* `shell`: The `WinRS` shell the process is run over
* `executable`: The executable or command to run
* `arguments`: A list of arguments to the executable or command, default is no arguments
* `id`: The ID of the created command, if not specified then this is dynamically created
* `no_shell`: Whether to create a command in the cmd shell or bypass it, default is `False`. If `True` then the executable must be the full path to the exe. This only works on older OS' before 2012 R2 (not including)
To execute the process, call `.invoke()`, the `stdout`, `stderr`, and `rc`
properties contain the output of the command once complete.
`PowerShell` is used by the PSRP protocol, it is designed to be a close
implementation of the
[System.Management.Automation.PowerShell](https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.powershell?view=powershellsdk-1.1.0)
class. The methods and properties are similar and can mostly do the same thing.
Here are the options that can be used to configure a `PowerShell` process;
* `runspace_pool`: The `RunspacePool` object to run the `PowerShell` process on
To execute the process, call `.invoke()`, the `output`, `had_erros`, and
`streams` contains the execution status and output information of the process.
Before invoke can be called, cmdlets or scripts must be added. These can be
done with the following methods;
* `add_script`: Add a raw PowerShell script to the pending commands
* `add_cmdlet`: Add a cmdlet to the pending commands
* `add_parameters`: Add a dictionary of key/value parameters to the last added command
* `add_argument`: Add a value argument to the last added command
* `add_statement`: Set the last command/script to be the end of that pipeline so the next command/script is like a newline
See the examples below for more details.
### Examples
How to use the high level client API
```python
from pypsrp.client import Client
# this takes in the same kwargs as the WSMan object
with Client("server", username="user", password="password") as client:
# execute a cmd command
stdout, stderr, rc = client.execute_cmd("dir")
stdout, stderr, rc = client.execute_cmd("powershell.exe gci $pwd")
sanitised_stderr = client.sanitise_clixml(stderr)
# execute a PowerShell script
output, streams, had_errors = client.execute_ps('''$path = "%s"
if (Test-Path -Path $path) {
Remove-Item -Path $path -Force -Recurse
}
New-Item -Path $path -ItemType Directory''' % path)
output, streams, had_errors = client.execute_ps("New-Item -Path C:\\temp\\folder -ItemType Directory")
# copy a file from the local host to the remote host
client.copy("~/file.txt", "C:\\temp\\file.txt")
# fetch a file from the remote host to the local host
client.fetch("C:\\temp\\file.txt", "~/file.txt")
```
How to use WinRS/Process to execute a command
```python
from pypsrp.shell import Process, SignalCode, WinRS
from pypsrp.wsman import WSMan
# creates a http connection with no encryption and basic auth
wsman = WSMan("server", ssl=False, auth="basic", encryption="never",
username="vagrant", password="vagrant")
with wsman, WinRS(wsman) as shell:
process = Process(shell, "dir")
process.invoke()
process.signal(SignalCode.CTRL_C)
# execute a process with arguments in the background
process = Process(shell, "powershell", ["gci", "$pwd"])
process.begin_invoke() # start the invocation and return immediately
process.poll_invoke() # update the output stream
process.end_invoke() # finally wait until the process is finished
process.signal(SignalCode.CTRL_C)
```
How to use RunspacePool/PowerShell to execute a PowerShell script/command
```python
from pypsrp.powershell import PowerShell, RunspacePool
from pypsrp.wsman import WSMan
# creates a https connection with explicit kerberos auth and implicit credentials
wsman = WSMan("server", auth="kerberos", cert_validation=False))
with wsman, RunspacePool(wsman) as pool:
# execute 'Get-Process | Select-Object Name'
ps = PowerShell(pool)
ps.add_cmdlet("Get-Process").add_cmdlet("Select-Object").add_argument("Name")
output = ps.invoke()
# execute 'Get-Process | Select-Object -Property Name'
ps.add_cmdlet("Get-Process").add_cmdlet("Select-Object")
ps.add_parameter("Property", "Name")
ps.begin_invoke() # execute process in the background
ps.poll_invoke() # update the output streams
ps.end_invoke() # wait until the process is finished
# execute 'Get-Process | Select-Object -Property Name; Get-Service audiosrv'
ps.add_cmdlet("Get-Process").add_cmdlet("Select-Object").add_parameter("Property", "Name")
ps.add_statement()
ps.add_cmdlet("Get-Service").add_argument("audiosrc")
ps.invoke()
# execute a PowerShell script with input being sent
script = '''begin {
$DebugPreference = "Continue"
Write-Debug -Message "begin"
} process {
Write-Output -InputObject $input
} end {
Write-Debug -Message "end"
}
'''
ps.add_script(script)
ps.invoke(["string", 1])
print(ps.output)
print(ps.streams.debug)
```
## Logging
This library takes advantage of the Python logging configuration and messages
are logged to the `pypsrp` named logger as well as `pypsrp.*` where `*` is each
Python script in the `pypsrp` directory.
An easy way to turn on logging for the entire library is to create the
following JSON file and run your script with
`PYPSRP_LOG_CFG=log.json python script.py` (this does not work with Python
2.6).
```json
{
"version": 1,
"disable_existing_loggers": false,
"formatters": {
"simple": {
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
}
},
"handlers": {
"console": {
"class": "logging.StreamHandler",
"level": "DEBUG",
"formatter": "simple",
"stream": "ext://sys.stdout"
}
},
"loggers": {
"pypsrp": {
"level": "DEBUG",
"handlers": ["console"],
"propagate": "no"
}
}
}
```
You can adjust the log level by changing the level value in `logger` to `INFO`.
_Note: `DEBUG` contains a lot of information and will output all the messages
sent to and from the client. This can have the side effect of leaking sensitive
information and should only be used for debugging purposes._
## Testing
Any changes are more than welcome in pull request form, you can run the current
test suite with tox like so;
```bash
# make sure tox is installed
pip install tox
# run the tox suite
tox
# or run the test manually for the current Python environment
py.test -v --pep8 --cov pypsrp --cov-report term-missing
```
A lot of the tests either simulate a remote Windows host but you can also run a
lot of them against a real Windows host. To do this, set the following
environment variables before running the tests;
* `PYPSRP_SERVER`: The hostname or IP of the remote host
* `PYPSRP_USERNAME`: The username to connect with
* `PYPSRP_PASSWORD`: The password to connect with
* `PYPSRR_PORT`: The port to connect with (default: `5986`)
* `PYPSRP_AUTH`: The authentication protocol to auth with (default: `negotiate`)
There are further integration tests that require a specific host setup to run
correctly. You can use `Vagrant` to set this host up. This is done by running
the following commands;
```bash
# download the Vagrant box and start it up based on the Vagrantfile
vagrant up
# once the above script is complete run the following
vagrant ssh # password is vagrant
powershell.exe
Register-PSSessionConfiguration -Path "C:\Users\vagrant\Documents\JEARoleSettings.pssc" -Name JEARole -Force
$sec_pass = ConvertTo-SecureString -String "vagrant" -AsPlainText -Force
$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList "vagrant", $sec_pass
$thumbprint = (Get-ChildItem -Path Cert:\LocalMachine\TrustedPeople)[0].Thumbprint
New-Item -Path WSMan:\localhost\ClientCertificate `
-Subject "vagrant@localhost" `
-URI * `
-Issuer $thumbprint `
-Credential $credential `
-Force
# exit the remote PowerShell session
exit
# exist the SSH session
exit
```
Once complete, set the following environment variables to run the integration
tests;
* `PYPSRP_RUN_INTEGRATION`: To any value
* `PYPSRP_SERVER`: Set to `127.0.0.1`
* `PYPSRP_USERNAME`: Set to `vagrant`
* `PYPSRP_PASSWORD`: Set to `vagrant`
* `PYPSRP_HTTP_PORT`: Set to `55985`
* `PYPSRP_HTTPS_PORT`: Set to `55986`
* `PYPSRP_CERT_DIR`: Set to the full path of the project directory
From here you can run the normal test suite and it will run all the integration
tests.
## Backlog
* Look at implementing the following transport options
* Named pipes
* SSH
* Update CI to use named pipes for integration tests
* Add Ansible playbook for better integration tests
* Improved serialization between Python and .NET objects
* Live interactive console for PSRP
Raw data
{
"_id": null,
"home_page": "https://github.com/jborean93/pypsrp",
"name": "pypsrp",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "winrm,psrp,winrs,windows,powershell",
"author": "Jordan Borean",
"author_email": "jborean93@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/57/da/3d9295972c20624c79843c1c14cf06fc6b0575ba786c1f72d6ca5bc5b9d5/pypsrp-0.8.1.tar.gz",
"platform": "",
"description": "# pypsrp - Python PowerShell Remoting Protocol Client library\n\n[](https://github.com/jborean93/pypsrp/actions/workflows/ci.yml)\n[](https://codecov.io/gh/jborean93/pypsrp)\n[](https://badge.fury.io/py/pypsrp)\n\npypsrp is a Python client for the PowerShell Remoting Protocol (PSRP) and\nWindows Remote Management (WinRM) service. It allows your to execute commands\non a remote Windows host from any machine that can run Python.\n\nThis library exposes 4 different types of APIs;\n\n* A simple client API that can copy files to and from the remote Windows host as well as execute processes and PowerShell scripts\n* A WSMan interface to execute various WSMan calls like `Send`, `Create`, `Connect`, `Disconnect`, etc\n* A Windows Remote Shell (WinRS) layer that executes cmd commands and executables using the base WinRM protocol\n* A PowerShell Remoting Protocol (PSRP) layer allows you to create remote Runspace Pools and PowerShell pipelines\n\nAt a basic level, you can use this library to;\n\n* Execute a cmd command\n* Run another executable\n* Execute PowerShell scripts\n* Copy a file from the localhost to the remote Windows host\n* Fetch a file from the remote Windows host to the localhost\n* Create a Runspace Pool that contains one or multiple PowerShell pipelines and execute them asynchronously\n* Support for a reference host base implementation of PSRP for interactive scripts\n\nCurrently this library only supports the WSMan transport method but is designed\nto support SSH at some point in the future (PR's are welcome). By default it\nsupports the following authentication methods with WSMan;\n\n* Basic\n* Certificate\n* NTLM\n\nIt also supports `Negotiate/Kerberos`, and `CredSSP` but require extra\nlibraries to be installed.\n\n\n## Requirements\n\nSee `How to Install` for more details\n\n* CPython 3.6+\n* [cryptography](https://github.com/pyca/cryptography)\n* [pyspnego](https://github.com/jborean93/pyspnego)\n* [requests](https://github.com/requests/requests)\n\n### Optional Requirements\n\nThe following Python libraries can be installed to add extra features that do\nnot come with the base package:\n\n* [python-gssapi](https://github.com/pythongssapi/python-gssapi) for Kerberos authentication on Linux\n* [pykrb5](https://github.com/jborean93/pykrb5) for Kerberos authentication on Linux\n* [requests-credssp](https://github.com/jborean93/requests-credssp) for CredSSP authentication\n\n\n## How to Install\n\nTo install pypsrp with all the basic features, run:\n\n```bash\npip install pypsrp\n```\n\n### Kerberos Authentication\n\nWhile pypsrp supports Kerberos authentication, it isn't included by default for\nLinux hosts due to it's reliance on system packages to be present.\n\nTo install these packages, depending on your distribution, run one of the following script blocks.\n\nFor Debian/Ubuntu\n\n```bash\n# For Python 2\napt-get install gcc python-dev libkrb5-dev\n\n# For Python 3\napt-get install gcc python3-dev libkrb5-dev\n\n# To add NTLM to the GSSAPI SPNEGO auth run\napt-get install gss-ntlmssp\n```\n\nFor RHEL/Centos\n\n```bash\nyum install gcc python-devel krb5-devel\n\n# To add NTLM to the GSSAPI SPNEGO auth run\nyum install gssntlmssp\n```\n\nFor Fedora\n\n```bash\ndnf install gcc python-devel krb5-devel\n\n# To add NTLM to the GSSAPI SPNEGO auth run\ndnf install gssntlmssp\n```\n\nFor Arch Linux\n\n```bash\npacman -S gcc krb5\n```\n\nOnce installed you can install the Python packages with\n\n```bash\npip install pypsrp[kerberos]\n```\n\nKerberos also needs to be configured to talk to the domain but that is outside\nthe scope of this page.\n\n### CredSSP Authentication\n\nLike Kerberos auth, CredSSP is supported but isn't included by default. To add\nsupport for CredSSP auth try to run the following\n\n```bash\npip install pypsrp[credssp]\n```\n\nIf that fails you may need to update pip and setuptools to a newer version\n`pip install -U pip setuptools`.\n\n\n## How to Use\n\nThere are 3 main components that are in use within this library;\n\n* `Transport`: Handles the raw transport of messages to and from the server\n* `Shell`: Handles the WSMV or PSRP protocol details used to create the remote shell that processes are run on, uses `Connection` to send the details\n* `Process`: Runs the process or script within a shell\n\n### Connection\n\nCurrently only the connection that is supported is the WSMan protocol over HTTP\nthrough `pypsrp.wsman.WSMan` and offers mostly all the same features in the\nWSMV spec including;\n\n* Basic, Certificate, Negotiate, Kerberos, and CredSSP authentication\n* TLS encryption\n* Message encryption with Negotiate, Kerberos, and CredSSP authentication\n* Definable proxy\n\nThese are the options that can be used to setup `WSMan`;\n\n* `server`: The hostname or IP address of the host to connect to\n* `max_envelope_size`: The maximum envelope size, in bytes, that can be sent to the server, default is `153600`\n* `operation_timeout`: The operation timeout, in seconds, of each WSMan operation, default is `20`. This should always be lower than `read_timeout`.\n* `port`: The port to connect to, default is `5986` if `ssl=True` else `5985`\n* `username`: The username to connect with, required for all auths except `certificate` and optionally required for `negotiate/kerberos`\n* `password`: The password for `username`. Due to a bug on MacOS/Heimdal GSSAPI implementations, this will persist in the user's ccache when using Negotiate or Kerberos authentication, run `kdestroy` manually to remove this\n* `ssl`: Whether to connect over `https` or `https`, default is `True`\n* `path`: The WinRM path to connect to, default is `wsman`\n* `auth`: The authentication protocol to use, default is `negotiate`, choices are `basic`, `certificate`, `negotiate`, `ntlm`, `kerberos`, `credssp`\n* `cert_validation`: Whether to validate the server's SSL certificate, default is `True`. Can be `False` to not validate or a path to a PEM file of trusted certificates\n* `connection_timeout`: The timeout for creating a HTTP connection, default is `30`\n* `read_timeout`: The timeout for receiving a response from the server after a request has been made, default is `30`\n* `encryption`: Controls the encryption settings, default is `auto`, choices are `auto`, `always`, `never`. Set to `always` to always run message encryption even over HTTPS, `never` to never use message encryption even over HTTP\n* `proxy`: The proxy URL used to connect to the remote host\n* `no_proxy`: Whether to ignore any environment proxy variable and connect directly to the host, default is `False`\n* `locale`: The `wsmv:Locale` value to set on each WSMan request. This specifies the language in which the cleint wants response text to be translated, default is `en-US`\n* `data_locale`: The `wsmv:DataLocale` value to set on each WSMan request. This specifies the format in which numerical data is presented in the response text, default is the value of `locale`\n* `reconnection_retries`: Number of retries on a connection problem, default is `0`\n* `reconnection_backoff`: Number of seconds to backoff in between reconnection attempts (first sleeps X, then sleeps 2*X, 4*X, 8*X, ...), default is `2.0`\n* `certificate_key_pem`: The path to the certificate key used in `certificate` authentication\n* `certificate_pem`: The path to the certificate used in `certificate` authentication\n* `credssp_auth_mechanism`: The sub-auth mechanism used in CredSSP, default is `auto`, choices are `auto`, `ntlm`, or `kerberos`\n* `credssp_disable_tlsv1_2`: Whether to used CredSSP auth over the insecure TLSv1.0, default is `False`\n* `credssp_minimum_version`: The minimum CredSSP server version that the client will connect to, default is `2`\n* `negotiate_delegate`: Whether to negotiate the credential to the host, default is `False`. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set\n* `negotiate_hostname_override`: The hostname used to calculate the host SPN when authenticating the host with Kerberos auth. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set\n* `negotiate_send_cbt`: Whether to binding the channel binding token (HTTPS only) to the auth or ignore, default is `True`\n* `negotiate_service`: Override the service part of the calculated SPN used when authenticating the server, default is `WSMAN`. This is only valid if `negotiate` auth negotiated Kerberos or `kerberos` was explicitly set\n\nWhen running over HTTP, this library will enforce encryption by default but if\nthat is not supported (Basic auth) or isn't available on the host then either\nuse HTTPS or disable encryption with `encryption=\"never\"`.\n\nThere are plans to add support for SSH as a connection but this still needs to\nbe implemented. SSH will work on hosts that are running PowerShell Core but\nnot the standard PowerShell.\n\n### Shell\n\nThere are two shells that can be used in this library, `pypsrp.shell.WinRS` and\n`pypsrp.powershell.RunspacePool`.\n\n`WinRS` is a cmd shell that can be used to issue cmd commands, including but\nnot limited to other executables. Here are the options that can be used to\nconfigure a `WinRS` shell;\n\n* `wsman`: WinRS only works over WSMan, so this is the `pypsrp.wsman.WSMan` object to run the commands over\n* `resource_uri`: The resource uri of the shell, defaults to `http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd`\n* `id`: The ID if the shell, this should be kept as `None` as it is created dynamically by the server\n* `input_streams`: The input stream(s) of the shell, default is `stdin`\n* `output_streams`: The output stream(s) of the shell, default is `stdout, stderr`\n* `codepage`: The codepage of the shell, default is the default of the host\n* `environment`: A dictionary of environment key/values to set for the remote shell\n* `idle_time_out`: THe idle timeout in seconds of the shell\n* `lifetime`: The total lifetime of the shell\n* `name`: The name (description only) of the shell\n* `no_profile`: Whether to create the shell with the user profile loaded or not\n* `working_directory`: The default working directory of the created shell\n\n`RunspacePool` is a shell used by the PSRP protocol, it is designed to be a\nclose implementation of the .NET\n[System.Management.Automation.Runspaces.RunspacePool](https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.runspacepool?view=powershellsdk-1.1.0)\nclass. The methods and properties are similar and can mostly do the same thing.\nHere are the options that can be used to configure a `RunspacePool` shell;\n\n* `connection`: The connection object used by the RunspacePool to send commands to the remote server, currently only supports `WSMan`\n* `apartment_state`: The int value of `pypsrp.complex_objects.ApartmentState` for the remote thread, default is `UNKNOWN`\n* `thread_options`: The int value of `pypsrp.complex_objects.ThreadOptions` that specifies the type of thread to create, default is `DEFAULT`\n* `host`: The local host info implementation, default is no host\n* `configuration_name`: The configuration name to connect to, default is `Microsoft.PowerShell` and can be used to specify the Just Enough Administration (JEA) to connect to\n* `min_runspaces`: The minimuum number of runspaces that a pool can hold, default is 1\n* `max_runspaces`: The maximum number of runspaces that a pool can hold. Each PowerShell pipeline is run in a single Runspace, default is 1\n* `session_key_timeout_ms`: The maximum time to wait for a session key transfer from the server\n\n### Process\n\nThere are two process objects that can be used, `pypsrp.shell.Process` for the\n`WinRS` shell and `pypsrp.powershell.PowerShell` for the `RunspacePool` shell.\nThese objects are ultimately used to execute commands, processes, or scripts on\nthe remote host.\n\n`Process` is used with the `WinRS` shell to execute a cmd command or another\nexecutable. The following options are used to configure the `Process` object;\n\n* `shell`: The `WinRS` shell the process is run over\n* `executable`: The executable or command to run\n* `arguments`: A list of arguments to the executable or command, default is no arguments\n* `id`: The ID of the created command, if not specified then this is dynamically created\n* `no_shell`: Whether to create a command in the cmd shell or bypass it, default is `False`. If `True` then the executable must be the full path to the exe. This only works on older OS' before 2012 R2 (not including)\n\nTo execute the process, call `.invoke()`, the `stdout`, `stderr`, and `rc`\nproperties contain the output of the command once complete.\n\n`PowerShell` is used by the PSRP protocol, it is designed to be a close\nimplementation of the\n[System.Management.Automation.PowerShell](https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.powershell?view=powershellsdk-1.1.0)\nclass. The methods and properties are similar and can mostly do the same thing.\nHere are the options that can be used to configure a `PowerShell` process;\n\n* `runspace_pool`: The `RunspacePool` object to run the `PowerShell` process on\n\nTo execute the process, call `.invoke()`, the `output`, `had_erros`, and\n`streams` contains the execution status and output information of the process.\nBefore invoke can be called, cmdlets or scripts must be added. These can be\ndone with the following methods;\n\n* `add_script`: Add a raw PowerShell script to the pending commands\n* `add_cmdlet`: Add a cmdlet to the pending commands\n* `add_parameters`: Add a dictionary of key/value parameters to the last added command\n* `add_argument`: Add a value argument to the last added command\n* `add_statement`: Set the last command/script to be the end of that pipeline so the next command/script is like a newline\n\nSee the examples below for more details.\n\n### Examples\n\nHow to use the high level client API\n\n```python\nfrom pypsrp.client import Client\n\n# this takes in the same kwargs as the WSMan object\nwith Client(\"server\", username=\"user\", password=\"password\") as client:\n\n # execute a cmd command\n stdout, stderr, rc = client.execute_cmd(\"dir\")\n\n stdout, stderr, rc = client.execute_cmd(\"powershell.exe gci $pwd\")\n sanitised_stderr = client.sanitise_clixml(stderr)\n\n # execute a PowerShell script\n output, streams, had_errors = client.execute_ps('''$path = \"%s\"\nif (Test-Path -Path $path) {\n Remove-Item -Path $path -Force -Recurse\n}\nNew-Item -Path $path -ItemType Directory''' % path)\n output, streams, had_errors = client.execute_ps(\"New-Item -Path C:\\\\temp\\\\folder -ItemType Directory\")\n\n # copy a file from the local host to the remote host\n client.copy(\"~/file.txt\", \"C:\\\\temp\\\\file.txt\")\n\n # fetch a file from the remote host to the local host\n client.fetch(\"C:\\\\temp\\\\file.txt\", \"~/file.txt\")\n```\n\nHow to use WinRS/Process to execute a command\n\n\n```python\nfrom pypsrp.shell import Process, SignalCode, WinRS\nfrom pypsrp.wsman import WSMan\n\n# creates a http connection with no encryption and basic auth\nwsman = WSMan(\"server\", ssl=False, auth=\"basic\", encryption=\"never\",\n username=\"vagrant\", password=\"vagrant\")\n\nwith wsman, WinRS(wsman) as shell:\n process = Process(shell, \"dir\")\n process.invoke()\n process.signal(SignalCode.CTRL_C)\n\n # execute a process with arguments in the background\n process = Process(shell, \"powershell\", [\"gci\", \"$pwd\"])\n process.begin_invoke() # start the invocation and return immediately\n process.poll_invoke() # update the output stream\n process.end_invoke() # finally wait until the process is finished\n process.signal(SignalCode.CTRL_C)\n```\n\nHow to use RunspacePool/PowerShell to execute a PowerShell script/command\n\n```python\nfrom pypsrp.powershell import PowerShell, RunspacePool\nfrom pypsrp.wsman import WSMan\n\n# creates a https connection with explicit kerberos auth and implicit credentials\nwsman = WSMan(\"server\", auth=\"kerberos\", cert_validation=False))\n\nwith wsman, RunspacePool(wsman) as pool:\n # execute 'Get-Process | Select-Object Name'\n ps = PowerShell(pool)\n ps.add_cmdlet(\"Get-Process\").add_cmdlet(\"Select-Object\").add_argument(\"Name\")\n output = ps.invoke()\n\n # execute 'Get-Process | Select-Object -Property Name'\n ps.add_cmdlet(\"Get-Process\").add_cmdlet(\"Select-Object\")\n ps.add_parameter(\"Property\", \"Name\")\n ps.begin_invoke() # execute process in the background\n ps.poll_invoke() # update the output streams\n ps.end_invoke() # wait until the process is finished\n\n # execute 'Get-Process | Select-Object -Property Name; Get-Service audiosrv'\n ps.add_cmdlet(\"Get-Process\").add_cmdlet(\"Select-Object\").add_parameter(\"Property\", \"Name\")\n ps.add_statement()\n ps.add_cmdlet(\"Get-Service\").add_argument(\"audiosrc\")\n ps.invoke()\n\n # execute a PowerShell script with input being sent\n script = '''begin {\n $DebugPreference = \"Continue\"\n Write-Debug -Message \"begin\"\n} process {\n Write-Output -InputObject $input\n} end {\n Write-Debug -Message \"end\"\n}\n'''\n ps.add_script(script)\n ps.invoke([\"string\", 1])\n print(ps.output)\n print(ps.streams.debug)\n```\n\n\n## Logging\n\nThis library takes advantage of the Python logging configuration and messages\nare logged to the `pypsrp` named logger as well as `pypsrp.*` where `*` is each\nPython script in the `pypsrp` directory.\n\nAn easy way to turn on logging for the entire library is to create the\nfollowing JSON file and run your script with\n`PYPSRP_LOG_CFG=log.json python script.py` (this does not work with Python\n2.6).\n\n```json\n{\n \"version\": 1,\n \"disable_existing_loggers\": false,\n \"formatters\": {\n \"simple\": {\n \"format\": \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n }\n },\n\n \"handlers\": {\n \"console\": {\n \"class\": \"logging.StreamHandler\",\n \"level\": \"DEBUG\",\n \"formatter\": \"simple\",\n \"stream\": \"ext://sys.stdout\"\n }\n },\n\n \"loggers\": {\n \"pypsrp\": {\n \"level\": \"DEBUG\",\n \"handlers\": [\"console\"],\n \"propagate\": \"no\"\n }\n }\n}\n```\n\nYou can adjust the log level by changing the level value in `logger` to `INFO`.\n\n_Note: `DEBUG` contains a lot of information and will output all the messages\nsent to and from the client. This can have the side effect of leaking sensitive\ninformation and should only be used for debugging purposes._\n\n\n## Testing\n\nAny changes are more than welcome in pull request form, you can run the current\ntest suite with tox like so;\n\n```bash\n# make sure tox is installed\npip install tox\n\n# run the tox suite\ntox\n\n# or run the test manually for the current Python environment\npy.test -v --pep8 --cov pypsrp --cov-report term-missing\n```\n\nA lot of the tests either simulate a remote Windows host but you can also run a\nlot of them against a real Windows host. To do this, set the following\nenvironment variables before running the tests;\n\n* `PYPSRP_SERVER`: The hostname or IP of the remote host\n* `PYPSRP_USERNAME`: The username to connect with\n* `PYPSRP_PASSWORD`: The password to connect with\n* `PYPSRR_PORT`: The port to connect with (default: `5986`)\n* `PYPSRP_AUTH`: The authentication protocol to auth with (default: `negotiate`)\n\nThere are further integration tests that require a specific host setup to run\ncorrectly. You can use `Vagrant` to set this host up. This is done by running\nthe following commands;\n\n```bash\n# download the Vagrant box and start it up based on the Vagrantfile\nvagrant up\n\n# once the above script is complete run the following\nvagrant ssh # password is vagrant\n\npowershell.exe\nRegister-PSSessionConfiguration -Path \"C:\\Users\\vagrant\\Documents\\JEARoleSettings.pssc\" -Name JEARole -Force\n\n$sec_pass = ConvertTo-SecureString -String \"vagrant\" -AsPlainText -Force\n$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList \"vagrant\", $sec_pass\n$thumbprint = (Get-ChildItem -Path Cert:\\LocalMachine\\TrustedPeople)[0].Thumbprint\n\nNew-Item -Path WSMan:\\localhost\\ClientCertificate `\n -Subject \"vagrant@localhost\" `\n -URI * `\n -Issuer $thumbprint `\n -Credential $credential `\n -Force\n\n\n# exit the remote PowerShell session\nexit\n\n# exist the SSH session\nexit\n```\n\nOnce complete, set the following environment variables to run the integration\ntests;\n\n* `PYPSRP_RUN_INTEGRATION`: To any value\n* `PYPSRP_SERVER`: Set to `127.0.0.1`\n* `PYPSRP_USERNAME`: Set to `vagrant`\n* `PYPSRP_PASSWORD`: Set to `vagrant`\n* `PYPSRP_HTTP_PORT`: Set to `55985`\n* `PYPSRP_HTTPS_PORT`: Set to `55986`\n* `PYPSRP_CERT_DIR`: Set to the full path of the project directory\n\nFrom here you can run the normal test suite and it will run all the integration\ntests.\n\n\n## Backlog\n\n* Look at implementing the following transport options\n * Named pipes\n * SSH\n* Update CI to use named pipes for integration tests\n* Add Ansible playbook for better integration tests\n* Improved serialization between Python and .NET objects\n* Live interactive console for PSRP\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PowerShell Remoting Protocol and WinRM for Python",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/jborean93/pypsrp"
},
"split_keywords": [
"winrm",
"psrp",
"winrs",
"windows",
"powershell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9deccd0d634f31e49fa260b0fa813b9b52c97ed52f3fe03e22da290b9a3bcbd9",
"md5": "1b9cd53685e93025c2bced10e53ecd4d",
"sha256": "0101345ceb415896fed9b056e7b77d65312089ddc73c4286247ccf1859d4bc4d"
},
"downloads": -1,
"filename": "pypsrp-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b9cd53685e93025c2bced10e53ecd4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 88404,
"upload_time": "2022-02-21T20:07:03",
"upload_time_iso_8601": "2022-02-21T20:07:03.351183Z",
"url": "https://files.pythonhosted.org/packages/9d/ec/cd0d634f31e49fa260b0fa813b9b52c97ed52f3fe03e22da290b9a3bcbd9/pypsrp-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "57da3d9295972c20624c79843c1c14cf06fc6b0575ba786c1f72d6ca5bc5b9d5",
"md5": "55d346022eafdd9cc825e4ad111a98ae",
"sha256": "f5500acd11dfe742d51b7fbb61321ba721038a300d67763dc52babe709db65e7"
},
"downloads": -1,
"filename": "pypsrp-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "55d346022eafdd9cc825e4ad111a98ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 385839,
"upload_time": "2022-02-21T20:07:05",
"upload_time_iso_8601": "2022-02-21T20:07:05.597044Z",
"url": "https://files.pythonhosted.org/packages/57/da/3d9295972c20624c79843c1c14cf06fc6b0575ba786c1f72d6ca5bc5b9d5/pypsrp-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-02-21 20:07:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jborean93",
"github_project": "pypsrp",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pypsrp"
}
JSON
