lib.winrm

  1#! /usr/bin/env python2
  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__ = '2025042001'
 16
 17try:
 18    import winrm
 19    HAVE_WINRM = True
 20except ImportError:
 21    HAVE_WINRM = False
 22
 23from . import txt
 24
 25
 26def run_cmd(args, cmd, params=None):
 27    """
 28    Execute a command over WinRM using cmd.exe and return the result.
 29
 30    This function runs a command remotely on a Windows machine using WinRM via `cmd.exe`.
 31    It handles authentication with or without a domain and returns the result as a dictionary.
 32
 33    ### Parameters
 34    - **args** (object):
 35      An object containing:
 36        - `WINRM_HOSTNAME` (`str`): The target hostname or IP.
 37        - `WINRM_USERNAME` (`str`): WinRM username.
 38        - `WINRM_PASSWORD` (`str`): WinRM password.
 39        - `WINRM_DOMAIN` (`str`, optional): Domain name, if applicable.
 40        - `WINRM_TRANSPORT` (`str`): Transport method (e.g., 'ntlm', 'kerberos').
 41    - **cmd** (`str`): The command to run (e.g., `ipconfig`).
 42    - **params** (`list`, optional): List of command-line parameters. Defaults to empty list.
 43
 44    ### Returns
 45    - **dict**:
 46      A dictionary with keys:
 47        - `retc` (`int`): The status code from the command execution.
 48        - `stdout` (`str`): The standard output as a string.
 49        - `stderr` (`str`): The standard error as a string.
 50    - **None**:
 51      If the connection or execution fails.
 52
 53    ### Notes
 54    - Converts `std_out` and `std_err` from bytes to Unicode text.
 55    - Uses `winrm.Session().run_cmd()`.
 56
 57    ### Example
 58    >>> result = run_cmd(args, 'ipconfig')
 59    >>> print(result['stdout'])
 60    """
 61    try:
 62        auth = (args.WINRM_USERNAME, args.WINRM_PASSWORD)
 63        if getattr(args, 'WINRM_DOMAIN', None):
 64            auth = ('{}@{}'.format(args.WINRM_USERNAME, args.WINRM_DOMAIN), args.WINRM_PASSWORD)
 65
 66        session = winrm.Session(
 67            args.WINRM_HOSTNAME,
 68            auth=auth,
 69            transport=args.WINRM_TRANSPORT,
 70        )
 71
 72        if params is None:
 73            params = []
 74
 75        result = session.run_cmd(cmd, params)
 76        return {
 77            'retc': result.status_code,
 78            'stdout': txt.to_text(result.std_out),
 79            'stderr': txt.to_text(result.std_err),
 80        }
 81    except Exception:
 82        return None
 83
 84
 85def run_ps(args, cmd):
 86    """
 87    Execute a PowerShell command over WinRM and return the result.
 88
 89    This function runs a PowerShell command remotely on a Windows machine via WinRM.
 90    It handles authentication with or without a domain and returns the result as a dictionary.
 91
 92    ### Parameters
 93    - **args** (object):
 94      An object containing:
 95        - `WINRM_HOSTNAME` (`str`): The target hostname or IP.
 96        - `WINRM_USERNAME` (`str`): WinRM username.
 97        - `WINRM_PASSWORD` (`str`): WinRM password.
 98        - `WINRM_DOMAIN` (`str`, optional): Domain name, if applicable.
 99        - `WINRM_TRANSPORT` (`str`): Transport method (e.g., 'ntlm', 'kerberos').
100    - **cmd** (`str`): The PowerShell command to run.
101
102    ### Returns
103    - **dict**:
104      A dictionary with keys:
105        - `retc` (`int`): The status code from the command execution.
106        - `stdout` (`str`): The standard output as a string.
107        - `stderr` (`str`): The standard error as a string.
108    - **None**:
109      If the connection or execution fails.
110
111    ### Notes
112    - Converts `std_out` and `std_err` from bytes to Unicode text.
113    - Uses `winrm.Session().run_ps()`.
114
115    ### Example
116    >>> result = run_ps(args, 'Get-Process')
117    >>> print(result['stdout'])
118    """
119    try:
120        auth = (args.WINRM_USERNAME, args.WINRM_PASSWORD)
121        if args.WINRM_DOMAIN:
122            auth = ('{}@{}'.format(args.WINRM_USERNAME, args.WINRM_DOMAIN), args.WINRM_PASSWORD)
123
124        session = winrm.Session(
125            args.WINRM_HOSTNAME,
126            auth=auth,
127            transport=args.WINRM_TRANSPORT,
128        )
129
130        result = session.run_ps(cmd)
131        return {
132            'retc': result.status_code,
133            'stdout': txt.to_text(result.std_out),
134            'stderr': txt.to_text(result.std_err),
135        }
136    except Exception:
137        return None