pywinrm

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

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

由 Ansible 用于 Windows 支持。

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

要求

• Linux、Mac OS X 或 Windows
• CPython 3.8+ 或 PyPy3
• requests-kerberos 和 requests-credssp 是可选的

安装

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

$ pip install pywinrm

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

# 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]

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

$ 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 证书验证的低级别 API 运行进程

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 端点是推荐的，因为它将加密发送到服务器上的所有数据（包括所有标题），与所有认证类型安全地工作，并且可以正确验证远程主机身份（当与由可验证的证书颁发机构签名的证书一起使用时）。

第二种选择是使用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

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

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

想帮忙 - 发送拉取请求。我肯定会接受好的拉取请求。