Skip to main content

The cross-platform tool to execute PowerShell and commandline commands remotely and locally.

Project description

PyPI version Build Status Coverage Status

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(command='$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(command='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.9 (19.06.2024)
  • "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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pywinos-2.0.9.tar.gz (18.6 kB view hashes)

Uploaded Source

Built Distribution

pywinos-2.0.9-py3-none-any.whl (14.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page