lib.winrm

  1#!/usr/bin/env python3
  2# -*- coding: utf-8; py-indent-offset: 4 -*-
  3#
  4# Author:  Linuxfabrik GmbH, Zurich, Switzerland
  5# Contact: info (at) linuxfabrik (dot) ch
  6#          https://www.linuxfabrik.ch/
  7# License: The Unlicense, see LICENSE file.
  8
  9# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.rst
 10
 11"""This library collects some Microsoft WinRM related functions.
 12"""
 13
 14__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
 15__version__ = '2025111201'
 16
 17try:
 18    import winrm
 19    HAVE_WINRM = True
 20except ImportError:
 21    HAVE_WINRM = False
 22
 23try:
 24    from pypsrp.client import Client
 25    HAVE_JEA = True
 26except ImportError:
 27    HAVE_JEA = False
 28
 29from . import txt
 30
 31
 32def run_cmd(args, cmd, params=None):
 33    """
 34    Run a native command on a remote Windows host via WinRM/PSRP and return a
 35    normalized result dictionary.
 36
 37    Prefers **pypsrp (PSRP)** if available (for JEA/PowerShell Remoting
 38    compatibility); otherwise falls back to **pywinrm**. Authentication,
 39    transport and SSL/port selection are derived from the provided `args`.
 40
 41    ### Parameters
 42    - **args**: An object (e.g., `argparse.Namespace`) that provides at least:
 43        - `WINRM_HOSTNAME` (`str`): Target host or IP.
 44        - `WINRM_USERNAME` (`str`, optional): Username. If `None` or empty when using
 45          Kerberos transport, will use existing Kerberos credentials from credential cache
 46          (e.g., obtained via `kinit`).
 47        - `WINRM_PASSWORD` (`str`, optional): Password. If `None` or empty when using
 48          Kerberos transport, will use existing Kerberos credentials from credential cache.
 49        - `WINRM_TRANSPORT` (`str`, optional): Transport (e.g., `'negotiate'`, `'kerberos'`,
 50          `'ntlm'`, `'credssp'`, `'basic'`, `'ssl'`). Defaults to `'negotiate'` if unset.
 51        - `WINRM_DOMAIN` (`str`, optional): If set, username is sent as `user@domain`.
 52      (Additional fields may be honored by the underlying libraries if present.)
 53    - **cmd** (`str`): The executable/command to run remotely (native command, not a PowerShell
 54       script block).
 55    - **params** (`list[str]`, optional): Positional arguments passed to the command. Defaults
 56       to `[]`.
 57
 58    ### Returns
 59    - **dict**: A normalized result with:
 60        - `retc` (`int`): Process return code (`0` on success).
 61        - `stdout` (`str`): Captured standard output (text).
 62        - `stderr` (`str`): Captured standard error (text).
 63
 64    ### Behavior
 65    - If **pypsrp** is available, maps `WINRM_TRANSPORT` to an appropriate PSRP auth
 66      and chooses SSL/port (5986 for SSL, 5985 otherwise), then executes the command
 67      via `Client.execute_cmd()`.
 68    - If pypsrp is unavailable but **pywinrm** is installed, executes via
 69      `Session.run_cmd()`.
 70    - For Kerberos authentication: if `WINRM_USERNAME` and `WINRM_PASSWORD` are not provided
 71      (or are empty/None), the function will attempt to use existing Kerberos credentials
 72      from the credential cache (obtained via `kinit`).
 73    - On any exception, returns `{'retc': 1, 'stdout': '', 'stderr': <exception text>}`.
 74    - If neither backend is present, returns an error indicating that no compatible
 75      remoting library is available.
 76
 77    ### Example
 78    >>> # With explicit credentials:
 79    >>> run_cmd(args, "ipconfig", ["/all"])
 80    {'retc': 0, 'stdout': 'Windows IP Configuration\\r\\n...','stderr': ''}
 81    >>> # With Kerberos using kinit credentials (username/password can be None):
 82    >>> run_cmd(args, "ipconfig", ["/all"])
 83    {'retc': 0, 'stdout': 'Windows IP Configuration\\r\\n...','stderr': ''}
 84    """
 85    # Determine authentication credentials
 86    # For Kerberos, allow using existing credentials from kinit
 87    username = getattr(args, 'WINRM_USERNAME', None)
 88    password = getattr(args, 'WINRM_PASSWORD', None)
 89
 90    # Check if we should use Kerberos with existing credentials
 91    _transport = (getattr(args, 'WINRM_TRANSPORT', None) or '').lower()
 92    use_kerberos_cache = (_transport in ['kerberos', 'negotiate']) and (not username or not password)
 93
 94    if use_kerberos_cache:
 95        # Use None for username/password to let Kerberos use credential cache
 96        auth = (None, None)
 97    else:
 98        # Use provided credentials
 99        auth = (username, password)
