@oneuptime/common 12.0.15 → 12.0.17

package/Tests/Utils/NetworkDevice/DeviceHealthStateUtil.test.ts

@@ -0,0 +1,433 @@
+import { describe, expect, test } from "@jest/globals";
+import OneUptimeDate from "../../../Types/Date";
+import {
+  DeviceHealthCounts,
+  NetworkDeviceHealthState,
+  addDeviceHealth,
+  deviceAttentionCount,
+  deviceHealthState,
+  emptyDeviceHealthCounts,
+  mergeDeviceHealthCounts,
+  worstDeviceHealthState,
+} from "../../../Utils/NetworkDevice/DeviceHealthStateUtil";
+
+/*
+ * Issue #3320 — the rule that decides which SITES hold a device somebody
+ * has to look at.
+ *
+ * Everything the hierarchy view claims about an estate of 21,700 devices is
+ * this function summed up, so every branch of it is pinned here: what a
+ * monitor's verdict overrides, what a dark port does to a device that is
+ * otherwise answering, and — the one that matters most — what stays
+ * "unknown" instead of being quietly counted as either a failure or a
+ * success.
+ */
+
+const NOW: Date = OneUptimeDate.fromString("2026-08-21T12:00:00.000Z");
+
+type MinutesAgoFunction = (minutes: number) => Date;
+
+const minutesAgo: MinutesAgoFunction = (minutes: number): Date => {
+  return new Date(NOW.getTime() - minutes * 60 * 1000);
+};
+
+describe("deviceHealthState — a monitor's verdict is the system of record", () => {
+  test("a status the ladder does not call offline makes the device up, whatever the poll says", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: false,
+          // The SNMP side would say Down on its own.
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  test("an offline monitor status makes the device down, whatever the poll says", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: true,
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("a monitor-backed device that is up can still be degraded by its ports", () => {
+    expect(
+      deviceHealthState(
+        { monitorStatusIsOffline: false, interfacesDown: 3 },
+        NOW,
+      ),
+    ).toBe("degraded");
+  });
+
+  /*
+   * `undefined` means "no monitor is attached", which is the ordinary case
+   * for an SNMP-walked switch. It must not be read as a verdict of any kind
+   * — doing so would either paint every switch in the estate down or hide
+   * every real outage behind a stamped green.
+   */
+  test("an absent monitor status defers to reachability rather than deciding", () => {
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: undefined,
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("down");
+    expect(
+      deviceHealthState(
+        {
+          monitorStatusIsOffline: null,
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+});
+
+/*
+ * The rule that this module exists for, and the one an earlier revision got
+ * wrong: MonitorStatus is a LADDER (Operational 1 ... Offline 3), not a
+ * pair. Reading the operational end counted every "Degraded" device as down
+ * on the site card while the map you reach by clicking that card drew the
+ * same device green — the two halves of the product describing different
+ * networks, which is precisely what a shared classifier is for.
+ *
+ * NetworkDeviceTopology.ts resolves the ladder with
+ * `status.isOfflineState ? "down" : "up"`. These pin the same answer here.
+ */
+describe("the MonitorStatus ladder — a middle rung is not an outage", () => {
+  type LadderRow = {
+    name: string;
+    isOperationalState: boolean;
+    isOfflineState: boolean;
+  };
+
+  // The seeded project rows, plus the middle rung that broke the old rule.
+  const LADDER: Array<LadderRow> = [
+    { name: "Operational", isOperationalState: true, isOfflineState: false },
+    { name: "Degraded", isOperationalState: false, isOfflineState: false },
+    { name: "Maintenance", isOperationalState: false, isOfflineState: false },
+    { name: "Offline", isOperationalState: false, isOfflineState: true },
+  ];
+
+  // Exactly what NetworkDeviceTopology.ts does with a status row.
+  function mapVerdict(row: LadderRow): "up" | "down" {
+    return row.isOfflineState ? "down" : "up";
+  }
+
+  test.each(LADDER)(
+    "$name: the rollup agrees with the map about up/down",
+    (row: LadderRow) => {
+      const state: NetworkDeviceHealthState = deviceHealthState(
+        { monitorStatusIsOffline: row.isOfflineState },
+        NOW,
+      );
+      const rollupSaysDown: boolean = state === "down";
+      expect(rollupSaysDown).toBe(mapVerdict(row) === "down");
+    },
+  );
+
+  test("a Degraded device with no dark ports is healthy, not down", () => {
+    expect(deviceHealthState({ monitorStatusIsOffline: false }, NOW)).toBe(
+      "healthy",
+    );
+  });
+
+  /*
+   * The regression in one assertion. If anybody re-wires this input to the
+   * operational flag, a Degraded row (isOperationalState false) starts
+   * reading "down" here and this fails.
+   */
+  test("only the OFFLINE rung produces down", () => {
+    const downRungs: Array<string> = LADDER.filter((row: LadderRow) => {
+      return (
+        deviceHealthState(
+          { monitorStatusIsOffline: row.isOfflineState },
+          NOW,
+        ) === "down"
+      );
+    }).map((row: LadderRow) => {
+      return row.name;
+    });
+    expect(downRungs).toEqual(["Offline"]);
+  });
+});
+
+describe("deviceHealthState — reachability, when nothing is stamped", () => {
+  test("the probe asked and got nothing: down", () => {
+    expect(
+      deviceHealthState(
+        { isReachable: false, lastPolledAt: minutesAgo(2) },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("the probe asked and the device answered: healthy", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(2),
+          lastSeenAt: minutesAgo(2),
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  /*
+   * The whole point of DeviceReachabilityUtil: a fleet whose real poll
+   * cadence exceeds the old fifteen-minute freshness window is not an
+   * outage. A device that answered two hours ago and has not been asked
+   * since is still up, and the site above it must not turn red for it.
+   */
+  test("a stale but successful poll is still up, not down", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(600),
+          lastSeenAt: minutesAgo(600),
+          pollingIntervalInMinutes: 5,
+        },
+        NOW,
+      ),
+    ).toBe("healthy");
+  });
+
+  test("a device nothing has ever polled is unknown, not a failure", () => {
+    expect(deviceHealthState({}, NOW)).toBe("unknown");
+    expect(
+      deviceHealthState({ isReachable: null, interfacesDown: 4 }, NOW),
+    ).toBe("unknown");
+  });
+
+  test("polled but never once answered is down, not pending", () => {
+    expect(deviceHealthState({ lastPolledAt: minutesAgo(30) }, NOW)).toBe(
+      "down",
+    );
+  });
+});
+
+describe("deviceHealthState — degraded", () => {
+  test("an up device with dark ports is degraded", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: true,
+          lastPolledAt: minutesAgo(1),
+          lastSeenAt: minutesAgo(1),
+          interfacesDown: 1,
+        },
+        NOW,
+      ),
+    ).toBe("degraded");
+  });
+
+  /*
+   * Interface counts on a device that does not answer are by definition
+   * stale, so "down" wins. A device reported as both would otherwise be
+   * counted in the softer bucket and drop out of a "Down" filter.
+   */
+  test("down beats degraded when both could apply", () => {
+    expect(
+      deviceHealthState(
+        {
+          isReachable: false,
+          lastPolledAt: minutesAgo(1),
+          interfacesDown: 9,
+        },
+        NOW,
+      ),
+    ).toBe("down");
+  });
+
+  test("zero, negative and non-finite interface counts never degrade", () => {
+    const base: {
+      isReachable: boolean;
+      lastPolledAt: Date;
+      lastSeenAt: Date;
+    } = {
+      isReachable: true,
+      lastPolledAt: minutesAgo(1),
+      lastSeenAt: minutesAgo(1),
+    };
+    expect(deviceHealthState({ ...base, interfacesDown: 0 }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: -2 }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: NaN }, NOW)).toBe(
+      "healthy",
+    );
+    expect(deviceHealthState({ ...base, interfacesDown: null }, NOW)).toBe(
+      "healthy",
+    );
+  });
+
+  test("a missing device row is unknown rather than an exception", () => {
+    expect(deviceHealthState(null, NOW)).toBe("unknown");
+    expect(deviceHealthState(undefined, NOW)).toBe("unknown");
+  });
+});
+
+describe("tallies", () => {
+  test("an empty tally is all zeroes and a fresh object each time", () => {
+    const first: DeviceHealthCounts = emptyDeviceHealthCounts();
+    const second: DeviceHealthCounts = emptyDeviceHealthCounts();
+    expect(first).toEqual({
+      total: 0,
+      down: 0,
+      degraded: 0,
+      healthy: 0,
+      unknown: 0,
+    });
+    first.down = 5;
+    expect(second.down).toBe(0);
+  });
+
+  test("adding a device moves total and exactly one state", () => {
+    const counts: DeviceHealthCounts = emptyDeviceHealthCounts();
+    addDeviceHealth(counts, "down");
+    addDeviceHealth(counts, "degraded");
+    addDeviceHealth(counts, "degraded");
+    addDeviceHealth(counts, "healthy");
+    addDeviceHealth(counts, "unknown");
+    expect(counts).toEqual({
+      total: 5,
+      down: 1,
+      degraded: 2,
+      healthy: 1,
+      unknown: 1,
+    });
+  });
+
+  test("the four states always sum to the total", () => {
+    const counts: DeviceHealthCounts = emptyDeviceHealthCounts();
+    const states: Array<NetworkDeviceHealthState> = [
+      "down",
+      "healthy",
+      "healthy",
+      "unknown",
+      "degraded",
+      "healthy",
+    ];
+    for (const state of states) {
+      addDeviceHealth(counts, state);
+    }
+    expect(
+      counts.down + counts.degraded + counts.healthy + counts.unknown,
+    ).toBe(counts.total);
+  });
+
+  test("merging adds field by field without touching either input", () => {
+    const first: DeviceHealthCounts = {
+      total: 3,
+      down: 1,
+      degraded: 0,
+      healthy: 2,
+      unknown: 0,
+    };
+    const second: DeviceHealthCounts = {
+      total: 4,
+      down: 0,
+      degraded: 2,
+      healthy: 1,
+      unknown: 1,
+    };
+    expect(mergeDeviceHealthCounts(first, second)).toEqual({
+      total: 7,
+      down: 1,
+      degraded: 2,
+      healthy: 3,
+      unknown: 1,
+    });
+    expect(first.total).toBe(3);
+    expect(second.total).toBe(4);
+  });
+
+  test("attention is exactly down plus degraded — never unknown", () => {
+    expect(
+      deviceAttentionCount({
+        total: 10,
+        down: 2,
+        degraded: 3,
+        healthy: 1,
+        unknown: 4,
+      }),
+    ).toBe(5);
+    expect(deviceAttentionCount(emptyDeviceHealthCounts())).toBe(0);
+  });
+});
+
+describe("worstDeviceHealthState", () => {
+  test("one down device outranks any number of healthy ones", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 40,
+        down: 1,
+        degraded: 5,
+        healthy: 34,
+        unknown: 0,
+      }),
+    ).toBe("down");
+  });
+
+  test("degraded outranks healthy", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 10,
+        down: 0,
+        degraded: 1,
+        healthy: 9,
+        unknown: 0,
+      }),
+    ).toBe("degraded");
+  });
+
+  test("healthy outranks unknown — one confirmed answer is a verdict", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 5,
+        down: 0,
+        degraded: 0,
+        healthy: 1,
+        unknown: 4,
+      }),
+    ).toBe("healthy");
+  });
+
+  test("a subtree of nothing but never-polled devices is unknown", () => {
+    expect(
+      worstDeviceHealthState({
+        total: 3,
+        down: 0,
+        degraded: 0,
+        healthy: 0,
+        unknown: 3,
+      }),
+    ).toBe("unknown");
+  });
+
+  test("an empty subtree is unknown, not healthy", () => {
+    expect(worstDeviceHealthState(emptyDeviceHealthCounts())).toBe("unknown");
+  });
+});

