Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .bundler-audit.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
# bundler-audit waivers. Each entry is a dev/test-only gem that is not
# shipped in the module (the module ships shell and PowerShell facts and a
# Bolt task) and that cannot be upgraded while an upstream pin holds it.
# Revisit each entry when the named pin moves; remove it once the
# resolved version clears the advisory.
ignore:
# minitar 0.12.1: path traversal on Windows with a crafted tarball.
# Held below 1.0 by bolt (~> 0.6), r10k (~> 0.9) and puppet_forge (< 1.0),
# all pulled in by puppet_litmus for acceptance tests. Waived 2026-11-18.
- GHSA-r6vf-943r-2wvw
# mcp 0.25.0: OAuth discovery SSRF. Pulled in by rubocop (mcp ~> 0.6) for
# its optional MCP server, which lint never starts. Waived 2026-11-18.
- GHSA-4m5j-jjfc-97gx
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,34 @@
# Changelog

## [0.3.0] - 2026-11-18

0.2.0 was never tagged or released, and 0.3.0 is the first release that carries it: everything under 0.2.0 below ships in 0.3.0
too.

- **The `patchbot` fact is now schema version 2, on Linux and Windows.** The fact carries `schema_version: 2`. A reader written
for version 1 keeps working: `available`, `security`, `reboot_required` and `last_checked` mean what they always did, and
everything else is additive.
- **Three-state reboot answer.** `reboot_status` is always present and is `required`, `not_required` or `unknown`. `unknown`
means the node cannot tell, and it is never read as "no". `reboot_status_reason` is a fixed code saying why, never raw command
output. `reboot_required` is kept for version 1 readers and is true only when `reboot_status` is `required`.
- **How each platform decides.** apt reads the `/var/run/reboot-required` marker, and reports `unknown` when no marker exists and
nothing installed would ever write one. dnf runs `needs-restarting -r` and reads its exit code; a missing plugin is reported as
`unknown` (`plugin_missing`), not as "no reboot needed". yum uses the standalone `needs-restarting` the same way. Windows runs
four probes (Component Based Servicing, Windows Update, pending file renames, and System Center Configuration Manager when
present); any yes is `required`, and a probe that failed is never read as a no.
- **dnf reports when the update check could not run.** `status` is `ok`, or `check_failed` with a fixed `check_error`
(`metadata_unavailable` or `package_manager_error`), and the counts are then zero instead of looking like a clean node.
- **Package detail.** The fact lists `repos`, `package_count` and `truncated`. `packages[]` is capped by `PCM_PATCH_MAX_PACKAGES`
(default 500); only the list is capped, and `available`, `security` and `package_count` stay exact.
- **`security` is now an exact count of pending updates.** It used to count advisory rows, so a package named in several
advisories was counted several times and `security` could exceed `available`. It now counts each pending update that has a
security advisory once, matched by exact package name, so one package can no longer be flagged by another package's advisory
that merely starts with the same letters.
- The patch task (`tasks/patch.*`) is unchanged in this release.
- `facts.d/patchbot.sh` and `facts.d/patchbot.ps1` are byte-identical copies of the development copy kept in the Puppet Stagehand
Console repository. sha256: `patchbot.sh` `daf7d4fb4ad702f2cbe55cc9d3c8dc58a6cb630dc69403a535389200633431f1`, `patchbot.ps1`
`fd934bbec566b876b93e9adc81c32c556e6e57688b6462ed7da291ecd593f333`.

## [0.2.0] - 2026-09-23

