waft.system.nodes.windows_node module

class waft.system.nodes.windows_node.WindowsNode(client: ClientBase)

Bases: BaseNode

Node for windows specific functionality

add_to_path(path: str | PurePath)
Add given path to path on node.

Fabric does not prepend env vars properly for Windows, so a different approach must be used to Unix machines

Parameters:

path – String of path to add to PATH

clone_ssh_key_auth(username: str)

Clone SSH key authorization to another system user account.

Parameters:

username (str) – Target system account username

copy_file(path_from: PurePath, path_to: PurePath)

Copy a file

create_user(username: str, password: str | None = None) → str

Create a system user account.

Parameters:

  • username (str) – New system account username

  • password (Optional[str]) – New user’s password. Defaults to existing user’s password or a new system generated value.

Returns:

Password for the new user account

Return type:

str

delete_registry_value(registry_path: str, name: str)

Delete the value for a registry item based on name and path

Parameters:

  • registry_path – Path to registry item to delete

  • name – name of registry item to delete

delete_user(username: str)

Delete a system user account.

Parameters:

username (str) – System account username

directory_exists(directory: PurePath) → bool

Check if the given directory exists on the node and return boolean value

Parameters:

directory – Directory path to check exists

file_exists(filepath: PurePath) → bool

Check if the given file exists on the node and return boolean value.

Parameters:

filepath (PurePath) – The path to the file to check.

Returns:

True if the file exists, False otherwise.

Return type:

bool

find_network_route(ip_address: str, optional_params: List[str] | None = None) → str

Retrieve the network route to a specified IP address on a Windows system.

This method uses the PowerShell Find-NetRoute cmdlet to find the network route for the given IP address.

Parameters:

  • optional_params – Optional parameters for Find-NetRoute -RemoteIPAddress

  • ip_address (str) – The IP address for which to find the network route.

Returns:

The output from the Find-NetRoute command, which includes the route details.

Return type:

str

get_dns_server_addresses() → set[str]

Get the IP addresses of the currently configured DNS servers.

Returns:

Set of DNS server addresses

Return type:

set[str]

get_domain_ips(domain: str) → List[IPv4Address | IPv6Address]

Get IPv4 and IPv6 addresses for a domain and its www subdomain.

Parameters:

domain (str) – The domain to resolve.

Returns:

A list of IPs

Return type:

list

get_registry_value(registry_path: str, name: str) → dict

Get a specific item value for a given registry key path

Parameters:

  • registry_path – Path to registry items to query

  • name – name of registry item to query value for

get_registry_values(registry_path: str, name: str | None = None) → dict

Get all item values for a given registry key path

Parameters:

  • registry_path – Path to registry items to query

  • name – name of registry item to query value for

get_sha256_of_file(remote_file_path: PurePath) → str | None

Get the sha256 of a file on the node

get_windows_system_info(csv: bool = False) → str

Runs systeminfo command on windows machines to get information about the system.

Running the systeminfo command can take a second or two to run so we cache it :param csv: If set to True the output will be put into a more parseable csv format

Returns: str of windows system info

getenv(key: str, default: Any = None) → Any

Return an environment variable value.

Parameters:

  • key (str) – Environment variable name

  • default (Any, optional) – Value to return if variable is not set. Defaults to None.

Returns:

environment variable value

Return type:

Any

property home_dir: str

Return the full path to the home directory of the user on the current node

property hostname: str

Returns the hostname of the system

install_packages(package_names: list[str], arguments: List[str] | None = None)

Install packages with given names

Parameters:

  • package_names – List of names of packages to be installed

  • arguments – Optional list of additional arguments to be passed to package manager

install_pstools()

Download and install the PSTools utilities suite.

For reference:

https://learn.microsoft.com/en-us/sysinternals/downloads/pstools https://learn.microsoft.com/en-us/previous-versions/technet-magazine/cc162490(v=msdn.10)?redirectedfrom=MSDN

install_uv(version: str | None = None)

Install uv on the node

Parameters:

version (Optional[str]) – Specific uv version to install. Installs the latest by default.

install_wireless_networking()

Install configurable wireless networking components.

is_process_running(pid: str) → bool

Return boolean indicating if process with given PID is running

Parameters:

pid – Process ID to check if is running

is_service_running(service: str) → bool

Return boolean indicating if service of given name is running

keyring_exec(*args, secret: str | None = None) → str

Execute the keyring CLI.

Parameters:

  • args (str) – Keyring command options to execute.

  • secret (Optional[str]) – Secret input.

Returns:

Keyring command output.

Return type:

str

Link file at given path

Parameters:

  • source_file – Path to file to link

  • target_file – Path to file to link to

  • sudo – Boolean indicating if command should be run using sudo

  • link_type – Link type

list_applications_matching_name(application_name: str) → List[Dict]

Retrieves a list of applications installed on a remote Windows system that match the specified application name, formatted as a list of dictionaries with application details.

Args:

application_name (str): Name of the application to match against installed products.

Returns:

List[Dict]: A list of dictionaries, each containing details of a matching application, such as

‘IdentifyingNumber’, ‘Name’, and ‘LocalPackage’.

make_directory(directory: PurePath, recursive: bool = True, sudo: bool = False)

Create given directory

Parameters:

  • directory – Directory path to create

  • recursive – If set to True all parent directories will be created as well

  • sudo – If set to True the command will be run with sudo permissions

move_file(path_from: PurePath, path_to: PurePath)

Move a file or dir from one path to another

newest_file_in_dir(directory: PurePath, tstamp: Literal['atime', 'ctime', 'mtime']) → PurePath

