pypsexec 0.0.1.dev3

Features

With pypsexec you can run commands of a remote Windows host like you would with PsExec. Current you can use pypsexec to do the following;

• Run as a specific local or domain user or the user

• Run as the local SYSTEM account

• Run as an interactive process

• Specify the session the interactive process should run on

• Specify the run level of the user token, highest or limited

• Set the priority of the process

• Set a timeout for the remote process

• Send input through the stdin pipe to the running process

• Set the processors the process can run on

Further Info

While this info is not necessary for you to use this library it can help people understand what is happening under the hood. This library runs the following steps when running a command;

• Create an SMB connection to the host

• Copies across the PAExec binary to the ADMIN$ share of the remote host

• Binds the Windows Service Manager to the opened IPC$ tree using RPC

• Creates and starts a Windows service as the SYSTEM account to run the binary copied

• Connect to the PAExec named pipe the service creates

• Sends the process details to the PAExec service through the pipe

• Send a request to the PAExec service to start the process based on the settings sent

• Connect to the newly spawned process’s stdout, stderr, stdin pipe (if not interactive or async)

• Read the stdout/stderr pipe until the process is complete

• Get the return code of the new process

• Stop and remove the PAExec service

• Remove the PAExec binary from the ADMIN$ share

• Disconnects from the SMB connection

In the case of a failed process, the PAExec service and binary may not be removed from the host and may need to be done manually. This is only the case for a critical error or the cleanup functions not being called.

By default the data being sent to and from the server is encrypted to stop people listening in on the network from snooping your data. Unfortunately this uses SMB encryption which was added in the SMB 3.x dialects so hosts running Windows 7, Server 2008, or Server 2008 R2 will not work with encryption.

This means that any data sent over the wire on these older versions of Windows is viewable by anyone reading those packets. Any input or output of the process comes through these packets so any secrets sent over the network won’t be encrypted. PAExec tries to reduce this risk by doing a simple XOR scramble of the settings set in run_executable so it isn’t plaintext but it can be decoded by someone who knows the protocol.

Requirements

• Python 2.7, 2.7, 3.4-3.6

• smbprotocol

To install pypsexec, simply run

pip install pypsexec

This will download the required packages that are required and get your Python environment ready to do.

Out of the box, pypsexec supports authenticating to a Windows host with NTLM authentication but users in a domain environment can take advantage of Kerberos authentication as well for added security. Currently the Windows implementation of the smbprotocol does not support Kerberos auth but for other platforms you can add support by installing the kerberos components of smbprotocol;

# for Debian/Ubuntu/etc:
sudo apt-get install gcc python-dev libkrb5-dev
pip install smbprotocol[kerberos]

# for RHEL/CentOS/etc:
sudo yum install gcc python-devel krb5-devel krb5-workstation python-devel
pip install smbprotocol[kerberos]

From there to check that everything was installed correctly and the correct GSSAPI extensions are available on that host, run

try:
    from gssapi.raw import inquire_sec_context_by_oid
    print("python-gssapi extension is available")
except ImportError as exc:
    print("python-gssapi extension is not available: %s" % str(exc))

If it isn’t available, then either a newer version of the system’s gssapi implementation needs to be setup and python-gssapi compiled against that newer version.

Remote Host Requirements

The goal of this package to be able to run executables on a vanilla remote Windows host with as little setup as possible. Unfortunately there is still some setup required to get working depending on the OS version and type that is being used. What pypsexec requires on the host is;

• SMB to be up and running on the Windows port and readable from the Python host

• The ADMIN$ share to be enabled with read/write access of the user configured

• The above usually means the configured user is an administrator of the Windows host

• At least SMB 2 on the host (Server 2008 and newer)

# PowerShell (Windows 8 and Server 2012 or Newer)
New-NetFirewallRule -Name SMB -DisplayName "SMB Inbound" -Enabled $true -Direction Inbound -Protocol TCP -Action Allow -LocalPort 445

# CMD (All OS's)
netsh advfirewall firewall add rule name=SMB dir=in action=allow protocol=TCP localport=445

$reg_path = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System"
$reg_prop_name = "LocalAccountTokenFilterPolicy"