package/Tests/Utils/SecurityEvent/GenericNormalizer.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from "@jest/globals";
+import NormalizedSecurityEvent from "../../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity from "../../../Types/SecurityEvent/OcsfSeverity";
+import GenericNormalizer from "../../../Utils/SecurityEvent/GenericNormalizer";
+
+/*
+ * The generic normalizer is the catch-all for arbitrary vendor JSON, so its
+ * whole value is the alias tables: "level" and "priority" must grade like
+ * "severity", "@timestamp" like "timestamp", "client_ip" like "source_ip".
+ * Removing an alias never errors — events just quietly lose their severity
+ * or entities and still ingest. These tests pin the aliases plus the safe
+ * defaults (Unknown severity, "Security event" message, content-hash uid)
+ * that keep an unrecognisable payload ingestable instead of dropped.
+ */
+describe("GenericNormalizer", () => {
+  describe("severity aliases", () => {
+    test.each<[string, string, OcsfSeverity]>([
+      ["severity", "high", OcsfSeverity.High],
+      ["level", "error", OcsfSeverity.Medium],
+      ["priority", "critical", OcsfSeverity.Critical],
+      ["risk_level", "low", OcsfSeverity.Low],
+    ])(
+      "%s: %s -> %s",
+      (field: string, value: string, expected: OcsfSeverity) => {
+        const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+          [field]: value,
+        });
+
+        expect(result.severityName).toBe(expected);
+      },
+    );
+
+    test("unrecognised severity defaults to Unknown", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        severity: "sev-nonsense",
+      });
+
+      expect(result.severityName).toBe(OcsfSeverity.Unknown);
+      expect(result.severityId).toBe(0);
+    });
+  });
+
+  describe("message aliases", () => {
+    test.each<[string, string]>([
+      ["message", "from message"],
+      ["msg", "from msg"],
+      ["summary", "from summary"],
+    ])("%s is accepted", (field: string, value: string) => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        [field]: value,
+      });
+
+      expect(result.message).toBe(value);
+    });
+
+    test("message wins over msg, and the default is 'Security event'", () => {
+      expect(
+        GenericNormalizer.normalize({ message: "primary", msg: "secondary" })
+          .message,
+      ).toBe("primary");
+
+      expect(GenericNormalizer.normalize({ foo: "bar" }).message).toBe(
+        "Security event",
+      );
+    });
+  });
+
+  describe("time aliases", () => {
+    test("timestamp parses", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        timestamp: "2024-05-01T12:00:00Z",
+      });
+
+      expect(result.time.getTime()).toBe(1714564800000);
+    });
+
+    test("@timestamp parses", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        "@timestamp": 1714564800,
+      });
+
+      expect(result.time.getTime()).toBe(1714564800000);
+    });
+  });
+
+  describe("entity aliases", () => {
+    test("user/host/ip aliases fill the principal and target columns", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        username: "alice",
+        hostname: "web-1",
+        client_ip: "1.2.3.4",
+        dest_ip: "5.6.7.8",
+      });
+
+      expect(result.principalUser).toBe("alice");
+      expect(result.principalHost).toBe("web-1");
+      expect(result.principalIp).toBe("1.2.3.4");
+      expect(result.targetIp).toBe("5.6.7.8");
+    });
+
+    test("primary spellings work too", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        user: "bob",
+        host: "db-1",
+        source_ip: "9.9.9.9",
+      });
+
+      expect(result.principalUser).toBe("bob");
+      expect(result.principalHost).toBe("db-1");
+      expect(result.principalIp).toBe("9.9.9.9");
+    });
+
+    test("observables are built from the extracted entities", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        username: "alice",
+        hostname: "web-1",
+        client_ip: "1.2.3.4",
+        dest_ip: "5.6.7.8",
+      });
+
+      expect(result.observables).toEqual([
+        "alice",
+        "web-1",
+        "1.2.3.4",
+        "5.6.7.8",
+      ]);
+    });
+  });
+
+  describe("class name from the event type", () => {
+    test("event_type prettifies with class uid pinned to 0", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        event_type: "port_scan",
+      });
+
+      expect(result.classUid).toBe(0);
+      expect(result.className).toBe("Port Scan");
+      expect(result.categoryUid).toBe(0);
+      expect(result.categoryName).toBe("Uncategorized");
+    });
+
+    test("spaces and dashes normalize before prettifying", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        category: "malware-detection event",
+      });
+
+      expect(result.className).toBe("Malware Detection Event");
+    });
+
+    test("without any type field the class name is Base Event", () => {
+      expect(GenericNormalizer.normalize({ foo: "bar" }).className).toBe(
+        "Base Event",
+      );
+    });
+  });
+
+  describe("eventUid", () => {
+    test.each<[string, string]>([
+      ["id", "id-1"],
+      ["uuid", "uuid-1"],
+      ["alert_id", "alert-1"],
+    ])("%s is accepted", (field: string, value: string) => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        [field]: value,
+      });
+
+      expect(result.eventUid).toBe(value);
+    });
+
+    test("without an id field, falls back to the content hash", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        message: "no id here",
+      });
+
+      expect(result.eventUid).toMatch(/^sha256:[0-9a-f]{64}$/);
+    });
+  });
+
+  describe("remaining columns", () => {
+    test("vendor, product, rule and status lift from their aliases", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        vendor: "Acme",
+        product: "AcmeEDR",
+        rule_name: "Suspicious PowerShell",
+        rule_id: "r-1",
+        status: "blocked",
+      });
+
+      expect(result.vendorName).toBe("Acme");
+      expect(result.productName).toBe("AcmeEDR");
+      expect(result.ruleName).toBe("Suspicious PowerShell");
+      expect(result.ruleId).toBe("r-1");
+      expect(result.statusName).toBe("blocked");
+    });
+
+    test("unrecognised fields still land in attributes", () => {
+      const result: NormalizedSecurityEvent = GenericNormalizer.normalize({
+        totally_custom: { deeply: "nested" },
+      });
+
+      expect(result.attributes["totally_custom.deeply"]).toBe("nested");
+    });
+  });
+});