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
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,29 @@
# Changelog

## [0.2.0] - 2026-09-23

- **Breaking (external fact consumers):** `facts.d/patchbot.sh`'s apt, dnf, and yum
branches no longer emit the `patches[]` array (`{"id","severity","security"}`).
All three now emit `packages[]` (`{"name","arch","current","available","repo",
"security"}`), carrying real installed/available version and repo/suite data
instead of a bare identifier + approximated severity. Any external consumer of
the retired `patches[]` shape (PuppetDB queries, third-party reporting) must
move to `packages[]`. Puppet Stagehand Console's own read side
(`patchFactPackages`) already accepts both shapes, preferring `packages[]` and
falling back to `patches[]` for nodes still running a pre-0.2.0 module — see
puppet-console phase 999.47 (`packages-tab-version-and-installation-source`).
- dnf/yum's installed (`current`) version now comes from one batched `rpm -q`
lookup per fact run (`rpm_installed_versions`/`rpm_installed_version_for`),
not `check-update`'s candidate-version column, and not one `rpm -q` per
pending package.
- Package names are validated (`pkgname_is_safe`) against the same
`[A-Za-z0-9][A-Za-z0-9._:+-]*` token shape `tasks/patch.sh`'s `patch_ids`
validation already enforces, before reaching `rpm`'s argv.
- Severity is no longer tracked as a separate field; only the `security`
boolean survives.
- The Windows fact (`facts.d/patchbot.ps1`) is unaffected — it keeps its own
legacy `patches[]`-shaped KB-entry array.

## [0.1.0] - 2026-08-20

- refactor: rename pcm module to stagehand (puppetlabs-stagehand) (2a33ade)
Expand Down
284 changes: 238 additions & 46 deletions facts.d/patchbot.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,40 @@
# Patch posture the console reads (Patching page + Action Center):
# {"patchbot": {"available": N, "security": N, "reboot_required": bool,
# "last_checked": "<ISO8601 UTC>",
# "patches": [{"id","severity","security"}, ...]}}
# "packages": [{"name","arch","current","available","repo","security"}, ...]}}
# (apt, dnf and yum all emit this shape as of 999.47-03. See 999.47-01 for
# apt, 999.47-03 for dnf/yum -- the three branches converged onto one
# shape via shared add_package/json_escape/rpm_installed_versions helpers
# rather than each formatting its own JSON.)
# Structured JSON output requires Facter 4 (ships with Puppet 8 — OpenVox,
# Puppet Core, and PE all qualify).
#
# `patches[]` backs the console's per-patch picker (Windows Update screen
# today; nothing here is Windows-specific). Deliberately id+severity+security
# only — no title — to keep the fact small; PuppetDB stores this and it's
# re-sent every agent run. The console resolves human-readable titles itself.
# See docs/design/patchbot-fact-schema-spec.md (filed in the project's AI
# vault, not this repo) for the full rationale.
# `packages[]` backs the console's per-patch picker (Windows Update screen
# today; nothing here is Windows-specific) and the Patching > Packages tab's
# version/source columns. Entries carry name, arch, current (installed)
# version, available version, repo/suite and a security boolean -- adopted
# from adapters/stagehand/facts.d/patchbot.sh's already-documented shape
# (D-02, 2026-09-23 design: docs/superpowers/specs/2026-09-23-patching-package-version-source-design.md)
# rather than inventing a third shape on top of the legacy "deliberately
# id+severity+security only" `patches[]` array. dnf/yum's `current` (the
# installed version) comes from a second, batched `rpm -q` lookup
# (rpm_installed_versions) since `check-update` only reports the candidate
# version -- one process invocation per fact run, not one per pending
# package (T-999.47-11).
#
# Severity here is an approximation, not a per-CVE rating: Linux package
# managers don't cleanly expose per-package severity the way Windows' WUA
# does (see facts.d/patchbot.ps1) without heavier tooling (debsecan, dnf5's
# richer API) this module deliberately doesn't pull in. A package is
# `security: true, severity: "high"` if the package manager's own
# security-update channel flags it; everything else is
# `security: false, severity: "unknown"`.
# `patches[]` is no longer emitted by any branch of this script. The
# console's read side (patchFactPackages, backend/internal/httpapi/patching.go)
# still tries "packages" first and falls back to "patches" -- that fallback
# is the degradation path for any node still running a pre-999.47 copy of
# this module during rollout (spec section 7), not dead code to delete.
#
# Severity is no longer tracked as a separate field for the packages[] shape
# -- only the "security" boolean survives (D-02). Linux package managers
# don't cleanly expose per-package severity the way Windows' WUA does (see
# facts.d/patchbot.ps1) without heavier tooling (debsecan, dnf5's richer
# API) this module deliberately doesn't pull in. A package is
# `security: true` if the package manager's own security-update channel (or
# advisory list) flags it; everything else is `security: false`.
#
# Split out of the stagehand module into its own patchbot module (2026-08-18);
# originally renamed from the legacy `patches` fact at the pcm/stagehand cutover
Expand All @@ -32,48 +48,166 @@ set -u
AVAILABLE=0
SECURITY=0
REBOOT=false
PATCHES=""

