driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 15s
driver / test (3.12) (pull_request) Failing after 14s
driver / types (pull_request) Failing after 23s
driver / test (3.13) (pull_request) Failing after 13s
driver / lowest (pull_request) Failing after 14s
driver / security (pull_request) Failing after 32s
driver / build (pull_request) Successful in 25s
CI / driver (pull_request) Failing after 1m21s
driver / publish (pull_request) Skipped
netOrk shows and controls every scheduled job of a host; on Windows that is the Task Scheduler. The driver now implements napalm-device-types' ScheduledJobsMixin over PowerShell Remoting, one script per call as every getter does. get_scheduled_jobs reads every task with its run info in one script (Get-ScheduledTask, Get-ScheduledTaskInfo) as task:<path><name>, its triggers summarised. Tasks under \Microsoft\ are the platform's, others the admin's: Windows does not record which software installed a task. The time zone is mapped to IANA for the common Windows zones, else None. A reading cut short, or holding fewer tasks than it counted, raises. manage_scheduled_job switches the task's own flag or starts it; Start-ScheduledTask returns once the task has started, so the result says that and no more. A disabled task, or one that refuses a start on demand, is not offered run. put_scheduled_job registers an application's task \<name> in the root folder from XML, so a create and a change write the whole definition the same way: the command runs in cmd.exe /d /s /c, the principal is SYSTEM or a local user without a stored password (S4U), and the cron expression becomes triggers only where Task Scheduler can say it exactly; any other shape is refused, naming why. The description keeps the job's name and cron expression, so the reading gives back what was written, and the digest also covers the triggers, so a change by hand is seen. delete_scheduled_job unregisters such a task and no other. Every write reads the task again first, and every value goes into PowerShell single-quoted with its quotes doubled. Requires napalm-device-types 4.26.0. Closes #8
123 lines
5.4 KiB
Markdown
123 lines
5.4 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 |
|
|
|
|
`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](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).
|