$reg_key = Get-Item -Path $reg_path
$reg_prop = $reg_key.GetValue($reg_prop_name)
if ($null -ne $reg_prop) {
    Remove-ItemProperty -Path $reg_path -Name $reg_prop_name
}

New-ItemProperty -Path $reg_path -Name $reg_prop_name -Value 1 -PropertyType DWord

$reg_path = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System"
$reg_prop_name = "EnableLUA"

$reg_key = Get-Item -Path $reg_path
$reg_prop = $reg_key.GetValue($reg_prop_name)
if ($null -ne $reg_prop) {
    Remove-ItemProperty -Path $reg_path -Name $reg_prop_name
}

New-ItemProperty -Path $reg_path -Name $reg_prop_name -Value 0 -PropertyType DWord

Examples

Here is an example of how to run a command with this library

from pypsexec.client import Client

# creates an encrypted connection to the host with the username and password
c = Client("hostname", username="username", password="password")

# set encrypt=False for Windows 7, Server 2008
c = Client("hostname", username="username", password="password", encrypt=False)

# if Kerberos is available, this will use the default credentials in the
# credential cache
c = Client("hostname")

# you can also tell it to use a specific Kerberos principal in the cache
# without a password
c = Client("hostname", username="username@DOMAIN.LOCAL")

c.connect()
try:
    c.create_service()

    # After creating the service, you can run multiple exe's without
    # reconnecting

    # run a simple cmd.exe program with arguments
    stdout, stderr, rc = c.run_executable("cmd.exe",
                                          arguments="/c echo Hello World")

    # run whoami.exe as the SYSTEM account
    stdout, stderr, rc = c.run_executable("whoami.exe", use_system_account=True)

    # run command asynchronously (in background), the rc is the PID of the spawned service
    stdout, stderr, rc = c.run_executable("longrunning.exe",
                                          arguments="/s other args",
                                          async=True)

    # run whoami.exe as a specific user
    stdout, stderr, rc = c.run_executable("whoami",
                                          arguments="/all",
                                          username="local-user",
                                          password="password",
                                          run_elevated=True)
finally:
    c.remove_service()
    c.disconnect()

In the case of a fatal failure, this project may leave behind some the PAExec payload in C:\Windows or the service still installed. As these are uniquely named they can build up over time. They can be manually removed but you can also use pypsexec to cleanup them all up at once. To do this run

from pypsexec.client import Client

c = Client("server", username="username", password="password")
c.connect()
c.cleanup()  # this is where the magic happens
c.disconnect()

The script will delete any files that match C:\Windows\PAExec-* and any services that match PAExec-*. For an individual run, the remove_service() function should still be used.

Logging

This library uses the builtin Python logging library and can be used to find out what is happening in the pypsexec process. Log messages are logged to the pypsexec named logger as well as pypsexec.* where * is each python script in the pypsexec directory.

A way to enable the logging in your scripts through code is to add the following to the top of the script being used;

import logging

logger = logging.getLogger("pypsexec")
logger.setLevel(logging.DEBUG)  # set to logging.INFO if you don't want DEBUG logs
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - '
                              '%(message)s')
ch.setFormatter(formatter)
logger.addHandler(ch)

These logs are generally useful when debugging issues as they give you a more step by step snapshot of what it is doing and what may be going wrong. The debug level will also print out a human readable string of each SMB packet that is sent out from the client but this level can get really verbose.

Testing

To this module, you need to install some pre-requisites first. This can be done by running;

pip install -r requirements-test.txt

# you can also run tox by installing tox
pip install tox

From there to run the basic tests run;

py.test -v --pep8 --cov pypsexec --cov-report term-missing

# or with tox 2.7, 2.7, 3.4, 3.5, and 3.6
tox

There are extra tests that only run when certain environment variables are set. To run these tests set the following variables;

• PYPSEXEC_SERVER: The hostname or IP to a Windows host

• PYPSEXEC_USERNAME: The username to use authenticate with

• PYPSEXEC_PASSWORD: The password for PYPSEXEC_USERNAME

From there, you can just run tox or py.test with these environment variables to run the integration tests.

Future

Some things I would be interested in looking at adding in the future would be

• Add a Python script that can be called to run adhoc commands like PsExec.exe