- **Breaking (external fact consumers):** `facts.d/patchbot.sh`'s apt, dnf, and yum
Expand Down
63 changes: 44 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ metadata; same parameters and same JSON output shape either way.
| `console_url` | `Optional[String[1]]` | — | Server-injected; unused by the patch itself (posture reaches the console via the fact, not the task's own output). |
| `ingest_token` | `Optional[String[1]]` | — | Server-injected; unused by the patch itself. |
| `security_only` | `Boolean` | `false` | Apply only security updates when true; otherwise apply all available updates. Ignored when `patch_ids` is set. |
| `patch_ids` | `Optional[Array[String[1]]]` | — | Install only these specific ids, as reported in the fact's `patches[]` array (KB numbers on Windows, package names on Linux). Takes priority over `security_only`. |
| `patch_ids` | `Optional[Array[String[1]]]` | — | Install only these specific ids, as reported in the fact (KB numbers from `missing[].kbs` on Windows, package names from `packages[].name` on Linux). Takes priority over `security_only`. |
| `reboot` | `Boolean` | `false` | Reboot the node afterward if a reboot is required. |

On Linux, `patch_ids` requires `jq` on the target (only when actually used —
Expand All @@ -64,40 +64,65 @@ every other path stays dependency-light). On Windows, no extra dependency:

## The `patchbot` fact schema

This module publishes **schema version 2** of the `patchbot` fact: the same keys, and the same reboot rule, as the fact the
console's own `stagehand` module ships. The full contract (every key and every reboot reason code) is kept with the Puppet Stagehand Console's own documentation, which
this repository does not link to. A fact without `schema_version` is version 1.

A Linux fact (dnf):

```json
{
"patchbot": {
"available": 4,
"schema_version": 2,
"status": "ok",
"available": 3,
"security": 1,
"reboot_required": false,
"last_checked": "2026-08-18T14:03:00Z",
"patches": [
{ "id": "KB5031354", "severity": "high", "security": true },
{ "id": "openssl", "severity": "high", "security": true },
{ "id": "some-lib.x86_64", "severity": "unknown", "security": false }
]
"reboot_status": "not_required",
"reboot_status_reason": "needs_restarting",
"last_checked": "2026-11-17T14:03:00Z",
"manager": "dnf",
"repos": ["appstream", "baseos"],
"packages": [
{ "name": "openssl", "arch": "x86_64", "current": "1:3.2.2-2.el9", "available": "1:3.2.2-6.el9_5", "repo": "rhel-9-appstream", "security": true }
],
"package_count": 3,
"truncated": false
}
}
```

| Field | Type | Meaning |
|---|---|---|
| `available` | integer | Count of packages/updates with an available update. |
| `security` | integer | Subset of `available` that are security updates. |
| `reboot_required` | boolean | Whether a pending reboot has been flagged (`/var/run/reboot-required` or `needs-restarting -r` on Linux; the WUA `SystemInfo.RebootRequired` property on Windows). |
| `schema_version` | integer | Always `2`. |
| `available` | integer | Count of packages/updates with an available update. Exact even when the list is capped. |
| `security` | integer | How many pending updates have a security advisory. An update is counted once even when several advisories or builds name it, and it is matched by exact package name, so `security` is never more than `available`. |
| `reboot_status` | enum | `required`, `not_required` or `unknown`. `unknown` means this node cannot tell (the tool that reports it is missing or failed, or no supported package manager is present). It is never reported as `not_required`. |
| `reboot_status_reason` | string | A fixed code saying why (for example `marker_present`, `needs_restarting`, `plugin_missing`, `no_package_manager`; `pending_reboot_probe`, `probes_clear`, `probes_failed` on Windows). Never raw command output. |
| `reboot_required` | boolean | Kept for readers of version 1: true only when `reboot_status` is `required`. |
| `last_checked` | string | ISO 8601 UTC timestamp of the last time this fact ran. |
| `patches[].id` | string | The identifier this entry round-trips into the task's `patch_ids` parameter. KB number (`KB5031354`) on Windows; bare package name (or `name.arch` on RHEL-family) on Linux. |
| `patches[].severity` | enum | `low` \| `medium` \| `high` \| `unknown` — the same severity scale `compliance.v1` uses. On Windows this is MSRC's rating (Critical/Important collapse to `high`, Moderate → `medium`, Low → `low`). On Linux it's an approximation: `high` if the package manager's security channel flags the update, `unknown` otherwise — Linux package managers don't expose per-package severity as cleanly as WUA does. |
| `patches[].security` | boolean | Whether this update is classified as a security update. |
| `manager` | string | `apt`, `dnf`, `yum` or `wua`; empty on a Linux node with no supported package manager. |
| `repos` | array | Linux: the configured suites or repository ids. |
| `packages[]` | array | Linux: `name`, `arch`, `current` (installed version), `available`, `repo`, `security`. Capped (see below). |
| `package_count`, `truncated` | integer, boolean | The full count, and whether the list above was cut at the cap. |
| `status`, `check_error` | string | dnf only: `ok`, or `check_failed` with a fixed `check_error` (`metadata_unavailable`, `package_manager_error`) when the update check could not run. |
| `os_build`, `installed_kbs`, `missing[]`, `source`, `wsus_server`, `cve_ids_populated`, `scan_error` | various | Windows: the build, the installed KBs, the missing updates (`kbs`, `title`, `severity`, `cve_ids`, `reboot`), and where the scan looked. |
| `cache_age_seconds`, `cache_stale` | integer, boolean | Windows: always `0` and `false` here, because this module's Windows fact scans live and has no cache. |

The package list is capped (`PCM_PATCH_MAX_PACKAGES`, default 500) because the fact is stored in PuppetDB and re-sent every agent
run. Only the detail list is capped; the counts stay exact and `truncated` says so.

**Deliberately no `title` field** — the fact is stored in PuppetDB and
re-sent every agent run, and `patches[]` can run to dozens of entries on a
stale node. The console resolves human-readable display text from `id`
itself rather than paying that cost in every fact upload.
The `patches[]` array of version 1 is no longer emitted. The console still falls back to it for a node that has not yet received
this module's new facts.

Structured JSON output requires Facter 4, which ships with Puppet 8 —
Structured JSON output requires Facter 4, which ships with Puppet 8 --
OpenVox, Puppet Core, and PE all qualify.

## Tests

The fact is tested together with its development copy in the Puppet Stagehand Console repository. This repository's CI runs the
task tests, rspec-puppet and Pester.

## Files

- `manifests/init.pp` — the `patchbot` class (Linux refresh timer only; the
Expand Down
5 changes: 2 additions & 3 deletions REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

### Tasks

* [`patch`](#patch): Apply available OS updates (all, security-only, or a specific set of patch_ids) on a node, optionally reboot when required, then refresh the
* [`patch`](#patch): Apply available OS updates (all, security-only, or a specific set of patch_ids) on a node, optionally reboot when required, then refresh the

## Classes

Expand Down Expand Up @@ -38,7 +38,7 @@ refresh, and facts.d/patchbot.ps1 queries WUA live on every fact run.

#### Examples

#####
#####

```puppet
include patchbot
Expand Down Expand Up @@ -107,4 +107,3 @@ Install only these specific patch/package ids, as reported in the patchbot fact'
Data type: `Boolean`

Reboot the node afterward if a reboot is required.

Loading
Loading