100        if getattr(args, 'WINRM_DOMAIN', None):
101            auth = (f'{username}@{args.WINRM_DOMAIN}', password)
102
103    if params is None:
104        params = []
105
106    if HAVE_JEA:
107        try:
108            # translate pywinrm transport -> pypsrp auth/ssl/port
109            _auth_map = {
110                'kerberos': 'kerberos',
111                'negotiate': 'negotiate',
112                'ntlm': 'negotiate',   # NTLM is negotiated under "negotiate"
113                'credssp': 'credssp',
114                'basic': 'basic',
115                'plaintext': 'basic',  # basic over HTTP
116                'ssl': 'basic',        # basic over HTTPS
117            }
118            _psrp_auth = _auth_map.get(_transport, 'negotiate')
119            _use_ssl = (_transport == 'ssl')
120            _port = 5986 if _use_ssl else 5985
121
122            # create PSRP client
123            session = Client(
124                server=args.WINRM_HOSTNAME,
125                username=auth[0],
126                password=auth[1],
127                auth=_psrp_auth,
128                ssl=_use_ssl,
129                port=_port,
130                cert_validation=True,
131            )
132
133            # run native command (not PowerShell script)
134            stdout, stderr, rc = session.execute_cmd(cmd, params)
135
136            return {
137                'retc': rc,
138                'stdout': txt.to_text(stdout),
139                'stderr': txt.to_text(stderr),
140            }
141        except Exception as e:
142            return {
143                'retc': 1,
144                'stdout': '',
145                'stderr': txt.exception2text(e),
146            }
147
148    if HAVE_WINRM:
149        try:
150            session = winrm.Session(
151                args.WINRM_HOSTNAME,
152                auth=auth,
153                transport=args.WINRM_TRANSPORT,
154            )
155
156            result = session.run_cmd(cmd, params)
157            return {
158                'retc': result.status_code,
159                'stdout': txt.to_text(result.std_out),
160                'stderr': txt.to_text(result.std_err),
161            }
162        except Exception as e:
163            return {
164                'retc': 1,
165                'stdout': '',
166                'stderr': txt.exception2text(e),
167            }
168
169    # Neither pypsrp nor pywinrm is available
170    return {
171        'retc': 1,
172        'stdout': '',
173        'stderr': 'No compatible remoting library available (pypsrp or pywinrm).',
174    }
175
176
177def run_ps(args, cmd):
178    """
179    Run a PowerShell script/string on a remote Windows host via WinRM/PSRP and
180    return a normalized result dictionary.
181
182    Prefers **pypsrp (PSRP)** if available (best for JEA/PowerShell Remoting);
183    otherwise falls back to **pywinrm**. Authentication, transport, and SSL/port
184    are derived from the provided `args`.
185
186    ### Parameters
187    - **args**: An object (e.g., `argparse.Namespace`) that provides at least:
188        - `WINRM_HOSTNAME` (`str`): Target host or IP.
189        - `WINRM_USERNAME` (`str`, optional): Username. If `None` or empty when using
190          Kerberos transport, will use existing Kerberos credentials from credential cache
191          (e.g., obtained via `kinit`).
192        - `WINRM_PASSWORD` (`str`, optional): Password. If `None` or empty when using
193          Kerberos transport, will use existing Kerberos credentials from credential cache.
194        - `WINRM_TRANSPORT` (`str`, optional): Transport (`'negotiate'`, `'kerberos'`,
195          `'ntlm'`, `'credssp'`, `'basic'`, `'ssl'`, etc.). Defaults to `'negotiate'`
196          if unset.
197        - `WINRM_DOMAIN` (`str`, optional): If set, username is sent as `user@domain`.
198      (Additional attributes may be honored by the underlying libraries if present.)
199    - **cmd** (`str`): PowerShell scriptblock/string to execute remotely.
200
201    ### Returns
202    - **dict**: A normalized result with:
203        - `retc` (`int`): Return code (`0` if no PowerShell errors were reported).
204        - `stdout` (`str`): Captured standard output/text from the script.
205        - `stderr` (`str`): Aggregated error/diagnostic output.
206          - For **PSRP**: collects entries from the PowerShell *Error* stream
207            (human-readable via `to_string()` when available).
208          - For **pywinrm**: uses `std_err`; if `retc == 0` and stderr begins with
209            `#< CLIXML`, it is suppressed as benign progress noise.
210
211    ### Behavior
212    - Maps `WINRM_TRANSPORT` to PSRP auth (`kerberos`, `negotiate`, `credssp`, `basic`)
213      and decides SSL/port (5986 for SSL, 5985 otherwise) when using **pypsrp**,
214      then executes via `Client.execute_ps()`.
215    - Falls back to **pywinrm** and executes via `Session.run_ps()` if pypsrp is not available.
216    - For Kerberos authentication: if `WINRM_USERNAME` and `WINRM_PASSWORD` are not provided
217      (or are empty/None), the function will attempt to use existing Kerberos credentials
218      from the credential cache (obtained via `kinit`).
219    - On any exception, returns `{'retc': 1, 'stdout': '', 'stderr': <exception text>}`.
220    - If neither backend is installed, returns an error indicating that no compatible
221      remoting library is available.
222
223    ### Example
224    >>> # With explicit credentials:
225    >>> run_ps(args, "Get-Process | Select-Object -First 1 | Format-Table Name,Id -AutoSize")
226    {'retc': 0, 'stdout': 'Name    Id\\r\\n----    --\\r\\n...\\r\\n', 'stderr': ''}
227    >>> # With Kerberos using kinit credentials (username/password can be None):
228    >>> run_ps(args, "Get-Process | Select-Object -First 1 | Format-Table Name,Id -AutoSize")
229    {'retc': 0, 'stdout': 'Name    Id\\r\\n----    --\\r\\n...\\r\\n', 'stderr': ''}
230    """
231    # Determine authentication credentials
232    # For Kerberos, allow using existing credentials from kinit
233    username = getattr(args, 'WINRM_USERNAME', None)
234    password = getattr(args, 'WINRM_PASSWORD', None)
235
236    # Check if we should use Kerberos with existing credentials
237    _transport = (getattr(args, 'WINRM_TRANSPORT', None) or '').lower()
238    use_kerberos_cache = (_transport in ['kerberos', 'negotiate']) and (not username or not password)
239
240    if use_kerberos_cache:
241        # Use None for username/password to let Kerberos use credential cache
242        auth = (None, None)
243    else:
244        # Use provided credentials
245        auth = (username, password)
246        if getattr(args, 'WINRM_DOMAIN', None):
247            auth = (f'{username}@{args.WINRM_DOMAIN}', password)
248
249    if HAVE_JEA:
250        try:
251            # translate pywinrm transport -> pypsrp auth/ssl/port
252            _auth_map = {
253                'kerberos': 'kerberos',
254                'negotiate': 'negotiate',
255                'ntlm': 'negotiate',   # NTLM is negotiated under "negotiate"
256                'credssp': 'credssp',
257                'basic': 'basic',
258                'plaintext': 'basic',  # basic over HTTP
259                'ssl': 'basic',        # basic over HTTPS
260            }
261            _psrp_auth = _auth_map.get(_transport, 'negotiate')
262            _use_ssl = (_transport == 'ssl')
263            _port = 5986 if _use_ssl else 5985
264
265            # create PSRP client (like in winrm.Session)
266            session = Client(
267                server=args.WINRM_HOSTNAME,
268                username=auth[0],
269                password=auth[1],
270                auth=_psrp_auth,
271                ssl=_use_ssl,
272                port=_port,
273                cert_validation=True,
274            )
275
276            # run PowerShell
277            stdout, streams, had_errors = session.execute_ps(cmd)
278
279            # stdout is already a string; stderr from PSRP error stream(s)
280            stderr_lines = []
281            for err in getattr(streams, 'error', []):
282                # err.to_string() gives a readable message with category/position if available
283                try:
284                    stderr_lines.append(err.to_string())
285                except Exception:
286                    # fallback to message text
287                    msg = getattr(err, 'message', None) or str(err)
288                    stderr_lines.append(str(msg))
289            stderr = '\n'.join(stderr_lines)
290
291            result = {
292                'retc': 0 if not had_errors else 1,
293                'stdout': txt.to_text(stdout),
294                'stderr': txt.to_text(stderr),
295            }
296            return result
297        except Exception as e:
298            return {
299                'retc': 1,
300                'stdout': '',
301                'stderr': txt.exception2text(e),
302            }
303
304    if HAVE_WINRM:
305        try:
306            session = winrm.Session(
307                args.WINRM_HOSTNAME,
308                auth=auth,
309                transport=args.WINRM_TRANSPORT,
310            )
311
312            # run PowerShell
313            result = session.run_ps(cmd)
314
315            result = {
316                'retc': result.status_code,
317                'stdout': txt.to_text(result.std_out),
318                'stderr': txt.to_text(result.std_err),
319            }
320            # if `result.status_code == 0`, ignore stderr that starts with `#< CLIXML`
321            # (it's just progress noise)
322            if result['retc'] == 0 and result['stderr'].startswith('#< CLIXML'):
323                result['stderr'] = ''
324            return result
325        except Exception as e:
326            return {
327                'retc': 1,
328                'stdout': '',
329                'stderr': txt.exception2text(e),
330            }
331
332    # Neither pypsrp nor pywinrm is available
333    return {
334        'retc': 1,
335        'stdout': '',
336        'stderr': 'No compatible remoting library available (pypsrp or pywinrm).',
337    }