Return the most recently modified file

Parameters:

  • directory – PurePath object pointing to the directory in question

  • tstamp – Type of timestamp to sort by

norm_path

alias of PureWindowsPath

property os_name: str

Returns the name of the OS e.g. Microsoft Windows 11 Pro

property os_version: str

Returns the version of the OS e.g. 10.0.22631 N/A Build 22631

platform: Platforms = 'windows'
property platform_is_windows: bool

Return boolean indicating whether system is a Windows-based platform

Returns:

True if node is a Windows-based platform, False otherwise

Return type:

bool

python: str = 'python'
read_file(file_path: str | PurePath, sudo: bool = False) → str

Read the contents of a remote file.

Parameters:

  • file_path (str | PurePath) – Path of the file on the remote system to read

  • sudo (bool) – If set to True the command will run with sudo permissions. Defaults to False.

Returns:

file contents

Return type:

str

remove_directory(directory: PurePath, recursive: bool = False)

Remove given directory

Parameters:

  • directory – Directory path to remove

  • recursive – If set to true all contained directories will be deleted as well, otherwise an exception will be raised if there are subdirectories

remove_file(filepath: PurePath, sudo: bool = False)

Remove file at given filepath

resolve_dns_name(domain_name: str | None = None, type: str | None = None, extract: ResolveDnsNameExtractionTypes | None = None, **kwargs: Any) → str

Check dns resolution of a domain name.

Parameters:

  • domain_name – Domain to check resolution of

  • type – DNS record type to retrieve e.g. TXT

  • extract – For the PowerShell command we can extract a particular element

  • **kwargs – Additional optional parameters

Returns: Output from DNS query.

restart_ssh_server()

Restart SSH server to update PATH to include newly added variables

restart_system(delay: int = 0, wait: bool = True)

Restart the node operating system.

Parameters:

  • delay (int, optional) – Time (in minutes) before the restart occurs. Defaults to 0.

  • wait (bool, optional) – True to wait for the system restart to complete (default) or False not to wait.

run_as_system_user(command: str, input: str | None = None, options: str = '') → str

Run a command as the built-in SYSTEM account.

Parameters:

  • command (str) – Command to execute (in PowerShell).

  • input (Optional[str]) – Command input.

  • options (str) – Custom psexec options.

Returns:

PsExec session output

Return type:

str

Raises:

RuntimeError – if command execution is not successful

run_background_command(command: List[str], sudo: bool = False)

Run a command in the background as a context manager, yield the PID of the background process

Parameters:

  • command – List of strings to form the command to be run

  • sudo – Run command with sudo permissions. On Windows this will be run with the “System” account

run_cdp_server()

Start a Chrome Debugging Protocol server on the test node

run_msiexec_command(action: MsiAction, msi_path: str, properties: dict | None = None, quiet_mode: bool = True) → str

Executes an msiexec command on a Windows system for installing or uninstalling MSI packages.

Args:

action (MsiAction): Specifies the action to perform (‘install’ or ‘uninstall’). msi_path (str): The path to the MSI file. properties (dict, optional): A dictionary of properties to pass to msiexec. quiet_mode (bool): If True, the command will execute in quiet mode with no user interaction.

Returns:

str: The output from the command execution.

run_ps_command(command: str | list[str], options: list[str] | None = None, auto_raise: bool = True, input: str | list[str] | None = None) → str

Executes a PowerShell command on a remote Windows system and returns the output as a string.

Args:

command (str | list[str]): PowerShell command to be executed remotely.

Alternate command formats may be expressed using a list of strings.

options (Optional[list[str]]): PowerShell options to be executed remotely. auto_raise (bool): Boolean to raise a RuntimeError if all output is stderr and not stdout input (Optional[str]): Command input.

Returns:

str: The output from the PowerShell command execution.

Raises:

RuntimeError: if the command execution status is non-zero or only stderr text is returned.

run_update()

Run updates on the system

set_registry_value(registry_path: str, name: str, value: str | int, value_type: WindowsRegValueTypes | None = None)

Set the value for a registry item based on name and path

Parameters:

  • registry_path – Path to registry items to set

  • name – name of registry item to set value for

  • value – Value to set for the given registry item

  • value_type – Type of value to set for the given registry item

set_system_environment_variable(variable: str, value: str | int)

Set Environment variable for entire system

Parameters:

  • variable – name of the environment variable to set

  • value – Value to which to set the environment variable

supports_sudo: bool = False
system_secret_del(identifier: str, username: str)

Delete a stored system secret.

Parameters:

  • identifier (str) – Credential identifier.

  • username (str) – Credential username.

system_secret_get(identifier: str, username: str) → dict

Retrieve a stored system secret.

Parameters:

  • identifier (str) – Credential identifier.

  • username (str) – Credential username.

Returns:

Credential as a JSON dictionary

Return type:

dict

system_secret_set(identifier: str, username: str, secret: str)

Set a stored system secret.

Parameters:

  • identifier (str) – Credential identifier.

  • username (str) – Credential username.

  • secret (str) – Credential secret.

property system_type: str

Returns the system type or base architecture e.g. x64-based

touch_file(filepath: PurePath)

Touch file at given path

Parameters:

filepath – Path to file to touch

trace_cmd: str = 'tracert'
uac_lowered()

Context manager to lower UAC settings and return UAC to previous state

uninstall_package(package_name: str, full_purge: bool = True)

Uninstall package with given name

Parameters:

  • package_name – String name of package to be uninstalled

  • full_purge – Boolean indicating if all associated files should be removed upon uninstalling the package