path: root/ansible_collections/community/windows/plugins/modules/psexec.py

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: (c) 2018, Jordan Borean <jborean93@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = r'''
---
module: psexec
short_description: Runs commands on a remote Windows host based on the PsExec
  model
description:
- Runs a remote command from a Linux host to a Windows host without WinRM being
  set up.
- Can be run on the Ansible controller to bootstrap Windows hosts to get them
  ready for WinRM.
options:
  hostname:
    description:
    - The remote Windows host to connect to, can be either an IP address or a
      hostname.
    type: str
    required: yes
  connection_username:
    description:
    - The username to use when connecting to the remote Windows host.
    - This user must be a member of the C(Administrators) group of the Windows
      host.
    - Required if the Kerberos requirements are not installed or the username
      is a local account to the Windows host.
    - Can be omitted to use the default Kerberos principal ticket in the
      local credential cache if the Kerberos library is installed.
    - If I(process_username) is not specified, then the remote process will run
      under a Network Logon under this account.
    type: str
  connection_password:
    description:
    - The password for I(connection_user).
    - Required if the Kerberos requirements are not installed or the username
      is a local account to the Windows host.
    - Can be omitted to use a Kerberos principal ticket for the principal set
      by I(connection_user) if the Kerberos library is installed and the
      ticket has already been retrieved with the C(kinit) command before.
    type: str
  port:
    description:
    - The port that the remote SMB service is listening on.
    type: int
    default: 445
  encrypt:
    description:
    - Will use SMB encryption to encrypt the SMB messages sent to and from the
      host.
    - This requires the SMB 3 protocol which is only supported from Windows
      Server 2012 or Windows 8, older versions like Windows 7 or Windows Server
      2008 (R2) must set this to C(no) and use no encryption.
    - When setting to C(no), the packets are in plaintext and can be seen by
      anyone sniffing the network, any process options are included in this.
    type: bool
    default: yes
  connection_timeout:
    description:
    - The timeout in seconds to wait when receiving the initial SMB negotiate
      response from the server.
    type: int
    default: 60
  executable:
    description:
    - The executable to run on the Windows host.
    type: str
    required: yes
  arguments:
    description:
    - Any arguments as a single string to use when running the executable.
    type: str
  working_directory:
    description:
    - Changes the working directory set when starting the process.
    type: str
    default: C:\Windows\System32
  asynchronous:
    description:
    - Will run the command as a detached process and the module returns
      immediately after starting the process while the process continues to
      run in the background.
    - The I(stdout) and I(stderr) return values will be null when this is set
      to C(yes).
    - The I(stdin) option does not work with this type of process.
    - The I(rc) return value is not set when this is C(yes)
    type: bool
    default: no
  load_profile:
    description:
    - Runs the remote command with the user's profile loaded.
    type: bool
    default: yes
  process_username:
    description:
    - The user to run the process as.
    - This can be set to run the process under an Interactive logon of the
      specified account which bypasses limitations of a Network logon used when
      this isn't specified.
    - If omitted then the process is run under the same account as
      I(connection_username) with a Network logon.
    - Set to C(System) to run as the builtin SYSTEM account, no password is
      required with this account.
    - If I(encrypt) is C(no), the username and password are sent as a simple
      XOR scrambled byte string that is not encrypted. No special tools are
      required to get the username and password just knowledge of the protocol.
    type: str
  process_password:
    description:
    - The password for I(process_username).
    - Required if I(process_username) is defined and not C(System).
    type: str
  integrity_level:
    description:
    - The integrity level of the process when I(process_username) is defined
      and is not equal to C(System).
    - When C(default), the default integrity level based on the system setup.
    - When C(elevated), the command will be run with Administrative rights.
    - When C(limited), the command will be forced to run with
      non-Administrative rights.
    type: str
    choices:
    - limited
    - default
    - elevated
    default: default
  interactive:
    description:
    - Will run the process as an interactive process that shows a process
      Window of the Windows session specified by I(interactive_session).
    - The I(stdout) and I(stderr) return values will be null when this is set
      to C(yes).
    - The I(stdin) option does not work with this type of process.
    type: bool
    default: no
  interactive_session:
    description:
    - The Windows session ID to use when displaying the interactive process on
      the remote Windows host.
    - This is only valid when I(interactive) is C(yes).
    - The default is C(0) which is the console session of the Windows host.
    type: int
    default: 0
  priority:
    description:
    - Set the command's priority on the Windows host.
    - See U(https://msdn.microsoft.com/en-us/library/windows/desktop/ms683211.aspx)
      for more details.
    type: str
    choices:
    - above_normal
    - below_normal
    - high
    - idle
    - normal
    - realtime
    default: normal
  show_ui_on_logon_screen:
    description:
    - Shows the process UI on the Winlogon secure desktop when
      I(process_username) is C(System).
    type: bool
    default: no
  process_timeout:
    description:
    - The timeout in seconds that is placed upon the running process.
    - A value of C(0) means no timeout.
    type: int
    default: 0
  stdin:
    description:
    - Data to send on the stdin pipe once the process has started.
    - This option has no effect when I(interactive) or I(asynchronous) is
      C(yes).
    type: str
requirements:
- pypsexec
- smbprotocol[kerberos] for optional Kerberos authentication
notes:
- This module requires the Windows host to have SMB configured and enabled,
  and port 445 opened on the firewall.
- This module will wait until the process is finished unless I(asynchronous)
  is C(yes), ensure the process is run as a non-interactive command to avoid
  infinite hangs waiting for input.
- The I(connection_username) must be a member of the local Administrator group
  of the Windows host. For non-domain joined hosts, the
  C(LocalAccountTokenFilterPolicy) should be set to C(1) to ensure this works,
  see U(https://support.microsoft.com/en-us/help/951016/description-of-user-account-control-and-remote-restrictions-in-windows).
- For more information on this module and the various host requirements, see
  U(https://github.com/jborean93/pypsexec).
seealso:
- module: ansible.builtin.raw
- module: ansible.windows.win_command
- module: community.windows.win_psexec
- module: ansible.windows.win_shell
author:
- Jordan Borean (@jborean93)
'''