# Appends one {"id":...,"severity":...,"security":...} object to $PATCHES.
# Package/KB identifiers are controlled strings from the package manager
# itself (never free-form user text), so no JSON-string escaping is needed.
add_patch() {
_id="$1" _sev="$2" _sec="$3"
_entry="{\"id\": \"${_id}\", \"severity\": \"${_sev}\", \"security\": ${_sec}}"
if [ -z "$PATCHES" ]; then
PATCHES="$_entry"
PACKAGES=""

# json_escape backslash-and-quote-escapes a value before it is interpolated
# into emitted JSON (T-999.47-01: suite/version/arch strings, unlike the bare
# package names the legacy add_patch call trusted, are less tightly
# controlled). Mirrors adapters/stagehand/facts.d/patchbot.sh's esc()
# (backslash substitution before quote substitution, same order).
json_escape() {
printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
}

# Appends one {"name","arch","current","available","repo","security"} object
# to $PACKAGES. Used by all three branches (apt: 999.47-01; dnf/yum:
# 999.47-03). Every string field is routed through json_escape first.
add_package() {
_name=$(json_escape "$1")
_arch=$(json_escape "$2")
_cur=$(json_escape "$3")
_avail=$(json_escape "$4")
_repo=$(json_escape "$5")
_sec="$6"
_entry="{\"name\": \"${_name}\", \"arch\": \"${_arch}\", \"current\": \"${_cur}\", \"available\": \"${_avail}\", \"repo\": \"${_repo}\", \"security\": ${_sec}}"
if [ -z "$PACKAGES" ]; then
PACKAGES="$_entry"
else
PATCHES="${PATCHES}, ${_entry}"
PACKAGES="${PACKAGES}, ${_entry}"
fi
}

# pkgname_is_safe validates that NAME is a plain package-name token before it
# reaches rpm's argv (T-999.47-09, same argument-injection class the
# patchbot patch task's own patch_ids validation already fixed --
# tasks/patch.sh's `[A-Za-z0-9][A-Za-z0-9._:+-]*` shape). A name containing
# whitespace or a leading dash would otherwise split into extra argv entries
# or be read as an rpm flag. A name that fails this check is simply skipped
# -- it never reaches rpm_installed_versions, so it contributes no "current"
# value, which the collapse rule already treats as an empty-tuple
# contributor rather than a fatal error.
pkgname_is_safe() {
case "$1" in
'') return 1 ;;
[A-Za-z0-9]*) ;;
*) return 1 ;;
esac
case "$1" in
*[!A-Za-z0-9._:+-]*) return 1 ;;
esac
return 0
}

# rpm_installed_versions NAMES...
#
# Runs exactly ONE `rpm -q` invocation across every pending package name,
# emitting one "name version" line per name rpm recognizes on stdout. This
# is the mitigation for the open risk spec section 9 records (T-999.47-11):
# the naive shape is one `rpm -q` per pending package, which on a node with
# hundreds of pending updates is the place fact-collection time noticeably
# grows -- batching it into one invocation makes the cost constant instead
# of linear in the number of pending packages. Names are passed after `--`
# (T-999.47-09) and stderr is discarded so an unrecognized name does not
# abort the run.
rpm_installed_versions() {
[ "$#" -gt 0 ] || return 0
rpm -q --queryformat '%{NAME} %|EPOCH?{%{EPOCH}:}:{}|%{VERSION}-%{RELEASE}\n' -- "$@" 2>/dev/null
return 0
}

