Security & Maintenance pipeline

Built into ImpulseCore

Core owns the chrome — admin tabs, customer panels, scheduling, the patch walker, the CVE matcher, the email, the audit. Modules supply the data and the action. The behaviour is uniform across every Impulse module.

1. The contract, in one sentence

Modules implement two small interfaces — SecurityCollector (read state from a host: pending updates, kernel version, etc.) and SecurityActuator (do something to a host: take a snapshot, apply package updates, reboot). Core finds them in the module, ticks the schedule, walks the CVE feed, calls them at the right moments, renders the UI, and writes the audit trail.

Modules reach their hosts through their scoped admin proxy. SSH-backed collection or patching only happens when you turn on that module’s HIGH-RISK break-glass SSH setting, which is off by default.

Modules don’t render Security UI

The admin Security and Maintenance tabs and the customer Security and Maintenance tabs are rendered by Core helpers (ImpulseCore::renderSecurityTab(), ImpulseCore::renderMaintenanceTab(), ImpulseCore::renderClientSecurityTab(), ImpulseCore::renderClientMaintenanceTab()). Modules just call them from their addon / clientarea handlers. This is why every module’s Security tab looks identical — same defer button, same window editor, same CVE banner, same patch history.

Core’s own Security tab (ImpulseCore → Security) is the fleet-wide view: held pre-patch snapshots, what needs attention, active and unconfirmed advisories, version spread per module, CVE feed health (with a Grab CVE now button) and recent security activity. Patch and reboot actions live on each module’s own Security tab.

2. Three CVE feeds, one matcher

Core maintains mod_impulsecore_cve_feed, refreshed from three upstream sources:

Source	Cadence	Catches
Ubuntu USN	hourly (cve_feed_refresh)	OS-level CVEs (kernel, OpenSSL, glibc, OpenSSH) and any apt-shipped product.
CISA KEV	hourly (cve_feed_refresh)	Actively-exploited cross-reference; promotes a USN/NVD match to critical.
NVD by CPE	daily (nvd_product_feed_refresh)	Direct-install upstream products declared in module manifests’ cve_products. Catches PostgreSQL, RustFS, Meilisearch, GoTrue — products the USN-only feed misses.

The matcher walks every snapshot and intersects:

1. The host’s upgradable apt packages × USN entries by package name (apt-shipped path).
2. The module’s products × NVD entries by product, gated on the running version falling inside NVD’s affected version range (direct-install path).

Only a certain match counts. When NVD publishes no usable version range, or the running version can’t be compared, the pair is listed as an unconfirmed advisory on ImpulseCore → Security and nothing is scheduled for it. A patch already planned for a match that turns out unconfirmed or not affected is withdrawn.

Severity routing:

Severity	Surface	Action
Critical (CVSS 9.0+ or KEV-listed)	Red banner on customer Overview, Security tab badge, immediate customer email	Auto-scheduled patch 24 hours out (1 hour for KEV-listed); not deferrable.
High (CVSS 7.0–8.9)	Amber banner on Security tab	Scheduled into the target’s next maintenance window; deferrable.
Medium / Low	No banner	Not scheduled on its own.

3. The four interfaces modules implement

SecurityCollector (per-service)

Returns a snapshot for one customer’s service: pending updates, reboot-required, kernel + service versions, defensive posture (UFW / fail2ban / SSH config). 5-min timeout per call. Failures populate collectorError rather than throwing.

SecurityActuator (per-service)

Optional. Calls snapshotBeforePatch(), applyUpdates(), reboot(), and restoreFromSnapshot() for one customer’s service. Without an Actuator, the Security tab disables Patch / Reboot buttons and the data is read-only.

ServerSecurityCollector (per-host)

For shared / managed infrastructure where patches happen at the host level. Returns one snapshot per host. Drives the “Shared / Managed Servers” section of the admin Security tab.

ServerSecurityActuator (per-host)

Optional mirror of SecurityActuator that operates on a server row instead of a service row. The patch walker dispatches to per-service or per-server actuator based on which column is set on the schedule row.

Core finds these classes in each module’s lib/Security/ directory. Modules can register either or both pairs — per-service for dedicated tenants, per-server for shared infrastructure.

4. Pre-patch snapshots and failed patches

