napalm-windows
NAPALM driver for Windows Server 2016+ and Windows 10/11, part of the netOrk
driver family built on napalm-device-types.
Driver name: windows · Role: OSDriver · Transport: PowerShell Remoting
(PSRP) over WinRM via pypsrp.
Tested against
Not recorded yet: the fixtures under tests/fixtures/synthetic/ are the JSON the scripts
are designed to emit, not output recorded from a host.
Install
pip install napalm-windows
How it works
Every getter sends one PowerShell script. The script projects the cmdlet
results onto flat, primitive fields and ends in ConvertTo-Json, so the
Python side parses JSON, never text. All device I/O goes through a single
seam (PsrpTransport.run(script) -> str), which is what the tests replace.
One runspace pool stays open per connection, so a poll pays the WinRM handshake once.
Supported
| Method | Source |
|---|---|
get_facts |
Win32_ComputerSystem, Win32_OperatingSystem, Win32_BIOS, registry (DisplayVersion, UBR) |
get_interfaces |
Get-NetAdapter |
get_interfaces_ip |
Get-NetIPAddress (loopback dropped, IPv6 zone index stripped) |
get_arp_table |
Get-NetNeighbor -AddressFamily IPv4 (broadcast, multicast, unreachable dropped) |
get_route_to |
Get-NetRoute (multicast, broadcast, loopback dropped) |
get_services / manage_service |
Win32_Service, Start-/Stop-/Restart-Service, Set-Service -StartupType |
get_listening_sockets |
Get-NetTCPConnection -State Listen, Get-NetUDPEndpoint, Get-Process, Win32_Service (a shared svchost names no service) |
get_scheduled_jobs |
Get-ScheduledTask + Get-ScheduledTaskInfo, one script; \Microsoft\* is platform, other tasks admin, the root task an application wrote application; time zone mapped to IANA for the common zones |
manage_scheduled_job |
Enable-/Disable-ScheduledTask, Start-ScheduledTask (returns once started; the result shows in the next reading) |
put_scheduled_job / delete_scheduled_job |
Register-ScheduledTask -Xml -Force in the root folder, Unregister-ScheduledTask; an application's tasks only |
get_time_sync / configure_time_sync |
w32time's registry values (group policy first), w32tm /query /status, the registry's TimeZoneInformation; writes NtpServer/Type + w32tm /config /update, Set-TimeZone. See Time sync |
running_kernel carries the full build including the update revision
(10.0.20348.2340): Windows ships fixes as UBR bumps, which is what CVE
matching has to compare against.
Scheduled tasks
An application's own job is the task \<name> in the root folder, never a folder of
its own. Its description is napalm-scheduled-job: <name> <description> and a second
line schedule: <cron expression>, so the reading gives back the cron expression and
the command it was written with; its digest also covers the triggers, so triggers
changed by hand count as a change.
- Command:
cmd.exe /d /s /c "<command>"— one line, as a Windows command line. - Principal:
SYSTEM, or a local user who runs it whether logged on or not without a stored password (S4U). Such a run has no network credentials, and the user needs the "Log on as a batch job" right. - Schedule: a cron expression becomes triggers only where Task Scheduler can
express it exactly — daily, weekly on weekdays, or monthly on days of the month (in
some months); at one or more times, or evenly spaced times as one repetition
(
*/5,*/15 8-17,0 */6), or one repeating trigger per hour (*/7); at most 48 triggers.@rebootis a boot trigger. Refused, naming why: both a day of the month and a weekday (cron's either rule), a weekday together with days or months, and times needing more than 48 triggers. A repetition counts elapsed time, so on the day summer time starts or ends its later runs shift by the hour. - Not read: which software installed a task (Windows does not record it), so a
vendor's updater is
admin; and the days of a monthly trigger, whichGet-ScheduledTaskdoes not expose.
Time sync
napalm-device-types' TimeSyncMixin; both the servers and the zone are written.
- Servers are w32time's
NtpServerin order, without their,0xflags; group policy's values (HKLM\SOFTWARE\Policies\Microsoft\W32Time\Parameters) win over the local ones.Type NoSynchas none. Written as<server>,0x8(client mode) withType NTP— whatw32tm /config /manualpeerlist /syncfromflags:manualwrites — thenw32tm /config /update; a stopped Windows Time service is started first. - Domain members that take their time from the domain hierarchy (
Type NT5DSorAllSync) report the servers configured, and a write is refused: the domain sets their time. So is a write where group policy sets w32time. - Synchronised is the leap indicator of
w32tm /query /status(3= not synchronised); a stopped service is not synchronised.daemonisw32time. - Zone: Windows keeps a Windows zone (
W. Europe Standard Time), which stands for several IANA zones. It is read as the zone CLDR names for it (Europe/Berlin) and written withSet-TimeZonefrom CLDR's mapping (windowsZones.xml, generated intonapalm_windows/_windows_zones.pybytools/windows_zones.py, never fetched at runtime). The IANA name written is kept inHKLM\SOFTWARE\napalm-windows(IanaTimeZone) and read back while the host is still in that Windows zone, soEurope/Viennareads back asEurope/Vienna. A zone with summer time switched off reads asNone; writing the zone switches it back on.
Not yet: packages, Windows Update, health metrics, Hyper-V. See netork#300 for the plan.
Preparing a host
WinRM is on by default on Windows Server; on Windows 10/11 run
Enable-PSRemoting once. Then either
- HTTPS (5986, default) — needs a certificate-backed HTTPS listener, or
- HTTP (5985) — set the device port to 5985. Traffic is still encrypted at message level (NTLM/Kerberos), credentials never travel in the clear.
A local administrator account additionally needs
LocalAccountTokenFilterPolicy = 1 under
HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System; without it
remote UAC strips the admin token. Domain accounts are not affected.
optional_args
| Key | Default | Meaning |
|---|---|---|
port |
5986 |
WinRM port |
winrm_ssl |
port != 5985 |
force HTTPS on or off |
winrm_auth |
negotiate |
pypsrp auth protocol (negotiate, ntlm, kerberos, credssp, basic) |
ssl_verify |
True |
validate the WinRM certificate |
Development
The rules are in STANDARDS.md.
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest --cov
Tests and fixtures
tests/fixtures/synthetic/ holds the JSON the scripts are designed to emit.
To record the real thing from a host:
python tools/harvest.py <host> <user> <label> [--port 5985] [--insecure]
Output lands in tools/harvest-out/ (gitignored); scrub it before copying
anything into tests/.
License
Apache-2.0, see LICENSE.