| Name | pywinrm JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | Python library for Windows Remote Management |
| upload_time | 2024-07-16 19:32:05 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Copyright (c) 2013 Alexey Diyan 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. |
| keywords |
winrm
ws-man
devops
ws-management
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# pywinrm
pywinrm is a Python client for the Windows Remote Management (WinRM) service.
It allows you to invoke commands on target Windows machines from any machine
that can run Python.
[](https://github.com/diyan/pywinrm/blob/master/LICENSE)
[](https://github.com/diyan/pywinrm/actions/workflows/ci.yml)
[](https://coveralls.io/r/diyan/pywinrm)
[](https://pypi.python.org/pypi/pywinrm)
WinRM allows you to perform various management tasks remotely. These include,
but are not limited to: running batch scripts, powershell scripts, and fetching
WMI variables.
Used by [Ansible](https://www.ansible.com/) for Windows support.
For more information on WinRM, please visit
[Microsoft's WinRM site](http://msdn.microsoft.com/en-us/library/aa384426.aspx).
## Requirements
* Linux, Mac OS X or Windows
* CPython 3.8+ or PyPy3
* [requests-kerberos](http://pypi.python.org/pypi/requests-kerberos) and [requests-credssp](https://github.com/jborean93/requests-credssp) is optional
## Installation
### To install pywinrm with support for basic, certificate, and NTLM auth, simply
```bash
$ pip install pywinrm
```
### To use Kerberos authentication you need these optional dependencies
```bash
# for Debian/Ubuntu/etc:
$ sudo apt-get install gcc python3-dev libkrb5-dev
$ pip install pywinrm[kerberos]
# for RHEL/CentOS/etc:
$ sudo dnf install gcc krb5-devel krb5-workstation python3-devel
$ pip install pywinrm[kerberos]
```
### To use CredSSP authentication you need these optional dependencies
```bash
$ pip install pywinrm[credssp]
```
## Example Usage
### Run a process on a remote host
```python
import winrm
s = winrm.Session('windows-host.example.com', auth=('john.smith', 'secret'))
r = s.run_cmd('ipconfig', ['/all'])
>>> r.status_code
0
>>> r.std_out
Windows IP Configuration
Host Name . . . . . . . . . . . . : WINDOWS-HOST
Primary Dns Suffix . . . . . . . :
Node Type . . . . . . . . . . . . : Hybrid
IP Routing Enabled. . . . . . . . : No
WINS Proxy Enabled. . . . . . . . : No
...
>>> r.std_err
```
NOTE: pywinrm will try and guess the correct endpoint url from the following formats:
- windows-host -> http://windows-host:5985/wsman
- windows-host:1111 -> http://windows-host:1111/wsman
- http://windows-host -> http://windows-host:5985/wsman
- http://windows-host:1111 -> http://windows-host:1111/wsman
- http://windows-host:1111/wsman -> http://windows-host:1111/wsman
### Run Powershell script on remote host
```python
import winrm
ps_script = """$strComputer = $Host
Clear
$RAM = WmiObject Win32_ComputerSystem
$MB = 1048576
"Installed Memory: " + [int]($RAM.TotalPhysicalMemory /$MB) + " MB" """
s = winrm.Session('windows-host.example.com', auth=('john.smith', 'secret'))
r = s.run_ps(ps_script)
>>> r.status_code
0
>>> r.std_out
Installed Memory: 3840 MB
>>> r.std_err
```
Powershell scripts will be base64 UTF16 little-endian encoded prior to sending to the Windows host. Error messages are converted from the Powershell CLIXML format to a human readable format as a convenience.
### Run process with low-level API with domain user, disabling HTTPS cert validation
```python
from winrm.protocol import Protocol
p = Protocol(
endpoint='https://windows-host:5986/wsman',
transport='ntlm',
username=r'somedomain\someuser',
password='secret',
server_cert_validation='ignore')
shell_id = p.open_shell()
command_id = p.run_command(shell_id, 'ipconfig', ['/all'])
std_out, std_err, status_code = p.get_command_output(shell_id, command_id)
p.cleanup_command(shell_id, command_id)
p.close_shell(shell_id)
```
### Valid transport options
pywinrm supports various transport methods in order to authenticate with the WinRM server. The options that are supported in the `transport` parameter are;
* `basic`: Basic auth only works for local Windows accounts not domain accounts. Credentials are base64 encoded when sending to the server.
* `plaintext`: Same as basic auth.
* `certificate`: Authentication is done through a certificate that is mapped to a local Windows account on the server.
* `ssl`: When used in conjunction with `cert_pem` and `cert_key_pem` it will use a certificate as above. If not will revert to basic auth over HTTPS.
* `kerberos`: Will use Kerberos authentication for domain accounts which only works when the client is in the same domain as the server and the required dependencies are installed. Currently a Kerberos ticket needs to be initialized outside of pywinrm using the `kinit` command.
* `ntlm`: Will use NTLM authentication for both domain and local accounts.
* `credssp`: Will use CredSSP authentication for both domain and local accounts. Allows double hop authentication. This only works over a HTTPS endpoint and not HTTP.
### Encryption
By default, WinRM will not accept unencrypted communication with a client. There are two ways
to enable encrypted communication with pywinrm:
1. Use an HTTPS endpoint instead of HTTP (Recommended)
2. Use NTLM, Kerberos, or CredSSP as the transport auth
Using an HTTPS endpoint is recommended, as it will encrypt all the data sent
to the server (including all headers), works securely with all
auth types, and can properly verify remote host identity (when used with certificates signed by a
verifiable certificate authority).
The second option is to use NTLM, Kerberos, or CredSSP, and set the `message_encryption`
arg to protocol to `auto` (the default value) or `always`. This will use the authentication GSS-API
Wrap and Unwrap methods to encrypt the message contents sent to
the server. This form of encryption is independent of the transport layer, and the strength of the encryption
used varies with the underlying authentication type selected (NTLM generally being the weakest and CredSSP the
strongest).
To configure message encryption you can use the `message_encryption` argument
when initialising protocol. This option has 3 values that can be set as shown
below.
* `auto`: Default, Will only use message encryption if it is available for the auth method and HTTPS isn't used.
* `never`: Will never use message encryption even when not over HTTPS.
* `always`: Will always use message encryption even when running over HTTPS (fails if encryption support is unavailable on the selected auth method).
If you set the value to `always` and the transport opt doesn't support message
encryption (e.g., `basic` auth or an old version of `pykerberos` without message
encryption support is installed), pywinrm will throw an exception.
If you do not use an HTTPS endpoint or message encryption, a default-configured WinRM
server will automatically reject requests from pywinrm. Server settings can be modified
allow unencrypted messages and credentials, but this is highly
insecure and should only be used for diagnostic purposes. To allow unencrypted communications,
run the following on the WinRM server (cmd and powershell versions provided):
```
# from cmd
winrm set winrm/config/service @{AllowUnencrypted="true"}
# or from powershell
Set-Item -Path "WSMan:\localhost\Service\AllowUnencrypted" -Value $true
```
Again, this should *not* be used in production environments, as your credentials and WinRM
messages can be trivially recovered.
### Enabling WinRM on remote host
Enable WinRM over HTTP for test usage (includes firewall rules):
```
winrm quickconfig
```
Enable WinRM basic authentication. For domain users, it is necessary to use NTLM, Kerberos, or CredSSP authentication (Kerberos and NTLM authentication are enabled by default, CredSSP is not).
```
# from cmd:
winrm set winrm/config/service/auth @{Basic="true"}
```
Enable WinRM CredSSP authentication. This allows double hop support so you can authenticate with a network service when running command son the remote host. This command is run in Powershell.
```powershell
Enable-WSManCredSSP -Role Server -Force
Set-Item -Path "WSMan:\localhost\Service\Auth\CredSSP" -Value $true
```
### Contributors (alphabetically)
- Alessandro Pilotti
- Alexey Diyan
- Chris Church
- David Cournapeau
- Gema Gomez
- Jijo Varghese
- Jordan Borean
- Juan J. Martinez
- Lukas Bednar
- Manuel Sabban
- Matt Clark
- Matt Davis
- Maxim Kovgan
- Nir Cohen
- Patrick Dunnigan
- Reina Abolofia
Want to help - send a pull request. I will accept good pull requests for sure.
Raw data
{
"_id": null,
"home_page": null,
"name": "pywinrm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "winrm, ws-man, devops, ws-management",
"author": null,
"author_email": "Alexey Diyan <alexey.diyan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5a/2f/d835c342c4b11e28beaccef74982e7669986c84bf19654c39f53c8b8243c/pywinrm-0.5.0.tar.gz",
"platform": null,
"description": "# pywinrm\npywinrm is a Python client for the Windows Remote Management (WinRM) service.\nIt allows you to invoke commands on target Windows machines from any machine\nthat can run Python.\n\n[](https://github.com/diyan/pywinrm/blob/master/LICENSE)\n[](https://github.com/diyan/pywinrm/actions/workflows/ci.yml)\n[](https://coveralls.io/r/diyan/pywinrm)\n[](https://pypi.python.org/pypi/pywinrm)\n\nWinRM allows you to perform various management tasks remotely. These include,\nbut are not limited to: running batch scripts, powershell scripts, and fetching\nWMI variables.\n\nUsed by [Ansible](https://www.ansible.com/) for Windows support.\n\nFor more information on WinRM, please visit\n[Microsoft's WinRM site](http://msdn.microsoft.com/en-us/library/aa384426.aspx).\n\n## Requirements\n* Linux, Mac OS X or Windows\n* CPython 3.8+ or PyPy3\n* [requests-kerberos](http://pypi.python.org/pypi/requests-kerberos) and [requests-credssp](https://github.com/jborean93/requests-credssp) is optional\n\n## Installation\n### To install pywinrm with support for basic, certificate, and NTLM auth, simply\n```bash\n$ pip install pywinrm\n```\n\n### To use Kerberos authentication you need these optional dependencies\n\n```bash\n# for Debian/Ubuntu/etc:\n$ sudo apt-get install gcc python3-dev libkrb5-dev\n$ pip install pywinrm[kerberos]\n\n# for RHEL/CentOS/etc:\n$ sudo dnf install gcc krb5-devel krb5-workstation python3-devel\n$ pip install pywinrm[kerberos]\n```\n\n### To use CredSSP authentication you need these optional dependencies\n\n```bash\n$ pip install pywinrm[credssp]\n```\n\n## Example Usage\n### Run a process on a remote host\n```python\nimport winrm\n\ns = winrm.Session('windows-host.example.com', auth=('john.smith', 'secret'))\nr = s.run_cmd('ipconfig', ['/all'])\n>>> r.status_code\n0\n>>> r.std_out\nWindows IP Configuration\n\n Host Name . . . . . . . . . . . . : WINDOWS-HOST\n Primary Dns Suffix . . . . . . . :\n Node Type . . . . . . . . . . . . : Hybrid\n IP Routing Enabled. . . . . . . . : No\n WINS Proxy Enabled. . . . . . . . : No\n...\n>>> r.std_err\n\n```\n\nNOTE: pywinrm will try and guess the correct endpoint url from the following formats:\n\n - windows-host -> http://windows-host:5985/wsman\n - windows-host:1111 -> http://windows-host:1111/wsman\n - http://windows-host -> http://windows-host:5985/wsman\n - http://windows-host:1111 -> http://windows-host:1111/wsman\n - http://windows-host:1111/wsman -> http://windows-host:1111/wsman\n\n\n### Run Powershell script on remote host\n\n```python\nimport winrm\n\nps_script = \"\"\"$strComputer = $Host\nClear\n$RAM = WmiObject Win32_ComputerSystem\n$MB = 1048576\n\n\"Installed Memory: \" + [int]($RAM.TotalPhysicalMemory /$MB) + \" MB\" \"\"\"\n\ns = winrm.Session('windows-host.example.com', auth=('john.smith', 'secret'))\nr = s.run_ps(ps_script)\n>>> r.status_code\n0\n>>> r.std_out\nInstalled Memory: 3840 MB\n\n>>> r.std_err\n\n```\n\nPowershell scripts will be base64 UTF16 little-endian encoded prior to sending to the Windows host. Error messages are converted from the Powershell CLIXML format to a human readable format as a convenience.\n\n### Run process with low-level API with domain user, disabling HTTPS cert validation\n\n```python\nfrom winrm.protocol import Protocol\n\np = Protocol(\n endpoint='https://windows-host:5986/wsman',\n transport='ntlm',\n username=r'somedomain\\someuser',\n password='secret',\n server_cert_validation='ignore')\nshell_id = p.open_shell()\ncommand_id = p.run_command(shell_id, 'ipconfig', ['/all'])\nstd_out, std_err, status_code = p.get_command_output(shell_id, command_id)\np.cleanup_command(shell_id, command_id)\np.close_shell(shell_id)\n```\n\n### Valid transport options\n\npywinrm supports various transport methods in order to authenticate with the WinRM server. The options that are supported in the `transport` parameter are;\n* `basic`: Basic auth only works for local Windows accounts not domain accounts. Credentials are base64 encoded when sending to the server.\n* `plaintext`: Same as basic auth.\n* `certificate`: Authentication is done through a certificate that is mapped to a local Windows account on the server.\n* `ssl`: When used in conjunction with `cert_pem` and `cert_key_pem` it will use a certificate as above. If not will revert to basic auth over HTTPS.\n* `kerberos`: Will use Kerberos authentication for domain accounts which only works when the client is in the same domain as the server and the required dependencies are installed. Currently a Kerberos ticket needs to be initialized outside of pywinrm using the `kinit` command.\n* `ntlm`: Will use NTLM authentication for both domain and local accounts.\n* `credssp`: Will use CredSSP authentication for both domain and local accounts. Allows double hop authentication. This only works over a HTTPS endpoint and not HTTP.\n\n### Encryption\n\nBy default, WinRM will not accept unencrypted communication with a client. There are two ways\nto enable encrypted communication with pywinrm:\n\n1. Use an HTTPS endpoint instead of HTTP (Recommended)\n2. Use NTLM, Kerberos, or CredSSP as the transport auth\n\nUsing an HTTPS endpoint is recommended, as it will encrypt all the data sent\nto the server (including all headers), works securely with all\nauth types, and can properly verify remote host identity (when used with certificates signed by a\nverifiable certificate authority).\n\nThe second option is to use NTLM, Kerberos, or CredSSP, and set the `message_encryption`\narg to protocol to `auto` (the default value) or `always`. This will use the authentication GSS-API\nWrap and Unwrap methods to encrypt the message contents sent to\nthe server. This form of encryption is independent of the transport layer, and the strength of the encryption\nused varies with the underlying authentication type selected (NTLM generally being the weakest and CredSSP the\nstrongest).\n\nTo configure message encryption you can use the `message_encryption` argument\nwhen initialising protocol. This option has 3 values that can be set as shown\nbelow.\n\n* `auto`: Default, Will only use message encryption if it is available for the auth method and HTTPS isn't used.\n* `never`: Will never use message encryption even when not over HTTPS.\n* `always`: Will always use message encryption even when running over HTTPS (fails if encryption support is unavailable on the selected auth method).\n\nIf you set the value to `always` and the transport opt doesn't support message\nencryption (e.g., `basic` auth or an old version of `pykerberos` without message\nencryption support is installed), pywinrm will throw an exception.\n\nIf you do not use an HTTPS endpoint or message encryption, a default-configured WinRM\nserver will automatically reject requests from pywinrm. Server settings can be modified\nallow unencrypted messages and credentials, but this is highly\ninsecure and should only be used for diagnostic purposes. To allow unencrypted communications,\nrun the following on the WinRM server (cmd and powershell versions provided):\n\n```\n# from cmd\nwinrm set winrm/config/service @{AllowUnencrypted=\"true\"}\n\n# or from powershell\nSet-Item -Path \"WSMan:\\localhost\\Service\\AllowUnencrypted\" -Value $true\n```\n\nAgain, this should *not* be used in production environments, as your credentials and WinRM\nmessages can be trivially recovered.\n\n\n### Enabling WinRM on remote host\nEnable WinRM over HTTP for test usage (includes firewall rules):\n```\nwinrm quickconfig\n```\n\nEnable WinRM basic authentication. For domain users, it is necessary to use NTLM, Kerberos, or CredSSP authentication (Kerberos and NTLM authentication are enabled by default, CredSSP is not).\n```\n# from cmd:\nwinrm set winrm/config/service/auth @{Basic=\"true\"}\n```\n\nEnable WinRM CredSSP authentication. This allows double hop support so you can authenticate with a network service when running command son the remote host. This command is run in Powershell.\n```powershell\nEnable-WSManCredSSP -Role Server -Force\nSet-Item -Path \"WSMan:\\localhost\\Service\\Auth\\CredSSP\" -Value $true\n```\n\n### Contributors (alphabetically)\n\n- Alessandro Pilotti\n- Alexey Diyan\n- Chris Church\n- David Cournapeau\n- Gema Gomez\n- Jijo Varghese\n- Jordan Borean\n- Juan J. Martinez\n- Lukas Bednar\n- Manuel Sabban\n- Matt Clark\n- Matt Davis\n- Maxim Kovgan\n- Nir Cohen\n- Patrick Dunnigan\n- Reina Abolofia\n\nWant to help - send a pull request. I will accept good pull requests for sure.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2013 Alexey Diyan 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.",
"summary": "Python library for Windows Remote Management",
"version": "0.5.0",
"project_urls": {
"homepage": "http://github.com/diyan/pywinrm/"
},
"split_keywords": [
"winrm",
" ws-man",
" devops",
" ws-management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c454340320145c225387f40ce412de1b209d991c322032e4922cc0a9935fd31",
"md5": "c340e795ea11f2d9f21027b05885e97c",
"sha256": "c267046d281de613fc7c8a528cdd261564d9b99bdb7c2926221eff3263b700c8"
},
"downloads": -1,
"filename": "pywinrm-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c340e795ea11f2d9f21027b05885e97c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48182,
"upload_time": "2024-07-16T19:32:03",
"upload_time_iso_8601": "2024-07-16T19:32:03.001838Z",
"url": "https://files.pythonhosted.org/packages/0c/45/4340320145c225387f40ce412de1b209d991c322032e4922cc0a9935fd31/pywinrm-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a2fd835c342c4b11e28beaccef74982e7669986c84bf19654c39f53c8b8243c",
"md5": "350aee4e5c071dfd3a1ffcb2d550f05d",
"sha256": "5428eb1e494af7954546cd4ff15c9ef1a30a75e05b25a39fd606cef22201e9f1"
},
"downloads": -1,
"filename": "pywinrm-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "350aee4e5c071dfd3a1ffcb2d550f05d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 40875,
"upload_time": "2024-07-16T19:32:05",
"upload_time_iso_8601": "2024-07-16T19:32:05.624093Z",
"url": "https://files.pythonhosted.org/packages/5a/2f/d835c342c4b11e28beaccef74982e7669986c84bf19654c39f53c8b8243c/pywinrm-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-16 19:32:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "diyan",
"github_project": "pywinrm",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pywinrm"
}