# rpm_installed_version_for NAME TABLE
#
# Resolves NAME against the "name version" TABLE rpm_installed_versions
# produced, returning the first match on stdout. A multilib pair (i686 and
# x86_64 reported as two lines for the same name) would otherwise double the
# emitted entry count -- taking the first keeps exactly one entry per
# check-update line. Prints nothing (empty "current") when NAME is absent
# from TABLE.
rpm_installed_version_for() {
printf '%s\n' "$2" | awk -v name="$1" '$1 == name { print $2; exit }'
}

if command -v apt-get >/dev/null 2>&1; then
# Simulated dist-upgrade: count Inst lines; security = those from a
# -security suite. Uses the package cache only (no network) — the patchbot
# patch task and unattended-upgrades keep the cache fresh.
#
# Inst openssl [3.0.2-0ubuntu1.15] (3.0.2-0ubuntu1.18 Ubuntu:24.04/noble-security [amd64])
#
# A package pulled in fresh as a dependency has no [current] bracket, so
# the third field is parsed defensively rather than positionally (ported
# from adapters/stagehand/facts.d/patchbot.sh's apt awk block, the proven
# reference implementation of this exact parse).
UPGR=$(apt-get -s dist-upgrade 2>/dev/null | grep '^Inst ' || true)
if [ -n "$UPGR" ]; then
AVAILABLE=$(printf '%s\n' "$UPGR" | wc -l | tr -d ' ')
SECURITY=$(printf '%s\n' "$UPGR" | grep -ci 'security' || true)
OLDIFS=$IFS
IFS='
'
# Field separator between the five extracted values below: the ASCII
# Unit Separator (0x1F), not a tab -- POSIX `read` treats IFS tab as
# whitespace and collapses adjacent delimiters (silently dropping an
# empty "current" field, e.g. a freshly-pulled dependency with no
# [current] bracket), which a non-whitespace IFS character does not.
USEP=$(printf '\037')
for LINE in $UPGR; do
PKG=$(printf '%s\n' "$LINE" | awk '{print $2}')
[ -n "$PKG" ] || continue
FIELDS=$(printf '%s\n' "$LINE" | awk -v usep="$USEP" '
{
name = $2
cur = ""
if ($3 ~ /^\[/) { cur = $3; gsub(/[][]/, "", cur) }

p = index($0, "(")
rest = (p ? substr($0, p + 1) : "")
split(rest, r, " ")
avail = r[1]

# Origins look like "Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security".
# Take the suite of the first one as the repo.
repo = ""
if (match(rest, /\/[A-Za-z0-9._-]+/)) {
repo = substr(rest, RSTART + 1, RLENGTH - 1)
}

arch = ""
if (match(rest, /\[[A-Za-z0-9_-]+\][)]?[ ]*$/)) {
arch = substr(rest, RSTART + 1, RLENGTH - 1)
gsub(/[])] */, "", arch)
}

printf "%s%s%s%s%s%s%s%s%s", name, usep, cur, usep, avail, usep, repo, usep, arch
}')
[ -n "$FIELDS" ] || continue
IFS="$USEP" read -r PKG_NAME PKG_CUR PKG_AVAIL PKG_REPO PKG_ARCH <<PKGFIELDS
$FIELDS
PKGFIELDS
[ -n "$PKG_NAME" ] || continue
# Security determination stays byte-for-byte the legacy behavior: a
# case-insensitive "security" match against the WHOLE Inst line, not
# adapters/stagehand's stricter "-security"-suite-only match (that is a
# different fleet-wide security count and out of scope here).
if printf '%s\n' "$LINE" | grep -qi 'security'; then
add_patch "$PKG" "high" "true"
add_package "$PKG_NAME" "$PKG_ARCH" "$PKG_CUR" "$PKG_AVAIL" "$PKG_REPO" "true"
else
add_patch "$PKG" "unknown" "false"
add_package "$PKG_NAME" "$PKG_ARCH" "$PKG_CUR" "$PKG_AVAIL" "$PKG_REPO" "false"
fi
done
IFS=$OLDIFS
fi
[ -f /var/run/reboot-required ] && REBOOT=true

