The cross-platform tool to execute PowerShell and commandline commands remotely and locally.
Project description
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 streamok
: 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 streamstderr
: standard err streamcmd
: Command sentraw
: 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.