slavedriver

A series of python connectors and transport layers to:

1. Give a programmer/user remote access to a machine regardless of method (SSH/Windows rm).
2. Provide a common interface for performing common operations regardless of the OS flavor connected.
3. Provide remote access to files and processes much like they were local.

What makes this project different from projects like ansible.

1. Ansible requires a mechanism for scripting out playbooks rather than focus on core logic and integration into other scripts and api's. IE. you have to run a playbook rather than process logic inside a script to do complex or custom things. This makes certain operations a lot of work for something simple. A really good example of this is doing something like forcing a reboot and reconnecting to the machine gracefully or interacting with scripts in an pexpect like manner because they have no headleass mode of operation.
2. The original goal of this project was to test hardware, not prop up thousands of virtual machines with the same configuration. The assumptions made by this project are different from projects like ansible for this reason.
3. The mechanisms to interface with machines are meant to be low level and potentially abstractible across operating systems. Operations like formatting disks, making file systems, etc...
4. As opposed to the initial goal of ansible, this project needs to be zero setup on the client. Although some efforts might be made to identify the operating system, nothing needs to be nor should be setup on the operating system.
5. This project was meant to be light weight. The only thing you need to do is include this library in your project and fire away. Testing environments are ephemeral; your test shouldn't fail because someone change a fundamental way the software is installed or run.

Ansible was developed at the same time this project was initially developed. There are many parallels, but fundamental differences that should be advantageous to test developers.

Connecting to Windows (WinRM)

slavedriver connects to Windows hosts over WinRM and auto-negotiates the authentication transport so the same code logs in for any user on any configuration, driven from Linux or Windows:

1. NTLM (tried first) — message-encrypted (sealed) even over plain HTTP on port 5985, so the host needs no Basic auth and no AllowUnencrypted. It authenticates local accounts (username) and domain/Active-Directory accounts (DOMAIN\username, via the server's pass-through to its DC).
2. Kerberos — only when the optional libraries are installed (see below); covers hardened AD hosts that have disabled NTLM.
3. SSL/HTTPS (5986) and finally legacy plaintext Basic, as fallbacks.

This replaces the old insecure guidance (Basic="true" + AllowUnencrypted="true"), which only ever worked for local accounts.

Host setup

Idempotent PowerShell scripts live in scripts/windows/, run as Administrator on the target (a dedicated/disposable VM is recommended):

Script	Purpose	Reboots?
Setup-WinRM.ps1	Enable WinRM securely (NTLM/Negotiate on, Basic & AllowUnencrypted off). -EnableHttps adds a self-signed 5986 listener.	No
Setup-TestLocalUser.ps1	Create a local test account and grant it WinRM access.	No
Setup-TestADUser.ps1	Promote a virgin Windows Server into its own AD forest (Domain Controller) and create a domain user. Phase-aware: first run promotes (box reboots), re-run creates the user.	Yes

# 1. Always: configure WinRM securely.
powershell -ExecutionPolicy Bypass -File .\scripts\windows\Setup-WinRM.ps1
# 2a. Local-user target:
powershell -ExecutionPolicy Bypass -File .\scripts\windows\Setup-TestLocalUser.ps1 -Username sdtest
# 2b. Domain-user target (Windows Server only; run twice, around the reboot):
powershell -ExecutionPolicy Bypass -File .\scripts\windows\Setup-TestADUser.ps1 -DomainName slavedriver.test -Username sdtest

Connecting from Python

from slavedriver.slave import Slave

# Local account — no domain needed; transport auto-negotiates to NTLM.
s = Slave(hostname="10.0.0.5", username="sdtest", password="P@ss")
s.connect()

# Domain / Active-Directory account — just pass the domain.
s = Slave(hostname="10.0.0.10", username="sdtest", password="P@ss", domain="SLAVEDRIVER")
s.connect()

Slave(..., winrm_options={...}) is an optional escape hatch for non-default hosts — keys: transport (pin one and skip negotiation), scheme, winrm_port, server_cert_validation ('validate' for strict TLS; default 'ignore' for self-signed test certs), message_encryption, read_timeout_sec, operation_timeout_sec.

Kerberos (hardened AD that disables NTLM)

pip install slavedriver[kerberos]

Negotiation then uses Kerberos automatically when its libraries are present. On Linux this also needs MIT krb5 libraries and a krb5.conf realm pointing at the DC; on domain-joined Windows it works out of the box.

Live tests

The WinRM tests skip themselves unless the relevant env vars point at a real host, so they are CI-safe. Secure local-user test (marker winrm) reads SLAVE_HOST / SLAVE_USER / SLAVE_PASS (+ optional SLAVE_DOMAIN); the domain test (marker winrm_domain) reads SLAVE_DOMAIN_HOST / SLAVE_DOMAIN_USER / SLAVE_DOMAIN_PASS and requires SLAVE_DOMAIN.

SLAVE_HOST=10.0.0.5 SLAVE_USER=sdtest SLAVE_PASS='P@ss' \
    pytest tests/test_winrm_secure.py -m winrm -q

SLAVE_DOMAIN_HOST=10.0.0.10 SLAVE_DOMAIN=SLAVEDRIVER \
SLAVE_DOMAIN_USER=sdtest SLAVE_DOMAIN_PASS='P@ss' \
    pytest tests/test_winrm_domain.py -m winrm_domain -q

Publishing

See PUBLISHING.md for how to release new versions of slavedriver to PyPI using scripts/publish.sh.