banshee/windows-collection/windows/winrm/updates

Updates of a Windows, by WinRM

Returns the updates waiting to be installed on a Windows, the critical ones among them, whether an installed update asks for a restart, and how old the last successful search for updates is. Four watches are proposed, each one set on the probe.

Versions

Windows Server 2012 and later, Windows 8 and later: Windows PowerShell 3.0, which the collector needs, ships with each of them; the WinRM service runs by default on every Windows Server from 2012 on, and winrm quickconfig starts it on a desktop Windows. Generic: no folder of version. That every release answers alike is assumed, not yet checked on a real Windows.

How it works

The collector runs one PowerShell script, by WinRM, that reads the Windows Update agent, through its COM objects Microsoft.Update.Session, Microsoft.Update.SystemInfo and Microsoft.Update.AutoUpdate:

$ErrorActionPreference = 'Stop'; $searcher = (New-Object -ComObject Microsoft.Update.Session).CreateUpdateSearcher(); $searcher.Online = $false; $updates = @($searcher.Search('IsInstalled=0 and IsHidden=0').Updates); ConvertTo-Json -Compress -InputObject @{pending = $updates.Count; critical = @($updates | Where-Object MsrcSeverity -eq 'Critical').Count; reboot = (New-Object -ComObject Microsoft.Update.SystemInfo).RebootRequired; hours = [long]((Get-Date).ToUniversalTime() - (New-Object -ComObject Microsoft.Update.AutoUpdate).Results.LastSearchSuccessDate).TotalHours}

WinRM hands the script to PowerShell itself: no shell stands in between, and the script is the one of windows/ssh/updates, without the powershell -Command "…" that cmd.exe needs there. The default shell of an OpenSSH server, which would read the $ of this script too early, does not matter here.
The search is made offline: Windows answers from the result of its own last search, without asking Windows Update or the WSUS server. Nothing is downloaded and nothing is installed; the run stays short.
That result may be old: the age of the last successful search, in days, says how much the count is worth, and has its own watch.
The updates waiting are those not installed and not hidden; the critical ones are those Microsoft rates Critical (MsrcSeverity), a rating that is the same whatever the language of Windows.
The restart is yes when an installed update waits for it, no otherwise.
A failed search stops the script with no answer, and the collector as misconfigured, rather than return zero updates.
Nothing is skipped at the first run.

Nothing is written to the Windows: the script only reads.

Prerequisites

The WinRM service of Windows listening in HTTPS. The service runs by default on every Windows Server from 2012 on (on a desktop Windows, winrm quickconfig starts it), with an HTTP listener only; the HTTPS listener needs a certificate: - a certificate for server authentication in the store of the computer (Cert:\LocalMachine\My), bearing the name the poller connects to: issued by the authority of the company, or made on the server by New-SelfSignedCertificate -DnsName <name> -CertStoreLocation Cert:\LocalMachine\My from Windows Server 2012 R2 on (Windows Server 2012 does not have this command); - then the listener: winrm quickconfig -transport:https finds a certificate of an authority by itself, but refuses a self-signed one; the command that takes either, on every Windows from Server 2012 on, is winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="<name>";CertificateThumbprint="<thumbprint>"} in cmd.exe, the thumbprint being the one Windows shows for the certificate.
The Windows firewall open to the poller on TCP 5986, which creating the listener does not do: New-NetFirewallRule -DisplayName "WinRM HTTPS" -Direction Inbound -Protocol TCP -LocalPort 5986 -Action Allow in PowerShell. A listener on another port is set in protocol:winrm:port.
The certificate judged by the poller before the account is sent, by the TLS profile of the probe: issued by an authority the system of the poller knows, by an authority added in protocol:tls:authorities, or pinned in protocol:winrm:fingerprint, the way for a self-signed certificate; the pin is not needed when the Security settings trust the first WinRM fingerprint presented. The fingerprint is sha256: followed by the SHA-256 of the certificate in 64 lower-case hexadecimal characters; from a machine that reaches the port, openssl s_client -connect <name>:5986 </dev/null | openssl x509 -noout -fingerprint -sha256 prints it, in capitals, with colons to take off. A certificate whose name is not the address of the host is judged on the name set in protocol:tls:server-name.
NTLM authentication, which the WinRM service accepts as installed (Negotiate = true in winrm get winrm/config/service/auth): the password never travels, only an answer computed with it. A domain that refuses NTLM is not served.
Windows PowerShell 3.0 or later, as shipped with every Windows from Server 2012 and Windows 8 on (3.0 on Server 2012, 4.0 on 2012 R2, 5.1 from 2016 on).
An account for monitoring, without administrator rights, local or of the domain, set in protocol:winrm:user (account, DOMAIN\account or account@domain) with its password in protocol:winrm:password, member of the local group "Remote Management Users", which opens WinRM to an account that is not an administrator. No other group is asked for: the offline search reads what Windows found by itself, which is not yet checked for such an account (Limits).
Windows searching for updates by itself, from Windows Update or a WSUS server: the collector only reads the result.

Outputs

Name	Label	Unit	Per instance
`pending`	Updates waiting	—	no
`critical`	Critical updates waiting	—	no
`reboot`	Restart required	—	no
`search-age`	Last successful search	d	no

Watches

Name	Title	Kind	Defaults	Checked by default
`critical-pending`	Critical updates waiting	above a threshold, on `critical`	warning above 0; no critical	yes
`pending`	Updates waiting	above a threshold, on `pending`	no threshold: to set on the probe	no
`reboot-required`	Restart required	state to avoid, on `reboot`	warning on `yes`; no critical	yes
`search-old`	No search for updates	above a threshold, on `search-age`	warning above 7 days, critical above 30 days	yes

Limits

A certificate of the listener that expires, or a pinned one that is renewed, stops every WinRM collector of the host: the network/tls/certificate collector of banshee/web-collection, deployed on port 5986, watches it.
The count is that of the last search Windows made: an update published since is not counted until Windows searches again.
A Windows that never searched, or whose updates are managed by another tool than the Windows Update agent, has no result to read: the collector stops as misconfigured, or "No search for updates" raises.
Not yet checked on a real Windows: the offline search and the reading of LastSearchSuccessDate by an account without administrator rights, from a WinRM session, where Windows Update is known to refuse some of its objects; and that LastSearchSuccessDate is given in UTC.