Before applyUpdates() runs against a host, the Actuator takes a provider snapshot through snapshotBeforePatch(), where the host’s provider and plan support snapshots. Every snapshot Core’s provider drivers create is recorded, so Core can delete it later — a provider bills a snapshot until it is deleted.

Core never restores a snapshot by itself. A restore rolls the whole server back and discards everything written to it since the snapshot — including customer data — so when a patch or the reboot after it fails, Core holds the snapshot for you instead:

• A critical rollback_held alert names the target, when the snapshot was taken, and what to do. It reaches the Overview’s Recent failures and your monitoring destinations.
• Automatic patching of that target pauses while it is held. A patch you start yourself (Patch now) still runs, and a successful patch ends the hold.
• ImpulseCore → Security → Held pre-patch snapshots lists every hold with Restore (type RESTORE; runs on the next tick), Delete (type DELETE) and, for a hold without a snapshot, Release (type RELEASE). These need WHMCS’s “Perform Server Operations” admin permission.
• A held snapshot is deleted automatically 7 days after it was taken, with a warning a day before; a hold without a snapshot is released after 7 days.

A failure that changed nothing on the host — the module refused the patch before starting, or the server couldn’t be reached — is held for 24 hours instead, then patching is tried again.

No snapshot is not a blocker

If the provider or plan can’t take a snapshot, the patch still runs — just without that safety net. If it then fails, the target is held without a snapshot (a critical failure_held alert) until you release it or the 7 days pass.

5. Customer maintenance window + deferral

Default per service: Sunday 02:00 in your WHMCS system timezone, 60 minutes. Customer-editable from their service’s Security or Maintenance tab (day-of-week, start hour, duration, timezone). A window may cross midnight.

High-severity patches honour a Defer button:

• One deferral per patch cycle.
• Hard cap of 14 days from when the patch first became applicable.
• After the cap, the next maintenance window applies the patch automatically — the Defer button disappears.

The clientarea Security tab surfaces the next scheduled patch time, the defer count remaining, and the hard-cap date. When the cap is reached, the copy reads “This update will be applied automatically in your next maintenance window. It can no longer be deferred.” Critical patches don’t render the Defer button at all.

6. The Core-owned security crons

Task	Cadence	Purpose
security_collect	daily	Refresh per-service + per-server snapshots from registered Collectors. 5-min per-collect timeout.
cve_feed_refresh	hourly	Pull Ubuntu USN + CISA KEV.
nvd_product_feed_refresh	daily	Pull NVD CVEs by CPE for every active module’s cve_products.
security_apply_critical	hourly	Match snapshots × CVE feed; schedule critical / KEV patches 24h (KEV: 1h) out with an immediate customer notice, and high-severity patches into the next maintenance window.
security_apply_window	5 min	Walk due, planned schedules where the customer’s window is open. Snapshot → patch → reboot; a failure is held for you, never rolled back automatically.
maintenance_warn	daily	Send the 24h-ahead notification email via the seeded WHMCS template.
security_freshness_check	daily	Raise error-level alerts for snapshots >3 days old, persistent collector errors, failed patches or reboots, stale CVE feeds and critical CVEs open over 24h; schedule a reboot in the next maintenance window for hosts that report one is required.
security_snapshot_expiry	daily	Delete held pre-patch snapshots after 7 days and clean up snapshots no longer needed.
security_events_purge	daily	90-day retention sweep on mod_impulsecore_security_events.
upstream_release_refresh	daily	Check for new upstream releases of the products modules run.

All of them ride on Core’s cron runner — you don’t add a per-module cron line for any of them. They tick automatically once Core itself is active.

7. Customer-facing copy is brand-neutral

Customer-facing strings in the Security and Maintenance tabs name your company — the Company Name from your WHMCS general settings (or “your hosting provider” if it’s blank) — and the maintenance notification emails carry no Impulse branding. There are no Impulse-branded strings on the customer surface — this is by design so you can sell the modules to your own customers without scrubbing copy. The email templates are yours to edit in ImpulseCore → Email Center.

Operators see Impulse branding; customers don’t

The admin Security and Maintenance tabs use Impulse copy + product names (because you, the operator, bought the module). The customer-facing client area reads exclusively from your WHMCS company configuration.