Patch Check Reference

Cross-platform patch check (Windows, Linux, macOS). Configuration fields, MSRC severities, output schema, and per-platform detection details.

Written By Erdinc Akay

Last updated About 1 month ago

Patch Check Reference

In the check catalog this check appears as System Updates (DE: Systemupdates).

Cross-platform: The patch check runs on Windows, Linux, and macOS (x64 and ARM64 on each). On Windows it uses the Windows Update API; on Linux it queries the native package manager (apt, dnf, yum, zypper, or pacman); on macOS it uses softwareupdate. The agent detects the operating system automatically.

Configuration Fields

Field	Type	Required	Default	Description
Warning threshold	integer	No	1	Number of pending updates before a warning is raised
Critical threshold	integer	No	10	Number of pending updates before a critical alert is raised
Count security updates only (Linux/macOS)	boolean	No	false	On Linux/macOS, count only security-relevant updates (the security repository on Linux, recommended updates on macOS). No effect on Windows, which uses the Severity filter instead.
Severity filter (Windows)	array (multi-select: Critical, Important, Moderate, Low)	No	["Critical", "Important"]	Windows only: MSRC severities to include when counting pending updates. Updates whose severity is not in this list are ignored. Leave empty to count all. Ignored on Linux/macOS. Gated behind Show advanced options.
Minimum update age (days, Windows)	integer	No	3	Windows only: updates younger than this many days are ignored, letting newly released patches bake before they count toward the thresholds. Linux/macOS updates carry no reliable per-update release date, so this has no effect there. Gated behind Show advanced options.

MSRC severities (Windows)

On Windows, pending updates are classified by their Microsoft Security Response Center (MSRC) severity, and the Severity filter field controls which severities are counted toward the thresholds. Linux and macOS do not expose MSRC severities — there the Count security updates only option governs which updates count instead.

Severity	Meaning
Critical	Exploitation could allow code execution without user interaction
Important	Exploitation could compromise data confidentiality, integrity, or availability
Moderate	Impact mitigated by default configuration, auditing, or difficulty of exploitation
Low	Impact is comprehensively mitigated by characteristics of the affected component

Output

Each run produces:

Field	Description
`platform`	Detected agent platform: `windows`, `linux`, or `macos`
`pendingCount`	Total number of pending updates reported by the platform's update source (before severity and age filtering)
`criticalUpdateCount`	Windows: number of pending updates with MSRC severity `Critical` after the minimum-age filter
`importantUpdateCount`	Windows: number of pending updates with MSRC severity `Important` after the minimum-age filter
`securityUpdateCount`	Linux/macOS: number of security-relevant pending updates. On Windows this equals Critical + Important
`updates[]`	Per-update detail. On Windows the list contains only the updates that pass the severity and minimum-age filters, truncated to the top 20. Each entry carries `title`, `severity`, and `kbId` (Windows only — Linux and macOS entries carry no KB number).

How updates are detected

Platform	Tool used	What is checked
Windows	PowerShell script (`powershell.exe`) that instantiates the Windows Update COM API via `New-Object -ComObject Microsoft.Update.Session`	Queries the Windows Update agent. Respects WSUS machine policy — if the device reports to a WSUS server, only WSUS-approved updates are shown
Linux	The first available native package manager: `apt`, `dnf`, `yum`, `zypper`, or `pacman`	Lists upgradable packages from the configured repositories. With Count security updates only enabled, only security-relevant updates are counted (security repository on apt, security advisories on dnf/yum, security patches on zypper). pacman (Arch) has no security classification, so this option counts zero updates there
macOS	`softwareupdate -l`	Lists available macOS software updates. With Count security updates only enabled, only recommended updates are counted

The octoja agent detects the operating system automatically. No manual configuration is needed.

Update management

Independently of the per-device patch check, octoja surfaces a fleet-wide view of every update in the Update Catalog. Opening an update shows its advisories, its block status, and whether the vendor has withdrawn it.

Blocking an update

From an update's detail page you can Block update with an optional reason. A block is tenant-global: it applies everywhere in the environment, not per patch policy. A blocked update is withheld from every device until it is unblocked.

Field	Description
Block update / Unblock update	Adds or removes a tenant-global block, keyed by the update's KB number
Reason (optional)	Free-text note recorded with the block
Blocked badge	Shown in the catalog and on the detail page while the update is blocked; the update is withheld from every device until unblocked

Advisories

octoja merges advisory intelligence for each update so a problematic patch can be spotted before deployment.

Advisory	Source
Known issues	Issues Microsoft has published for the update, each with a status such as Confirmed, Mitigated, Investigating, Workaround available, or Resolved
Community reports	Problem reports gathered from the wider community
Reported by other octoja users	A cross-tenant signal showing how many other octoja users have flagged or already blocked the update

Withdrawn updates

When the vendor retracts an update, octoja marks it with a Withdrawn status so it is not offered for installation.

Notes

The check uses the same update mechanism as the Windows Update settings panel.
If your organisation manages updates through WSUS (Windows Server Update Services), the check only reports updates approved by your WSUS administrator.
Auto-patching can be configured separately on the device Updates tab.
If the warning threshold is configured higher than the critical threshold, the check swaps the two values at runtime so the critical threshold remains the upper bound.
By default the check runs every 6 hours.
If the check cannot run at all — no supported package manager on Linux, softwareupdate unavailable on macOS, an unsupported platform, or unparseable tool output — it reports an Error result with a matching message instead of an update count.

See also: Configure a Patch Check