driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 57s
driver / test (3.12) (pull_request) Successful in 58s
driver / test (3.13) (pull_request) Successful in 51s
driver / lowest (pull_request) Successful in 26s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 57s
CI / driver (pull_request) Successful in 2m23s
driver / publish (pull_request) Skipped
netOrk keeps one list of NTP servers and a time zone per site and aligns a device that differs (NetOrk/netork#2360). A Windows host takes part through w32time and its time zone, in one PowerShell script per read. The servers and the mode are read from w32time's registry values, group policy's first, not from w32tm /query /configuration, whose text is in the host's language; synchronised is the leap indicator on the first line of w32tm /query /status, which reads the same in any language. The servers are written the way w32tm /config /manualpeerlist /syncfromflags:manual writes them (NtpServer with 0x8, Type NTP), followed by w32tm /config /update: no value passes a native command line, whose quoting Windows PowerShell 5.1 mangles. A domain member that takes its time from the domain hierarchy (NT5DS, AllSync) and a host whose w32time comes from group policy refuse the write: their time is set elsewhere, and a local write would be overridden or break the domain's time. Windows keeps a Windows zone, which stands for several IANA zones, so Europe/Vienna written would read back as Europe/Berlin and the poll would align the host forever. The IANA name written is kept beside it in HKLM\SOFTWARE\napalm-windows and read back while the host is still in that Windows zone. The zone is read from the registry, which [TimeZoneInfo]::Local caches for the life of the remote session. The zone table is now CLDR's windowsZones.xml (release 49) both ways, generated by tools/windows_zones.py with tzdata's links and committed with its source and checksum; nothing is fetched at runtime. CLDR's old names (Asia/Calcutta) read as their current ones (Asia/Kolkata). Writes the host already has are skipped. Needs napalm-device-types 4.35.0. Refs NetOrk/netork#2367
149 lines
7.3 KiB
Markdown
149 lines
7.3 KiB
Markdown
# napalm-windows
|
|
|
|
NAPALM driver for Windows Server 2016+ and Windows 10/11, part of the netOrk
|
|
driver family built on [`napalm-device-types`](https://git.netork.io/NAPALM/napalm-device-types).
|
|
|
|
Driver name: `windows` · Role: `OSDriver` · Transport: PowerShell Remoting
|
|
(PSRP) over WinRM via [`pypsrp`](https://pypi.org/project/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
|
|
|
|
```bash
|
|
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. `@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.
|
|
|
|
### Time sync
|
|
|
|
napalm-device-types' `TimeSyncMixin`; both the servers and the zone are written.
|
|
|
|
* **Servers** are w32time's `NtpServer` in order, without their `,0x` flags; group
|
|
policy's values (`HKLM\SOFTWARE\Policies\Microsoft\W32Time\Parameters`) win over
|
|
the local ones. `Type NoSync` has none. Written as `<server>,0x8` (client mode) with
|
|
`Type NTP` — what `w32tm /config /manualpeerlist /syncfromflags:manual` writes —
|
|
then `w32tm /config /update`; a stopped Windows Time service is started first.
|
|
* **Domain members** that take their time from the domain hierarchy (`Type NT5DS` or
|
|
`AllSync`) 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. `daemon` is `w32time`.
|
|
* **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 with `Set-TimeZone` from CLDR's mapping
|
|
([`windowsZones.xml`](https://github.com/unicode-org/cldr/blob/release-49/common/supplemental/windowsZones.xml),
|
|
generated into `napalm_windows/_windows_zones.py` by `tools/windows_zones.py`,
|
|
never fetched at runtime). The IANA name written is kept in
|
|
`HKLM\SOFTWARE\napalm-windows` (`IanaTimeZone`) and read back while the host is
|
|
still in that Windows zone, so `Europe/Vienna` reads back as `Europe/Vienna`. A
|
|
zone with summer time switched off reads as `None`; 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](https://git.netork.io/NAPALM/driver-standard/src/branch/main/STANDARDS.md).
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](LICENSE).
|