EXAMPLES = r'''
- name: Run a cmd.exe command
  community.windows.psexec:
    hostname: server
    connection_username: username
    connection_password: password
    executable: cmd.exe
    arguments: /c echo Hello World

- name: Run a PowerShell command
  community.windows.psexec:
    hostname: server.domain.local
    connection_username: username@DOMAIN.LOCAL
    connection_password: password
    executable: powershell.exe
    arguments: Write-Host Hello World

- name: Send data through stdin
  community.windows.psexec:
    hostname: 192.168.1.2
    connection_username: username
    connection_password: password
    executable: powershell.exe
    arguments: '-'
    stdin: |
      Write-Host Hello World
      Write-Error Error Message
      exit 0

- name: Run the process as a different user
  community.windows.psexec:
    hostname: server
    connection_user: username
    connection_password: password
    executable: whoami.exe
    arguments: /all
    process_username: anotheruser
    process_password: anotherpassword

- name: Run the process asynchronously
  community.windows.psexec:
    hostname: server
    connection_username: username
    connection_password: password
    executable: cmd.exe
    arguments: /c rmdir C:\temp
    asynchronous: yes

- name: Use Kerberos authentication for the connection (requires smbprotocol[kerberos])
  community.windows.psexec:
    hostname: host.domain.local
    connection_username: user@DOMAIN.LOCAL
    executable: C:\some\path\to\executable.exe
    arguments: /s

- name: Disable encryption to work with WIndows 7/Server 2008 (R2)
  community.windows.psexec:
    hostanme: windows-pc
    connection_username: Administrator
    connection_password: Password01
    encrypt: no
    integrity_level: elevated
    process_username: Administrator
    process_password: Password01
    executable: powershell.exe
    arguments: (New-Object -ComObject Microsoft.Update.Session).CreateUpdateInstaller().IsBusy

- name: Download and run ConfigureRemotingForAnsible.ps1 to setup WinRM
  community.windows.psexec:
    hostname: '{{ hostvars[inventory_hostname]["ansible_host"] | default(inventory_hostname) }}'
    connection_username: '{{ ansible_user }}'
    connection_password: '{{ ansible_password }}'
    encrypt: yes
    executable: powershell.exe
    arguments: '-'
    stdin: |
      $ErrorActionPreference = "Stop"
      $sec_protocols = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::SystemDefault
      $sec_protocols = $sec_protocols -bor [Net.SecurityProtocolType]::Tls12
      [Net.ServicePointManager]::SecurityProtocol = $sec_protocols
      $url = "https://github.com/ansible/ansible-documentation/raw/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
      Invoke-Expression ((New-Object Net.WebClient).DownloadString($url))
      exit
  delegate_to: localhost
'''

