Metadata-Version: 2.4
Name: napalm-windows
Version: 0.2.0
Summary: NAPALM driver for Windows hosts via PowerShell Remoting (WinRM)
Author-email: Christian Manivong <christian@manivong.de>
License-Expression: Apache-2.0
Project-URL: Repository, https://git.netork.io/NAPALM/napalm-windows
Project-URL: Issues, https://git.netork.io/NAPALM/napalm-windows/issues
Project-URL: Changelog, https://git.netork.io/NAPALM/napalm-windows/src/branch/main/CHANGELOG.md
Keywords: napalm,network,automation,windows,winrm,powershell,psrp,driver
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: napalm>=4.0
Requires-Dist: napalm-device-types>=4.21.1
Requires-Dist: pypsrp>=0.8
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# 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) |

`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.

Not yet: packages, Windows Update, scheduled tasks, 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).
