Patch plans, a monthly report and new-port alerts

Patch plans (Updates -> Patch plans): updates on a schedule, one server at a time, each by an
ordinary update run, stopping at the first failure by default, silencing what depends on a
server while it is updated, with one message at the end.

Monthly report (Operations -> Monthly report, and optionally a message on a day of the month):
availability, incidents, updates, restore tests, backups and renewals for a calendar month,
printable. Backed by daily endpoint figures and a record of renewals.

New ports: the first report with ports is the baseline; a TCP port that begins listening later and
is not noted on the server's Ports card is a warning, cleared by Mark as expected.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-19 23:16:14 +02:00
1 parent ddd0aa622a
commit be6c5552bd
46 files changed
+7836 -26

No files matched your search

+196
View File
@@ -0,0 +1,196 @@
import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { patchPlans, servers } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { isValidTimeZone } from "../services/maintenanceSchedules.js";
import { activeRunOf, cancelPlanRun, listPlanRuns, MAX_PLANS, parseItems, planDays, planOccurrences, planServerIds, planServers, planTags, PlanError, startPlanRun, type PlanRow, type PlanRunRow } from "../services/patchPlans.js";
import { InvalidTagError, normalizeTags, parseTags } from "../services/serverTags.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const patchPlansRouter = Router();
// Everyone signed in can see what is planned and how it went, like the Updates page. Making a plan is an administrator's (it will run on its own, at night);
// starting one now or stopping one that is running is an operator's, like an update run.
patchPlansRouter.use(requireAuth);
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
const planSchema = z
.object({
name: z.string().trim().min(1).max(100),
enabled: z.boolean().default(true),
days: z.array(z.number().int().min(0).max(6)).min(1).max(7),
startTime: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "Use a time like 02:00"),
timezone: z.string().trim().min(1).max(60),
tags: z.array(z.string()).max(12).default([]),
serverIds: z.array(z.number().int().positive()).max(200).default([]),
integrationId: z.number().int().positive(),
projectId: z.number().int().positive(),
templateId: z.number().int().positive(),
templateName: z.string().trim().min(1).max(200),
limitFrom: z.enum(["name", "hostname"]).default("name"),
stopOnFailure: z.boolean().default(true),
onlyWithUpdates: z.boolean().default(true),
silenceDependents: z.boolean().default(true),
windowMinutes: z.number().int().min(15).max(480).default(90),
})
.refine((d) => isValidTimeZone(d.timezone), { message: "That isn't a time zone the system knows (use a name like Europe/Stockholm).", path: ["timezone"] })
.refine((d) => d.tags.length > 0 || d.serverIds.length > 0, { message: "Choose which servers: give a tag, or name at least one server.", path: ["tags"] });
function valuesOf(d: z.infer<typeof planSchema>) {
return {
name: d.name,
enabled: d.enabled,
days: JSON.stringify([...new Set(d.days)].sort()),
startTime: d.startTime,
timezone: d.timezone,
tags: JSON.stringify(normalizeTags(d.tags)),
serverIds: JSON.stringify([...new Set(d.serverIds)]),
integrationId: d.integrationId,
projectId: d.projectId,
templateId: d.templateId,
templateName: d.templateName,
limitFrom: d.limitFrom,
stopOnFailure: d.stopOnFailure,
onlyWithUpdates: d.onlyWithUpdates,
silenceDependents: d.silenceDependents,
windowMinutes: d.windowMinutes,
};
}
const shapeRun = (r: PlanRunRow) => ({
id: r.id,
planId: r.planId,
planName: r.planName,
trigger: r.trigger,
startedBy: r.startedBy,
status: r.status,
message: r.message,
startedAt: r.startedAt,
finishedAt: r.finishedAt,
items: parseItems(r.items).map(({ windowIds: _w, ...i }) => i),
});
async function shapePlan(p: PlanRow, all: { id: number; name: string; tags: string | null }[], now: Date) {
const covered = planServers(p, all);
const next = planOccurrences(p, now, new Date(now.getTime() + 15 * 86_400_000)).filter((o) => o.start.getTime() > now.getTime()).slice(0, 3);
const active = await activeRunOf(p.id);
return {
id: p.id,
name: p.name,
enabled: p.enabled,
days: planDays(p),
startTime: p.startTime,
timezone: p.timezone,
tags: planTags(p),
serverIds: planServerIds(p),
integrationId: p.integrationId,
projectId: p.projectId,
templateId: p.templateId,
templateName: p.templateName,
limitFrom: p.limitFrom,
stopOnFailure: p.stopOnFailure,
onlyWithUpdates: p.onlyWithUpdates,
silenceDependents: p.silenceDependents,
windowMinutes: p.windowMinutes,
createdBy: p.createdBy,
servers: covered,
next: next.map((o) => o.start.toISOString()),
running: active !== null,
};
}
patchPlansRouter.get("/", asyncHandler(async (_req, res) => {
const now = new Date();
const rows = await db.select().from(patchPlans).orderBy(patchPlans.name);
const all = await db.select({ id: servers.id, name: servers.name, tags: servers.tags }).from(servers);
const tags = [...new Set(all.flatMap((s) => parseTags(s.tags)))].sort((a, b) => a.localeCompare(b, "sv"));
res.json({
plans: await Promise.all(rows.map((p) => shapePlan(p, all, now))),
runs: (await listPlanRuns({ limit: 15 })).map(shapeRun),
servers: all.map((s) => ({ id: s.id, name: s.name, tags: parseTags(s.tags) })).sort((a, b) => a.name.localeCompare(b.name)),
tags,
});
}));
/** The message for a rejected body, as a sentence. */
const reason = (parsed: { error: z.ZodError }) => parsed.error.issues[0]?.message ?? "That isn't a plan.";
patchPlansRouter.post("/", requireRole("admin"), asyncHandler(async (req, res) => {
const parsed = planSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: reason(parsed), details: parsed.error.flatten() });
if ((await db.select({ id: patchPlans.id }).from(patchPlans)).length >= MAX_PLANS) return res.status(409).json({ error: "too_many", message: `At most ${MAX_PLANS} plans.` });
let values;
try {
values = valuesOf(parsed.data);
} catch (err) {
if (err instanceof InvalidTagError) return res.status(400).json({ error: "invalid_tag", message: err.message });
throw err;
}
const actor = req.currentUser!;
const [row] = await db.insert(patchPlans).values({ ...values, createdBy: actor.name ?? actor.email ?? actor.oidcSub }).returning();
await recordAudit({ actor, category: "patch_plan", action: "create", targetType: "patch_plan", targetId: row.id, detail: { name: row.name, days: planDays(row), time: row.startTime } });
res.status(201).json({ plan: await shapePlan(row, await db.select({ id: servers.id, name: servers.name, tags: servers.tags }).from(servers), new Date()) });
}));
patchPlansRouter.put("/:id", requireRole("admin"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
const parsed = planSchema.safeParse(req.body);
if (!Number.isInteger(id) || !parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.success ? "That isn't a plan." : reason(parsed) });
const [before] = await db.select().from(patchPlans).where(eq(patchPlans.id, id)).limit(1);
if (!before) return res.status(404).json({ error: "not_found" });
let values;
try {
values = valuesOf(parsed.data);
} catch (err) {
if (err instanceof InvalidTagError) return res.status(400).json({ error: "invalid_tag", message: err.message });
throw err;
}
// A changed day or time is a new schedule: what it last started on no longer says whether today's has happened.
const rescheduled = values.days !== before.days || values.startTime !== before.startTime || values.timezone !== before.timezone;
const [row] = await db.update(patchPlans).set({ ...values, ...(rescheduled ? { lastRunDate: null } : {}) }).where(eq(patchPlans.id, id)).returning();
await recordAudit({ actor: req.currentUser!, category: "patch_plan", action: "update", targetType: "patch_plan", targetId: id, detail: { name: row.name, days: planDays(row), time: row.startTime } });
res.json({ plan: await shapePlan(row, await db.select({ id: servers.id, name: servers.name, tags: servers.tags }).from(servers), new Date()) });
}));
patchPlansRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [before] = await db.select().from(patchPlans).where(eq(patchPlans.id, id)).limit(1);
if (!before) return res.status(404).json({ error: "not_found" });
if (await activeRunOf(id)) return res.status(409).json({ error: "running", message: "It is running now. Stop the run first." });
await db.delete(patchPlans).where(eq(patchPlans.id, id));
await recordAudit({ actor: req.currentUser!, category: "patch_plan", action: "delete", targetType: "patch_plan", targetId: id, detail: { name: before.name } });
res.status(204).end();
}));
// Run it now, instead of at its time (it still starts again at its time).
patchPlansRouter.post("/:id/run", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const actor = req.currentUser!;
try {
const run = await startPlanRun(id, { trigger: "manual", actor: actor.name ?? actor.email ?? actor.oidcSub });
res.status(201).json({ run: shapeRun(run) });
} catch (err) {
if (err instanceof PlanError) return res.status(err.status).json({ error: err.code, message: err.message });
throw err;
}
}));
patchPlansRouter.post("/runs/:id/cancel", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const actor = req.currentUser!;
try {
const run = await cancelPlanRun(id, actor.name ?? actor.email ?? actor.oidcSub);
if (!run) return res.status(404).json({ error: "not_found" });
res.json({ run: shapeRun(run) });
} catch (err) {
if (err instanceof PlanError) return res.status(err.status).json({ error: err.code, message: err.message });
throw err;
}
}));
+40
View File
@@ -0,0 +1,40 @@
import { Router } from "express";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { buildMonthlyReport, isMonthId, lastFullMonth, monthlyReportText, recentMonths } from "../services/monthlyReport.js";
import { recordAudit } from "../services/audit.js";
import { notifyNow } from "../services/notify.js";
import { getSettings } from "../services/settingsStore.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const reportsRouter = Router();
reportsRouter.use(requireAuth);
/** The month asked for, or the last whole one; null when what was asked is not a month. */
async function monthFrom(query: unknown): Promise<{ id: string; months: { id: string; label: string }[] } | null> {
const tz = (await getSettings()).notifications.timezone || "UTC";
const months = recentMonths(new Date(), tz);
if (query === undefined || query === "") return { id: lastFullMonth(new Date(), tz), months };
if (!isMonthId(query) || !months.some((m) => m.id === query)) return null;
return { id: query, months };
}
// How a month went, for everyone signed in: it is only what the pages it comes from already show them. ?month=2026-09, the last whole month by default;
// ?format=text is the plain-text version a notification carries.
reportsRouter.get("/monthly", asyncHandler(async (req, res) => {
const picked = await monthFrom(req.query.month);
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months, like 2026-09." });
const report = await buildMonthlyReport(picked.id);
if (req.query.format === "text") return res.json(monthlyReportText(report));
res.json({ report, months: picked.months });
}));
// Send it now to the notification channels, as if it were the day. Administrators.
reportsRouter.post("/monthly/send", requireRole("admin"), asyncHandler(async (req, res) => {
const picked = await monthFrom((req.body as { month?: unknown } | undefined)?.month);
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months, like 2026-09." });
const { title, message } = monthlyReportText(await buildMonthlyReport(picked.id));
await notifyNow(title, message);
await recordAudit({ actor: req.currentUser!, category: "report", action: "send_monthly", targetType: "report", detail: { month: picked.id } });
res.json({ sent: true });
}));
+11
View File
@@ -7,6 +7,8 @@ import { requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { beginScan, endScan, MAX_SCAN_SPAN, resolveScanTarget, scanPorts, toRanges } from "../services/portScan.js";
import { type AgentPort, groupAgentPorts, parseJson } from "../services/agentPorts.js";
import { newListeningPorts, parseBaseline, portKey } from "../services/newPorts.js";
import { getSettings } from "../services/settingsStore.js";
import { asyncHandler } from "../utils/asyncHandler.js";
// Mounted under /api/servers/:id/ports by the servers router, which has already required a signed-in user.
@@ -37,6 +39,8 @@ export interface PortEntry {
agent: { addresses: string[]; process: string | null; localOnly: boolean } | null;
/** "open" if anything is using it; "reserved" if it only has a note. */
state: "open" | "reserved";
/** Began listening after the first report and nobody has noted it: a "new port" alert is on until it is noted or stops listening. */
isNew: boolean;
}
async function buildPortList(serverId: number) {
@@ -46,6 +50,11 @@ async function buildPortList(serverId: number) {
const agentRaw = parseJson<AgentPort[] | null>(server.listeningPorts, null);
const agent = groupAgentPorts(agentRaw ?? []);
// What is new: listening, reachable from outside, not in the baseline and not noted — the same rule the alert uses.
const expected = new Set(rows.filter((r) => r.label || r.comment).map((r) => portKey(r.protocol, r.port)));
const alerting = (await getSettings()).healthChecks.newPortAlerts;
const fresh = new Set(alerting ? newListeningPorts(agentRaw, parseBaseline(server.portBaseline), expected).map((p) => portKey(p.protocol, p.port)) : []);
const entries = new Map<string, PortEntry>();
for (const row of rows) {
const key = `${row.protocol}:${row.port}`;
@@ -59,6 +68,7 @@ async function buildPortList(serverId: number) {
lastSeenOpenAt: row.lastSeenOpenAt,
agent: agent.get(key) ?? null,
state: "reserved",
isNew: fresh.has(key),
});
}
for (const [key, info] of agent) {
@@ -74,6 +84,7 @@ async function buildPortList(serverId: number) {
lastSeenOpenAt: null,
agent: info,
state: "reserved",
isNew: fresh.has(key),
});
}
for (const entry of entries.values()) {
+9 -1
View File
@@ -13,6 +13,7 @@ import { scheduleLogRetentionPurge } from "../services/logRetentionScheduler.js"
import { purgeOldLogs } from "../services/logRetention.js";
import { scheduleQuietHoursFlush } from "../services/quietHoursScheduler.js";
import { scheduleWeeklyDigest } from "../services/weeklyDigestScheduler.js";
import { scheduleMonthlyReport } from "../services/monthlyReportScheduler.js";
import { buildDigest, sendDigest } from "../services/weeklyDigest.js";
import { enabledChannelCount } from "../services/notify.js";
import { CATEGORIES, CHANNEL_IDS } from "../services/notifyRouting.js";
@@ -143,7 +144,7 @@ const updateSchema = z.object({
.partial()
.optional(),
healthChecks: z
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730) })
.object({ serverOfflineMinutes: z.number().int().min(15).max(10080), diskUsagePercent: z.number().int().min(50).max(99), domainWarnDays: z.number().int().min(1).max(365), diskForecastDays: z.number().int().min(0).max(90), backupStaleHours: z.number().int().min(0).max(2160), restoreTestDays: z.number().int().min(0).max(730), newPortAlerts: z.boolean() })
.partial()
.optional(),
quietHours: z
@@ -165,6 +166,10 @@ const updateSchema = z.object({
.object({ enabled: z.boolean(), day: z.number().int().min(0).max(6), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
.partial()
.optional(),
monthlyReport: z
.object({ enabled: z.boolean(), day: z.number().int().min(1).max(28), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
.partial()
.optional(),
});
settingsRouter.put("/", requireRole("admin"), asyncHandler(async (req, res) => {
@@ -200,6 +205,9 @@ settingsRouter.put("/", requireRole("admin"), asyncHandler(async (req, res) => {
if (parsed.data.digest || parsed.data.notifications) {
await scheduleWeeklyDigest();
}
if (parsed.data.monthlyReport || parsed.data.notifications) {
await scheduleMonthlyReport();
}
await recordAudit({
actor: req.currentUser!,