christianmanivong 37708009a0
driver / standard (push) Successful in 19s
driver / lint (push) Successful in 18s
driver / types (push) Successful in 1m7s
driver / test (3.12) (push) Successful in 1m2s
driver / test (3.13) (push) Successful in 58s
driver / lowest (push) Successful in 29s
driver / build (push) Successful in 27s
driver / security (push) Successful in 1m1s
CI / driver (push) Successful in 2m40s
driver / publish (push) Skipped
Merge pull request 'feat(scheduled-jobs): the Task Scheduler as scheduled jobs (#8)' (#9) from feature/scheduled-jobs into main
2026-11-03 08:20:27 +00:00

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

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. @reboot is 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, which Get-ScheduledTask does not expose.

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.

S
Description
NAPALM driver for Windows hosts via PowerShell Remoting (WinRM)
Readme
185 KiB
0 Stars 1 Watchers 0 Forks
2026-10-25 18:03:18 +00:00
Languages
Python 100%