PyWinOS

The cross-platform tool to work with remote and local Windows OS.

PyWinOS uses the Windows Remote Manager (WinRM) service. It can establish connection to a remote server based on Windows OS and execute commands:

• PowerShell
• Command line
• WMI.

It can execute commands locally using subprocess and command-line too.

For more information on WinRM, please visit Microsoft’s WinRM site It based on pywinrm.

PyWinOS (main methods) returns WinResponse object with properties:

• exited: Exit code (int)
• stdout: standard output stream (converted to dict if got appropriate content)
• stderr: standard err stream
• ok: Is exit code == 0 (bool)

Installation

For most users, the recommended method to install is via pip:

pip install pywinos

or from source:

python setup.py install

Import

from pywinos import WinOSClient

Usage (remote server)

Run PowerShell:

from pywinos import WinOSClient

tool = WinOSClient(host='172.16.0.126', username='administrator', password='qqq123aaa', log_enabled=True)
response = tool.run_ps(cmd='$PSVersionTable.PSVersion')

# 2022-07-17 23:04:22 | INFO      | WinOSClient         232 | 172.16.0.48    PS | $PSVersionTable.PSVersion
# 2022-07-17 23:04:23 | INFO      | WinOSClient         264 | 172.16.0.48    PS | 0:
# 	Major  Minor  Build  Revision
# -----  -----  -----  --------
# 5      1      17763  316

from pywinos import WinOSClient

tool = WinOSClient(host='172.16.0.126', username='administrator', password='qqq123aaa', log_enabled=True)
response = tool.run_ps('Get-Service -Name "ALG" | ConvertTo-Json')

# 2022-07-18 21:02:02 | INFO      | WinOSClient         220 | 172.16.0.48    | PS  | Get-Service -Name "ALG" | ConvertTo-Json -Depth 1
# 2022-07-18 21:02:03 | INFO      | WinOSClient         252 | 172.16.0.48    | PS  | 0:
# 	{'CanPauseAndContinue': False, 'CanShutdown': False, 'CanStop': False, 'DisplayName': 'App...

print(response.stdout)
# {'CanPauseAndContinue': False, 'CanShutdown': False, 'CanStop': False, 'DisplayName': 'Application Layer Gatew...}

print(response.stderr)
# None

print(response.ok)
# True

Run command line:

from pywinos import WinOSClient

tool = WinOSClient('172.16.0.126', 'administrator', 'P@ssw0rd', log_enabled=False)
response = tool.run_cmd(cmd='whoami')

# 2022-07-17 23:06:46 | INFO      | WinOSClient         232 | 172.16.0.48    CMD | whoami
# 2022-07-17 23:06:46 | INFO      | WinOSClient         264 | 172.16.0.48    CMD | 0:
# 	autovm1\administrator

Instance of a WinResponse can be pretty printed

from pywinos import WinOSClient

client = WinOSClient('172.16.0.48', 'administrator', 'zzz123ZZZ', log_enabled=True, log_level='DEBUG')
result = client.is_service_running('alg')
print(result)

{
  "exit_code": 0,
  "ok": true,
  "stdout": "autovm1\\administrator",
  "stderr": "",
  "cmd": "whoami",
  "raw": "<Responsecode0, out b'autovm1\\administrato', err b''>"
}

• exit_code: Exit code (int)
• ok: Is exit code == 0 (bool)
• stdout: standard output stream
• stderr: standard err stream
• cmd: Command sent
• raw: Response class from WinRM

Main low-level methods to work with local/remote Windows OS:

• run_cmd
• run_cmd_local
• run_ps
• run_ps_local

High-level methods:

• Use list_all_methods() to get list of all methods.

Changelog

UNRELEASED

2.0.10 (19.06.2024)

• "command" param from the .run_cmd() changed to the "cmd"
• FAQ fixed

WARNING: Use .run_*** methods only! All High-level methods will be deprecated in future releases!

2.0.9 (19.06.2024) (WITHDRAWN)

• "command" param from the .run_cmd() changed to the "cmd"

2.0.8 (9.03.2023)

run_ps and run_cmd extended to use insecure=False param In order to pass double-hop trouble, cert will be ignored on a destination host. Just enable wsman server: Enable-WSManCredSSP -Role Server -Force

