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__ = '2025103002'
 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`): Username.
 45        - `WINRM_PASSWORD` (`str`): Password.
 46        - `WINRM_TRANSPORT` (`str`, optional): Transport (e.g., `'negotiate'`, `'kerberos'`,
 47          `'ntlm'`, `'credssp'`, `'basic'`, `'ssl'`). Defaults to `'negotiate'` if unset.
 48        - `WINRM_DOMAIN` (`str`, optional): If set, username is sent as `user@domain`.
 49      (Additional fields may be honored by the underlying libraries if present.)
 50    - **cmd** (`str`): The executable/command to run remotely (native command, not a PowerShell
 51       script block).
 52    - **params** (`list[str]`, optional): Positional arguments passed to the command. Defaults
 53       to `[]`.
 54
 55    ### Returns
 56    - **dict**: A normalized result with:
 57        - `retc` (`int`): Process return code (`0` on success).
 58        - `stdout` (`str`): Captured standard output (text).
 59        - `stderr` (`str`): Captured standard error (text).
 60
 61    ### Behavior
 62    - If **pypsrp** is available, maps `WINRM_TRANSPORT` to an appropriate PSRP auth
 63      and chooses SSL/port (5986 for SSL, 5985 otherwise), then executes the command
 64      via `Client.execute_cmd()`.
 65    - If pypsrp is unavailable but **pywinrm** is installed, executes via
 66      `Session.run_cmd()`.
 67    - On any exception, returns `{'retc': 1, 'stdout': '', 'stderr': <exception text>}`.
 68    - If neither backend is present, returns an error indicating that no compatible
 69      remoting library is available.
 70
 71    ### Example
 72    >>> # args provides WINRM_* settings (hostname, creds, transport, etc.)
 73    >>> run_cmd(args, "ipconfig", ["/all"])
 74    {'retc': 0, 'stdout': 'Windows IP Configuration\\r\\n...','stderr': ''}
 75    """
 76    auth = (args.WINRM_USERNAME, args.WINRM_PASSWORD)
 77    if getattr(args, 'WINRM_DOMAIN', None):
 78        auth = (f'{args.WINRM_USERNAME}@{args.WINRM_DOMAIN}', args.WINRM_PASSWORD)
 79
 80    if params is None:
 81        params = []
 82
 83    if HAVE_JEA:
 84        try:
 85            # translate pywinrm transport -> pypsrp auth/ssl/port
 86            _transport = (args.WINRM_TRANSPORT or '').lower()
 87            _auth_map = {
 88                'kerberos': 'kerberos',
 89                'negotiate': 'negotiate',
 90                'ntlm': 'negotiate',   # NTLM is negotiated under "negotiate"
 91                'credssp': 'credssp',
 92                'basic': 'basic',
 93                'plaintext': 'basic',  # basic over HTTP
 94                'ssl': 'basic',        # basic over HTTPS
 95            }
 96            _psrp_auth = _auth_map.get(_transport, 'negotiate')
 97            _use_ssl = (_transport == 'ssl')
 98            _port = 5986 if _use_ssl else 5985
 99
100            # create PSRP client
101            session = Client(
102                server=args.WINRM_HOSTNAME,
103                username=auth[0],
104                password=auth[1],
105                auth=_psrp_auth,
106                ssl=_use_ssl,
107                port=_port,
108                cert_validation=True,
109            )
110
111            # run native command (not PowerShell script)
112            stdout, stderr, rc = session.execute_cmd(cmd, params)
113
114            return {
115                'retc': rc,
116                'stdout': txt.to_text(stdout),
117                'stderr': txt.to_text(stderr),
118            }
119        except Exception as e:
120            return {
121                'retc': 1,
122                'stdout': '',
123                'stderr': txt.exception2text(e),
124            }
125
126    if HAVE_WINRM:
127        try:
128            session = winrm.Session(
129                args.WINRM_HOSTNAME,
130                auth=auth,
131                transport=args.WINRM_TRANSPORT,
132            )
133
134            result = session.run_cmd(cmd, params)
135            return {
136                'retc': result.status_code,
137                'stdout': txt.to_text(result.std_out),
138                'stderr': txt.to_text(result.std_err),
139            }
140        except Exception as e:
141            return {
142                'retc': 1,
143                'stdout': '',
144                'stderr': txt.exception2text(e),
145            }
146
147    # Neither pypsrp nor pywinrm is available
148    return {
149        'retc': 1,
150        'stdout': '',
151        'stderr': 'No compatible remoting library available (pypsrp or pywinrm).',
152    }
153
154
155def run_ps(args, cmd):
156    """
157    Run a PowerShell script/string on a remote Windows host via WinRM/PSRP and
158    return a normalized result dictionary.
159
160    Prefers **pypsrp (PSRP)** if available (best for JEA/PowerShell Remoting);
161    otherwise falls back to **pywinrm**. Authentication, transport, and SSL/port
162    are derived from the provided `args`.
163
164    ### Parameters
165    - **args**: An object (e.g., `argparse.Namespace`) that provides at least:
166        - `WINRM_HOSTNAME` (`str`): Target host or IP.
167        - `WINRM_USERNAME` (`str`): Username.
168        - `WINRM_PASSWORD` (`str`): Password.
169        - `WINRM_TRANSPORT` (`str`, optional): Transport (`'negotiate'`, `'kerberos'`,
170          `'ntlm'`, `'credssp'`, `'basic'`, `'ssl'`, etc.). Defaults to `'negotiate'`
171          if unset.
172        - `WINRM_DOMAIN` (`str`, optional): If set, username is sent as `user@domain`.
173      (Additional attributes may be honored by the underlying libraries if present.)
174    - **cmd** (`str`): PowerShell scriptblock/string to execute remotely.
175
176    ### Returns
177    - **dict**: A normalized result with:
178        - `retc` (`int`): Return code (`0` if no PowerShell errors were reported).
179        - `stdout` (`str`): Captured standard output/text from the script.
180        - `stderr` (`str`): Aggregated error/diagnostic output.
181          - For **PSRP**: collects entries from the PowerShell *Error* stream
182            (human-readable via `to_string()` when available).
183          - For **pywinrm**: uses `std_err`; if `retc == 0` and stderr begins with
184            `#< CLIXML`, it is suppressed as benign progress noise.
185
186    ### Behavior
187    - Maps `WINRM_TRANSPORT` to PSRP auth (`kerberos`, `negotiate`, `credssp`, `basic`)
188      and decides SSL/port (5986 for SSL, 5985 otherwise) when using **pypsrp**,
189      then executes via `Client.execute_ps()`.
190    - Falls back to **pywinrm** and executes via `Session.run_ps()` if pypsrp is not available.
191    - On any exception, returns `{'retc': 1, 'stdout': '', 'stderr': <exception text>}`.
192    - If neither backend is installed, returns an error indicating that no compatible
193      remoting library is available.
194
195    ### Example
196    >>> # args must provide WINRM_* settings (hostname, creds, transport, etc.)
197    >>> run_ps(args, "Get-Process | Select-Object -First 1 | Format-Table Name,Id -AutoSize")
198    {'retc': 0, 'stdout': 'Name    Id\\r\\n----    --\\r\\n...\\r\\n', 'stderr': ''}
199    """
200    auth = (args.WINRM_USERNAME, args.WINRM_PASSWORD)
201    if getattr(args, 'WINRM_DOMAIN', None):
202        auth = (f'{args.WINRM_USERNAME}@{args.WINRM_DOMAIN}', args.WINRM_PASSWORD)
203
204    if HAVE_JEA:
205        try:
206            # translate pywinrm transport -> pypsrp auth/ssl/port
207            _transport = (args.WINRM_TRANSPORT or '').lower()
208            _auth_map = {
209                'kerberos': 'kerberos',
210                'negotiate': 'negotiate',
211                'ntlm': 'negotiate',   # NTLM is negotiated under "negotiate"
212                'credssp': 'credssp',
213                'basic': 'basic',
214                'plaintext': 'basic',  # basic over HTTP
215                'ssl': 'basic',        # basic over HTTPS
216            }
217            _psrp_auth = _auth_map.get(_transport, 'negotiate')
218            _use_ssl = (_transport == 'ssl')
219            _port = 5986 if _use_ssl else 5985
220
221            # create PSRP client (like in winrm.Session)
222            session = Client(
223                server=args.WINRM_HOSTNAME,
224                username=auth[0],
225                password=auth[1],
226                auth=_psrp_auth,
227                ssl=_use_ssl,
228                port=_port,
229                cert_validation=True,
230            )
231
232            # run PowerShell
233            stdout, streams, had_errors = session.execute_ps(cmd)
234
235            # stdout is already a string; stderr from PSRP error stream(s)
236            stderr_lines = []
237            for err in getattr(streams, 'error', []):
238                # err.to_string() gives a readable message with category/position if available
239                try:
240                    stderr_lines.append(err.to_string())
241                except Exception:
242                    # fallback to message text
243                    msg = getattr(err, 'message', None) or str(err)
244                    stderr_lines.append(str(msg))
245            stderr = '\n'.join(stderr_lines)
246
247            result = {
248                'retc': 0 if not had_errors else 1,
249                'stdout': txt.to_text(stdout),
250                'stderr': txt.to_text(stderr),
251            }
252            return result
253        except Exception as e:
254            return {
255                'retc': 1,
256                'stdout': '',
257                'stderr': txt.exception2text(e),
258            }
259
260    if HAVE_WINRM:
261        try:
262            session = winrm.Session(
263                args.WINRM_HOSTNAME,
264                auth=auth,
265                transport=args.WINRM_TRANSPORT,
266            )
267
268            # run PowerShell
269            result = session.run_ps(cmd)
270
271            result = {
272                'retc': result.status_code,
273                'stdout': txt.to_text(result.std_out),
274                'stderr': txt.to_text(result.std_err),
275            }
276            # if `result.status_code == 0`, ignore stderr that starts with `#< CLIXML`
277            # (it's just progress noise)
278            if result['retc'] == 0 and result['stderr'].startswith('#< CLIXML'):
279                result['stderr'] = ''
280            return result
281        except Exception as e:
282            return {
283                'retc': 1,
284                'stdout': '',
285                'stderr': txt.exception2text(e),
286            }
287
288    # Neither pypsrp nor pywinrm is available
289    return {
290        'retc': 1,
291        'stdout': '',
292        'stderr': 'No compatible remoting library available (pypsrp or pywinrm).',
293    }