elif command -v dnf >/dev/null 2>&1; then
# `check-update -q` exits 100 with a package list when updates exist.
LIST=$(dnf -q check-update 2>/dev/null | awk 'NF>=3 && $1 !~ /^Obsoleting/ {print $1}' || true)
# `check-update -q` exits 100 with a package list when updates exist:
# openssl.x86_64 1:3.2.2-6.el9_5 rhel-9-appstream
# Column 2 is the CANDIDATE (available) version, not the installed one --
# check-update never reports what's currently installed, so the batched
# rpm_installed_versions lookup below is what makes `current` true
# (D-02, spec S4). NF>=3 and the Obsoleting guard are unchanged from the
# legacy parse -- both already drop the lines that must be dropped (the
# NF>=3 filter also silently drops a wrapped two-line check-update entry,
# a pre-existing limitation this plan does not change).
LIST=$(dnf -q check-update 2>/dev/null | awk 'NF>=3 && $1 !~ /^Obsoleting/ {print}' || true)
# Advisory severity for the security subset (e.g. "Important/Sec." NEVRA);
# cross-referenced below by NEVRA-prefix match against each $LIST entry's
# bare package name — RPM NEVRA always starts "<name>-<version>...", so a
Expand All @@ -85,20 +219,45 @@ elif command -v dnf >/dev/null 2>&1; then
OLDIFS=$IFS
IFS='
'
# Pass 1: collect every pending package's bare name (arch stripped via
# the branch's existing name.arch trailing-component convention),
# validated by pkgname_is_safe (T-999.47-09) before it can reach rpm's
# argv. An invalid name is skipped, not aborted -- see pkgname_is_safe.
NAMES=""
for ENTRY in $LIST; do
[ -n "$ENTRY" ] || continue
NAME=${ENTRY%.*}
NAMEARCH=$(printf '%s\n' "$ENTRY" | awk '{print $1}')
NAME=${NAMEARCH%.*}
if pkgname_is_safe "$NAME"; then
NAMES="${NAMES}${NAMES:+ }${NAME}"
fi
done
# shellcheck disable=SC2086 # intentional word-splitting: NAMES is a
# space-joined list of already-validated (pkgname_is_safe) tokens, and
# this is the ONE batched rpm -q call (T-999.47-11) rather than one per
# package.
RPM_TABLE=$(rpm_installed_versions $NAMES)

# Pass 2: emit one packages[] entry per check-update line.
for ENTRY in $LIST; do
[ -n "$ENTRY" ] || continue
NAMEARCH=$(printf '%s\n' "$ENTRY" | awk '{print $1}')
AVAIL=$(printf '%s\n' "$ENTRY" | awk '{print $2}')
REPO=$(printf '%s\n' "$ENTRY" | awk '{print $3}')
NAME=${NAMEARCH%.*}
ARCH=${NAMEARCH##*.}
CUR=$(rpm_installed_version_for "$NAME" "$RPM_TABLE")
MATCH=$(printf '%s\n' "$SECLIST" | grep -m1 -- "${NAME}-" || true)
if [ -n "$MATCH" ]; then
SEV=$(printf '%s\n' "$MATCH" | awk '{print $1}' | sed -E 's#/Sec\.?$##' | tr '[:upper:]' '[:lower:]')
case "$SEV" in
critical|important) add_patch "$ENTRY" "high" "true" ;;
moderate) add_patch "$ENTRY" "medium" "true" ;;
low) add_patch "$ENTRY" "low" "true" ;;
*) add_patch "$ENTRY" "high" "true" ;;
critical|important) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
moderate) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
low) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
*) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
esac
else
add_patch "$ENTRY" "unknown" "false"
add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "false"
fi
done
IFS=$OLDIFS
Expand All @@ -109,28 +268,54 @@ elif command -v dnf >/dev/null 2>&1; then
[ $? -eq 1 ] && REBOOT=true