2.0.7 (8.03.2023)

• run_cmd() extended to use "use_cred_ssp=False" param
• "logger_enabled" param renamed to the "log_enabled"
• _session renamed to the __create_session; debug log added
• _protocol renamed to the __set_protocol; debug log added
• __client refactored; debug log added
• _get_transport_name renamed to the __get_transport_name
• get_hash_local() obsolete
• debug_info() obsolete

2.0.6 (20.02.2023)

run PS and CMD local changed to log warning in exit code==0 and stderr contains some text

2.0.5 (20.02.2023)

run_ps_local() fixed

2.0.4 (24.10.2022)

• run PS and CMD local fixed
• ping method removed
• debug print removed

2.0.3 (24.10.2022)

move_item fixed

2.0.2 (18.10.2022)

In case warning detected in STDERR with 0 exit code - warning will be logged. Execution will not be disrupted.

New method added:

• move_item

2.0.1 (11.10.2022)

• Execution command changed in case of stderr contains smth. Exception will be raised
• Log improved
• decomposition performed
• get_directory_size renamed to the get_dir_size
• instance print fixed

2.0.0 (04.08.2022)

NEW version without back compatibility.

• Response is dict by default.
• Logger updated

1.2.8a (18.07.2022)

Changes reverted and refactored

• Response is a WinResponse class with properties (see this readme from a very beginning)
• stdout will be converted to dict if possible
• ResponseParser renamed to the WinResponse

1.2.8 (17.07.2022)

Breaking changes

From now on dict with exit_code, ok, stdout, stderr, cmd, raw keys returns

ResponseParser:

• .stdout: try to return json if possible
• .stderr: "CLIXML..." suppressed and returns None if no errors
• obj print returns pretty dict

WinOSClient:

• log_level instance attr added. INFO by default
• log format changed
• debug log added
• run_cmd and run_ps returns dict now
• if stderr is not empty -> log entry + RemoteCommandExecutionError raise
• many methods renamed according commandlet used name
• many high-level methods removed in favor to use "general" method. i.e. get_service_status removed. Use get_service and 'Status' key from dict result
• cmdlet used added into docstring

Renamed:

• remove -> remove_item + "ignore_errors=False" param added
• get_network_adapter_state -> get_net_adapter
• disable_network_adapter -> disable_net_adapter
• enable_network_adapter -> enable_net_adapter
• get_disks -> get_disk and removed dimensions
• get_volumes -> get_volume and removed dimensions

Obsolete:

• all "*_local" high-level methods
• attach_share()
• is_disk_offline
• get_volumes_count : use get_volume

RemoteCommandExecutionError added

1.2.7 (3.06.2022)

• log format changed according to other modules
• get_volumes() fixed to process all volumes (including service volumes without label)
• get_disks() changed. Keys are int now.
• "EntitiesQuantity" key added to bot methods
• FAQ updated

1.2.6 (3.06.2022)

• Logger name changed to 'WinOSClient'
• get_disks() returns dict with disk number as key and dict with disk info as value
• get_volumes() returns dict with volume name as key and dict with volume info as value Both of them have optional param to get info only for specific disk/volume

1.2.5 (29.04.2022)

New methods:

• .get_xml()
• .get_xml_local()

1.2.4 (29.04.2022)

New method added:

• .get_disks() returns list of dict with disks info

Method updated:

• .get_volumes(): added dimension=None param. Sizes can be converted to "MB" and "GB". To get bytes do not set this param
• .get_volumes() extended with the "SizeUsed" field

1.2.3 (28.04.2022)

New methods added:

• .get_volumes() returns list of dicts with volumes info
• .get_volumes_count() returns dict including CD-ROMs and system reserved volumes

1.2.2 (22.04.2022)

• .get_process(), .get_process_local(), .get_service_file_version(), .get_service_file_version_local() raise ProcessLookupError if process not found
• .get_service(), .get_service_local() raise ServiceLookupError if service not found
• All method related to xmk handling marked as deprecated
• ServiceLookupError exception added
• Typos fixed

1.2.1 (17.04.2022)

• updated to manage logger state

1.2.0 (6.04.2022)

• External logger used
• Logger moved into class in order to have access to it after inheritance