RETURN = r'''
msg:
  description: Any exception details when trying to run the process
  returned: module failed
  type: str
  sample: 'Received exception from remote PAExec service: Failed to start "invalid.exe". The system cannot find the file specified. [Err=0x2, 2]'
stdout:
  description: The stdout from the remote process
  returned: success and interactive or asynchronous is 'no'
  type: str
  sample: Hello World
stderr:
  description: The stderr from the remote process
  returned: success and interactive or asynchronous is 'no'
  type: str
  sample: Error [10] running process
pid:
  description: The process ID of the asynchronous process that was created
  returned: success and asynchronous is 'yes'
  type: int
  sample: 719
rc:
  description: The return code of the remote process
  returned: success and asynchronous is 'no'
  type: int
  sample: 0
'''

import traceback

from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils._text import to_bytes, to_text

PYPSEXEC_IMP_ERR = None
try:
    from pypsexec import client
    from pypsexec.exceptions import PypsexecException, PDUException, SCMRException
    from pypsexec.paexec import ProcessPriority
    from smbprotocol.exceptions import SMBException, SMBAuthenticationError, \
        SMBResponseException
    import socket
    HAS_PYPSEXEC = True
except ImportError:
    PYPSEXEC_IMP_ERR = traceback.format_exc()
    HAS_PYPSEXEC = False

KERBEROS_IMP_ERR = None
try:
    import gssapi  # pylint: disable=unused-import
    # GSSAPI extension required for Kerberos Auth in SMB
    from gssapi.raw import inquire_sec_context_by_oid  # pylint: disable=unused-import
    HAS_KERBEROS = True
except ImportError:
    KERBEROS_IMP_ERR = traceback.format_exc()
    HAS_KERBEROS = False


def remove_artifacts(module, client):
    try:
        client.remove_service()
    except (SMBException, PypsexecException) as exc:
        module.warn("Failed to cleanup PAExec service and executable: %s"
                    % to_text(exc))


