pywinrm

pywinrm是Windows远程管理（WinRM）服务的Python客户端。它允许您从任何可以运行Python的机器上调用目标Windows机器上的命令。

WinRM允许您远程执行各种管理任务。这些包括但不限于：运行批处理脚本、PowerShell脚本和获取WMI变量。

由Ansible用于Windows支持。

有关WinRM的更多信息，请访问Microsoft的WinRM网站。

要求

• Linux、Mac OS X或Windows
• CPython 2.6-2.7, 3.3-3.5 或 PyPy2
• requests-kerberos 和 requests-credssp 是可选的

安装

要安装支持基本、证书和 NTLM 验证的 pywinrm，只需

$ pip install pywinrm

要使用 Kerberos 验证，您需要以下可选依赖项

# for Debian/Ubuntu/etc:
$ sudo apt-get install gcc python-dev libkrb5-dev
$ pip install pywinrm[kerberos]

# for RHEL/CentOS/etc:
$ sudo yum install gcc python-devel krb5-devel krb5-workstation python-devel
$ pip install pywinrm[kerberos]

要使用 CredSSP 验证，您需要以下可选依赖项

# for Debian/Ubuntu/etc:
$ sudo apt-get install gcc python-dev libssl-dev
$ pip install pywinrm[credssp]

# for RHEL/CentOS/etc:
$ sudo yum install gcc python-devel openssl-devel
$ pip install pywinrm[credssp]

示例用法

在远程主机上运行进程

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

注意：pywinrm 将尝试从以下格式猜测正确的端点 URL

• 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

在远程主机上运行 PowerShell 脚本

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 脚本在发送到 Windows 主机之前将被 base64 UTF16 小端编码。错误消息将从 Powershell CLIXML 格式转换为可读格式，以便方便使用。

使用域用户运行进程，禁用 HTTPS 证书验证

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)

有效的传输选项

pywinrm 支持各种传输方法以与 WinRM 服务器进行身份验证。在 transport 参数中支持以下选项；

• basic：基本身份验证仅适用于本地 Windows 账户，不适用于域账户。凭据在发送到服务器时进行 base64 编码。
• plaintext：与基本身份验证相同。
• certificate：通过映射到服务器上本地 Windows 账户的证书进行身份验证。
• ssl：当与 cert_pem 和 cert_key_pem 一起使用时，它将使用上述证书。如果没有，将回退到通过 HTTPS 的基本身份验证。
• kerberos：将使用针对域账户的 Kerberos 身份验证。这只在客户端与服务器在同一个域中并且已安装所需依赖项时才有效。目前需要使用 kinit 命令在 pywinrm 外初始化 Kerberos 令牌。
• ntlm：将使用针对域和本地账户的 NTLM 身份验证。
• credssp：将使用针对域和本地账户的 CredSSP 身份验证。允许双跳身份验证。这仅适用于 HTTPS 端点，不适用于 HTTP。

加密

默认情况下，WinRM 不会接受与客户端的未加密通信。有两种方法可以启用 pywinrm 的加密通信

1. 使用 HTTPS 端点而不是 HTTP（推荐）
2. 使用 NTLM、Kerberos 或 CredSSP 作为传输身份验证

使用 HTTPS 端点是推荐的，因为它将加密发送到服务器上的所有数据（包括所有标头），与所有身份验证类型安全地工作，并且可以正确验证远程主机身份（当与由可验证证书机构签发的证书一起使用时）。您可以使用 此脚本 在 WinRM 上轻松设置自签名证书的 HTTPS 端点，但在生产环境中推荐使用可验证证书机构。

第二种选择是使用NTLM、Kerberos或CredSSP，并将message_encryption参数设置为协议为auto（默认值）或always。这将使用认证GSS-API封装和解封装方法来加密发送到服务器的消息内容。这种加密形式独立于传输层，所使用的加密强度取决于选择的底层认证类型（NTLM通常是最弱的，CredSSP是最强的）。

要配置消息加密，您可以在初始化协议时使用message_encryption参数。此选项有3个值可以设置，如下所示。

• auto：默认值，只有当认证方法可用且不使用HTTPS时才会使用消息加密。
• never：即使不通过HTTPS也会禁用消息加密。
• always：即使运行在HTTPS上也会始终使用消息加密（如果所选认证方法不支持加密，则失败）。

如果您将值设置为always，但传输选项不支持消息加密（例如，basic认证或安装了不带消息加密支持的旧版pykerberos），pywinrm将抛出异常。

如果您未使用HTTPS端点或消息加密，默认配置的WinRM服务器将自动拒绝来自pywinrm的请求。可以通过修改服务器设置来允许未加密的消息和凭据，但这非常不安全，仅应用于诊断目的。要允许未加密的通信，请在WinRM服务器上运行以下命令（提供cmd和powershell版本）

# from cmd
winrm set winrm/config/service @{AllowUnencrypted="true"}

# or from powershell
Set-Item -Path "WSMan:\localhost\Service\AllowUnencrypted" -Value $true

再次强调，这不应在生产环境中使用，因为您的凭据和WinRM消息可以被轻易恢复。

在远程主机上启用WinRM

使用自签名证书启用WinRM的HTTP和HTTPS（包括防火墙规则）

# from powershell:
Invoke-Expression ((New-Object System.Net.Webclient).DownloadString('https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1'))

为测试用途启用WinRM的HTTP（包括防火墙规则）

winrm quickconfig

启用WinRM基本认证。对于域用户，必须使用NTLM、Kerberos或CredSSP认证（默认启用Kerberos和NTLM认证，CredSSP未启用）。

# from cmd:
winrm set winrm/config/service/auth @{Basic="true"}

启用WinRM CredSSP认证。这允许双重跃迁支持，因此您可以在远程主机上运行命令时使用网络服务进行认证。此命令在PowerShell中运行。

Enable-WSManCredSSP -Role Server -Force
Set-Item -Path "WSMan:\localhost\Service\Auth\CredSSP" -Value $true

贡献者（按字母顺序）

• 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

想要帮助 - 发送pull request。我肯定会接受好的pull request。