elif command -v yum >/dev/null 2>&1; then
LIST=$(yum -q check-update 2>/dev/null | awk 'NF>=3 {print $1}' || true)
# Same shape as the dnf branch above, reusing rpm_installed_versions,
# rpm_installed_version_for, pkgname_is_safe, add_package and json_escape
# rather than duplicating any of them. Every yum-specific difference from
# the dnf branch stays intact: no Obsoleting guard, the bare
# needs-restarting reboot probe (not `yum -q needs-restarting`), and its
# own SECLIST invocation.
LIST=$(yum -q check-update 2>/dev/null | awk 'NF>=3 {print}' || true)
SECLIST=$(yum -q updateinfo list security 2>/dev/null | awk 'NF>=3 {print $2, $3}' || true)
SECURITY=$(printf '%s\n' "$SECLIST" | grep -c '.' || true)
if [ -n "$LIST" ]; then
AVAILABLE=$(printf '%s\n' "$LIST" | wc -l | tr -d ' ')
OLDIFS=$IFS
IFS='
'
NAMES=""
for ENTRY in $LIST; do
[ -n "$ENTRY" ] || continue
NAMEARCH=$(printf '%s\n' "$ENTRY" | awk '{print $1}')
NAME=${NAMEARCH%.*}
if pkgname_is_safe "$NAME"; then
NAMES="${NAMES}${NAMES:+ }${NAME}"
fi
done
# shellcheck disable=SC2086 # intentional word-splitting: NAMES is a
# space-joined list of already-validated (pkgname_is_safe) tokens, and
# this is the ONE batched rpm -q call (T-999.47-11) rather than one per
# package.
RPM_TABLE=$(rpm_installed_versions $NAMES)

for ENTRY in $LIST; do
[ -n "$ENTRY" ] || continue
NAME=${ENTRY%.*}
NAMEARCH=$(printf '%s\n' "$ENTRY" | awk '{print $1}')
AVAIL=$(printf '%s\n' "$ENTRY" | awk '{print $2}')
REPO=$(printf '%s\n' "$ENTRY" | awk '{print $3}')
NAME=${NAMEARCH%.*}
ARCH=${NAMEARCH##*.}
CUR=$(rpm_installed_version_for "$NAME" "$RPM_TABLE")
MATCH=$(printf '%s\n' "$SECLIST" | grep -m1 -- "${NAME}-" || true)
if [ -n "$MATCH" ]; then
SEV=$(printf '%s\n' "$MATCH" | awk '{print $1}' | sed -E 's#/Sec\.?$##' | tr '[:upper:]' '[:lower:]')
case "$SEV" in
critical|important) add_patch "$ENTRY" "high" "true" ;;
moderate) add_patch "$ENTRY" "medium" "true" ;;
low) add_patch "$ENTRY" "low" "true" ;;
*) add_patch "$ENTRY" "high" "true" ;;
critical|important) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
moderate) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
low) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
*) add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "true" ;;
esac
else
add_patch "$ENTRY" "unknown" "false"
add_package "$NAME" "$ARCH" "$CUR" "$AVAIL" "$REPO" "false"
fi
done
IFS=$OLDIFS
Expand All @@ -140,5 +325,12 @@ elif command -v yum >/dev/null 2>&1; then
fi

NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
printf '{"patchbot": {"available": %s, "security": %s, "reboot_required": %s, "last_checked": "%s", "patches": [%s]}}\n' \
"${AVAILABLE:-0}" "${SECURITY:-0}" "$REBOOT" "$NOW" "$PATCHES"
# All three branches (apt, dnf, yum) build $PACKAGES now (999.47-03) -- a
# node with no supported package manager on PATH at all also gets this
# shape, with an empty packages[] array. The legacy patches[] shape is no
# longer emitted by this script; patchFactPackages's fallback to "patches"
# (backend/internal/httpapi/patching.go) remains the only thing that still
# knows it, as the degradation path for any node still running a pre-999.47
# copy of this module during rollout (spec section 7).
printf '{"patchbot": {"available": %s, "security": %s, "reboot_required": %s, "last_checked": "%s", "packages": [%s]}}\n' \
"${AVAILABLE:-0}" "${SECURITY:-0}" "$REBOOT" "$NOW" "$PACKAGES"
Loading
Loading