def main():
    module_args = dict(
        hostname=dict(type='str', required=True),
        connection_username=dict(type='str'),
        connection_password=dict(type='str', no_log=True),
        port=dict(type='int', required=False, default=445),
        encrypt=dict(type='bool', default=True),
        connection_timeout=dict(type='int', default=60),
        executable=dict(type='str', required=True),
        arguments=dict(type='str'),
        working_directory=dict(type='str', default=r'C:\Windows\System32'),
        asynchronous=dict(type='bool', default=False),
        load_profile=dict(type='bool', default=True),
        process_username=dict(type='str'),
        process_password=dict(type='str', no_log=True),
        integrity_level=dict(type='str', default='default',
                             choices=['default', 'elevated', 'limited']),
        interactive=dict(type='bool', default=False),
        interactive_session=dict(type='int', default=0),
        priority=dict(type='str', default='normal',
                      choices=['above_normal', 'below_normal', 'high',
                               'idle', 'normal', 'realtime']),
        show_ui_on_logon_screen=dict(type='bool', default=False),
        process_timeout=dict(type='int', default=0),
        stdin=dict(type='str')
    )
    result = dict(
        changed=False,
    )
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=False,
    )

    process_username = module.params['process_username']
    process_password = module.params['process_password']
    use_system = False
    if process_username is not None and process_username.lower() == "system":
        use_system = True
        process_username = None
        process_password = None

    if process_username is not None and process_password is None:
        module.fail_json(msg='parameters are required together when not '
                             'running as System: process_username, '
                             'process_password')
    if not HAS_PYPSEXEC:
        module.fail_json(msg=missing_required_lib("pypsexec"),
                         exception=PYPSEXEC_IMP_ERR)

    hostname = module.params['hostname']
    connection_username = module.params['connection_username']
    connection_password = module.params['connection_password']
    port = module.params['port']
    encrypt = module.params['encrypt']
    connection_timeout = module.params['connection_timeout']
    executable = module.params['executable']
    arguments = module.params['arguments']
    working_directory = module.params['working_directory']
    asynchronous = module.params['asynchronous']
    load_profile = module.params['load_profile']
    elevated = module.params['integrity_level'] == "elevated"
    limited = module.params['integrity_level'] == "limited"
    interactive = module.params['interactive']
    interactive_session = module.params['interactive_session']

    priority = {
        "above_normal": ProcessPriority.ABOVE_NORMAL_PRIORITY_CLASS,
        "below_normal": ProcessPriority.BELOW_NORMAL_PRIORITY_CLASS,
        "high": ProcessPriority.HIGH_PRIORITY_CLASS,
        "idle": ProcessPriority.IDLE_PRIORITY_CLASS,
        "normal": ProcessPriority.NORMAL_PRIORITY_CLASS,
        "realtime": ProcessPriority.REALTIME_PRIORITY_CLASS
    }[module.params['priority']]
    show_ui_on_logon_screen = module.params['show_ui_on_logon_screen']

    process_timeout = module.params['process_timeout']
    stdin = module.params['stdin']

    if (connection_username is None or connection_password is None) and \
            not HAS_KERBEROS:
        module.fail_json(msg=missing_required_lib("gssapi"),
                         execption=KERBEROS_IMP_ERR)

    win_client = client.Client(server=hostname, username=connection_username,
                               password=connection_password, port=port,
                               encrypt=encrypt)

    try:
        win_client.connect(timeout=connection_timeout)
    except SMBAuthenticationError as exc:
        module.fail_json(msg='Failed to authenticate over SMB: %s'
                             % to_text(exc))
    except SMBResponseException as exc:
        module.fail_json(msg='Received unexpected SMB response when opening '
                             'the connection: %s' % to_text(exc))
    except PDUException as exc:
        module.fail_json(msg='Received an exception with RPC PDU message: %s'
                             % to_text(exc))
    except SCMRException as exc:
        module.fail_json(msg='Received an exception when dealing with SCMR on '
                             'the Windows host: %s' % to_text(exc))
    except (SMBException, PypsexecException) as exc:
        module.fail_json(msg=to_text(exc))
    except socket.error as exc:
        module.fail_json(msg=to_text(exc))

    # create PAExec service and run the process
    result['changed'] = True
    b_stdin = to_bytes(stdin, encoding='utf-8') if stdin else None
    run_args = dict(
        executable=executable, arguments=arguments, asynchronous=asynchronous,
        load_profile=load_profile, interactive=interactive,
        interactive_session=interactive_session,
        run_elevated=elevated, run_limited=limited,
        username=process_username, password=process_password,
        use_system_account=use_system, working_dir=working_directory,
        priority=priority, show_ui_on_win_logon=show_ui_on_logon_screen,
        timeout_seconds=process_timeout, stdin=b_stdin
    )
    try:
        win_client.create_service()
    except (SMBException, PypsexecException) as exc:
        module.fail_json(msg='Failed to create PAExec service: %s'
                         % to_text(exc))

    try:
        proc_result = win_client.run_executable(**run_args)
    except (SMBException, PypsexecException) as exc:
        module.fail_json(msg='Received error when running remote process: %s'
                         % to_text(exc))
    finally:
        remove_artifacts(module, win_client)

    if asynchronous:
        result['pid'] = proc_result[2]
    elif interactive:
        result['rc'] = proc_result[2]
    else:
        result['stdout'] = proc_result[0]
        result['stderr'] = proc_result[1]
        result['rc'] = proc_result[2]

    # close the SMB connection
    try:
        win_client.disconnect()
    except (SMBException, PypsexecException) as exc:
        module.warn("Failed to close the SMB connection: %s" % to_text(exc))

    module.exit_json(**result)


if __name__ == '__main__':
    main()