@oneuptime/common 12.0.15 → 12.0.16

package/Utils/Monitor/NetworkDeviceLinkRuleUtil.ts

@@ -156,12 +156,47 @@ export interface LinkRuleOutcome {
   unsitedChildDeviceCount?: number | undefined;
 }
 
+/*
+ * One failing site, as the banner lists it rather than as the resolver
+ * computed it. Deliberately not LinkRuleGroupFailure itself: this crosses the
+ * wire to the browser, so it carries the two numbers an operator acts on and
+ * nothing else.
+ */
+export interface LinkRuleWarningSite {
+  siteId: string;
+  siteName?: string | undefined;
+  reason: LinkRuleGroupSkipReason;
+  /*
+   * Devices in THIS site the rule wanted to place and could not — the damage
+   * count for one line of the list, which sums to the sentence's total.
+   */
+  strandedDeviceCount: number;
+  // Devices in this site carrying the parent labels: 0, or >= 2 when ambiguous.
+  matchedParentCount: number;
+}
+
 /** One bullet in the topology map's warning banner. At most one per rule. */
 export interface LinkRuleWarning {
   ruleId: string;
   ruleName?: string | undefined;
   reason: LinkRuleWarningReason;
   message: string;
+  /*
+   * The failing sites themselves, in the same order the sentence names them,
+   * capped at MAX_LISTED_SITES. Present only for a site-scoped rule that
+   * failed somewhere.
+   *
+   * The sentence names three sites and then says "and 694 more", which is a
+   * blast radius and not something anybody can act on — issue #3321, where an
+   * operator with 949 sites had no way to find out WHICH of them were broken.
+   * The list is what turns that number back into work.
+   */
+  sites?: Array<LinkRuleWarningSite> | undefined;
+  /*
+   * Exact number of failing sites, still exact when `sites` was capped. Always
+   * >= sites.length, so the UI can say how many it is not showing.
+   */
+  siteCount?: number | undefined;
 }
 
 /*
@@ -204,6 +239,13 @@ export default class NetworkDeviceLinkRuleUtil {
 
   // Three names is enough to recognise a pattern; fourteen is a wall of text.
   private static readonly MAX_NAMED_SITES: number = 3;
+  /*
+   * How many failing sites ride back on the warning for the operator to work
+   * through. Far more than the sentence names, because this is a list nobody
+   * reads until they open it — but still capped: a project with 949 broken
+   * sites must not turn a 60-second map poll into a megabyte of site names.
+   */
+  public static readonly MAX_LISTED_SITES: number = 100;
   // Site names are ShortText and can run to 100 characters.
   private static readonly MAX_SITE_NAME_LENGTH: number = 40;
   private static readonly UNNAMED_SITE: string = "an unnamed site";
@@ -530,18 +572,17 @@ export default class NetworkDeviceLinkRuleUtil {
   }
 
   /*
-   * "Unit 4, Unit 9 and 2 more sites".
-   *
-   * Sorted before naming, and that is load-bearing rather than cosmetic: the
-   * live view refetches every sixty seconds and the device query has no ORDER
-   * BY, so an unsorted list would reshuffle the banner on every poll and read
-   * as a change that did not happen. The count stays exact even when the names
-   * are elided, so the operator always knows the true blast radius.
+   * By site name, then by id so equally-named (and unnamed) sites still have
+   * ONE order. Load-bearing rather than cosmetic: the live view refetches
+   * every sixty seconds and the device query has no ORDER BY, so an unsorted
+   * list would reshuffle the banner on every poll and read as a change that
+   * did not happen. The sentence and the site list share it so the three names
+   * the sentence gives are the first three rows of the list.
    */
-  private static describeSiteList(
+  private static sortSiteFailures(
     failures: Array<LinkRuleGroupFailure>,
-  ): string {
-    const sorted: Array<LinkRuleGroupFailure> = [...failures].sort(
+  ): Array<LinkRuleGroupFailure> {
+    return [...failures].sort(
       (a: LinkRuleGroupFailure, b: LinkRuleGroupFailure) => {
         return (
           (a.siteName || "").localeCompare(b.siteName || "") ||
@@ -549,6 +590,21 @@ export default class NetworkDeviceLinkRuleUtil {
         );
       },
     );
+  }
+
+  /*
+   * "Unit 4, Unit 9 and 2 more sites".
+   *
+   * Named in sortSiteFailures order, for the reasons given there. The count
+   * stays exact even when the names are elided, so the operator always knows
+   * the true blast radius — and `getWarning` sends the sites themselves
+   * alongside, because a blast radius is not a list of buildings.
+   */
+  private static describeSiteList(
+    failures: Array<LinkRuleGroupFailure>,
+  ): string {
+    const sorted: Array<LinkRuleGroupFailure> =
+      NetworkDeviceLinkRuleUtil.sortSiteFailures(failures);
 
     const names: Array<string> = sorted
       .slice(0, NetworkDeviceLinkRuleUtil.MAX_NAMED_SITES)
@@ -721,7 +777,7 @@ export default class NetworkDeviceLinkRuleUtil {
       );
     }
 
-    return {
+    const warning: LinkRuleWarning = {
       ruleId: outcome.ruleId,
       ruleName: outcome.ruleName,
       // Highest-ranked condition present. Ambiguity outranks a missing parent.
@@ -733,5 +789,31 @@ export default class NetworkDeviceLinkRuleUtil {
             : "devicesWithoutSite",
       message: parts.join(" "),
     };
+
+    /*
+     * The list, for the sentence the operator cannot act on. Written only when
+     * there are failing sites, so a warning that is purely about unsited
+     * devices — which names no site at all — keeps the exact shape it had.
+     *
+     * `siteCount` is the true total and `sites` may be shorter; a caller that
+     * reads sites.length as the number of broken sites is wrong at the cap,
+     * which is precisely the scale this exists for.
+     */
+    if (failures.length > 0) {
+      warning.siteCount = failures.length;
+      warning.sites = NetworkDeviceLinkRuleUtil.sortSiteFailures(failures)
+        .slice(0, NetworkDeviceLinkRuleUtil.MAX_LISTED_SITES)
+        .map((failure: LinkRuleGroupFailure) => {
+          return {
+            siteId: failure.siteId,
+            siteName: failure.siteName,
+            reason: failure.reason,
+            strandedDeviceCount: failure.matchedChildCount,
+            matchedParentCount: failure.matchedParentCount,
+          };
+        });
+    }
+
+    return warning;
   }
 }

package/Utils/NetworkDevice/DeviceHealthStateUtil.ts

@@ -0,0 +1,231 @@
+import DeviceReachabilityUtil, {
+  NetworkDeviceReachability,
+} from "./DeviceReachabilityUtil";
+
+/*
+ * The one place that decides how healthy a single NetworkDevice is, and how
+ * a pile of those verdicts rolls up into the counts a site card prints.
+ *
+ * The topology graph has always answered this question — a node is drawn
+ * red, amber or green — but it answered it inside the graph, from a
+ * NetworkTopologyNode that only exists once the whole map has been built.
+ * Issue #3320 needs the same verdict one level up, per SITE, so a franchise
+ * estate of 949 sites can say WHICH sites hold a device that needs
+ * attention without first drawing 21,700 device nodes.
+ *
+ * So the rule moves here, and both halves read it:
+ *
+ *   status  — a monitor-stamped status wins outright; otherwise the shared
+ *             reachability rule (the OUTCOME of the last poll, never its
+ *             age) decides, and a device nothing has ever polled is
+ *             `unknown` rather than a failure.
+ *   degraded — an up device with dark ports. A switch that answers every
+ *             poll while three of its interfaces are down is not down, but
+ *             it is exactly what somebody is looking for.
+ *
+ * This deliberately mirrors NetworkTopologyUtil.deviceStatus followed by
+ * TopologyHealthFilter.healthStateForNode, because a device that reads
+ * "degraded" on the map and "healthy" on the site card above it is the two
+ * halves of the product describing different networks.
+ *
+ * The ONE input the map has that a site rollup does not is the link layer:
+ * the map also degrades a node with an operationally-down link attached.
+ * That fact lives in the topology edges, which are built per-site and never
+ * exist at rollup time. The asymmetry is safe in the direction that matters
+ * — the device at the other end of a dead link reports its own dark port —
+ * but it is why a site's device counts can be very slightly kinder than the
+ * map you get when you drill into it, and never the reverse.
+ */
+
+/**
+ * How healthy one device is.
+ *
+ * "unknown" is a real answer and not a synonym for healthy: a device
+ * nothing has polled yet has never been judged, and counting it either way
+ * would put onboarding into an operator's attention list (or hide a real
+ * gap behind a green count).
+ */
+export type NetworkDeviceHealthState =
+  | "down"
+  | "degraded"
+  | "healthy"
+  | "unknown";
+
+/**
+ * The columns the classifier reads. Every caller selects exactly these.
+ *
+ * `monitorStatusIsOffline` is the OFFLINE end of the device's stamped
+ * MonitorStatus row — `undefined` when no monitor backs the device (the
+ * ordinary case for an SNMP-walked switch), which is what sends the
+ * decision down to reachability.
+ *
+ * The offline end and not the operational end, because MonitorStatus is a
+ * ladder rather than a pair: the seeded rows run Operational (1) ...
+ * Offline (3), and a "Degraded" row in between is NEITHER operational nor
+ * offline. The device map resolves that ladder with
+ * `isOfflineState ? "down" : "up"` (see NetworkDeviceTopology.ts), so a
+ * caller that passed the operational flag instead would count every
+ * degraded-but-reachable device as down — and the map you reach by
+ * clicking that card would draw the same device green.
+ */
+export interface DeviceHealthStateInput {
+  monitorStatusIsOffline?: boolean | null | undefined;
+  isReachable?: boolean | null | undefined;
+  lastPolledAt?: Date | string | null | undefined;
+  lastSeenAt?: Date | string | null | undefined;
+  pollingIntervalInMinutes?: number | null | undefined;
+  interfacesDown?: number | null | undefined;
+}
+
+/**
+ * How many devices in some scope are in each state.
+ *
+ * `total` is carried rather than derived so a caller can print "4 of 128"
+ * without summing four fields, and so a partial rollup (see the
+ * truncation flags on the hierarchy endpoint) still reports an honest
+ * denominator.
+ */
+export interface DeviceHealthCounts {
+  total: number;
+  down: number;
+  degraded: number;
+  healthy: number;
+  unknown: number;
+}
+
+/**
+ * The state of one device.
+ *
+ * Order is load-bearing. A stamped monitor status is the operator's own
+ * system of record and beats everything; then hard-down beats everything
+ * else, because a device that does not answer has interface counts that
+ * are by definition stale; then — and only for a device known to be up —
+ * dark ports make it degraded.
+ *
+ * Note what this means for a device stamped "Degraded": the ladder does not
+ * call it offline, so it is up, and it lands in "degraded" only if it also
+ * reports dark ports. That is the device map's rule, reproduced exactly.
+ * Diverging from it here — however reasonable the divergence — would put a
+ * site card and the map it opens into disagreement, which is the one
+ * outcome this module exists to make impossible.
+ */
+export function deviceHealthState(
+  device: DeviceHealthStateInput | null | undefined,
+  now?: Date | undefined,
+): NetworkDeviceHealthState {
+  if (!device) {
+    return "unknown";
+  }
+
+  let isUp: boolean;
+
+  if (
+    device.monitorStatusIsOffline === true ||
+    device.monitorStatusIsOffline === false
+  ) {
+    // Anything the ladder does not call OFFLINE is up. See the input docs.
+    isUp = !device.monitorStatusIsOffline;
+  } else {
+    const reachability: NetworkDeviceReachability =
+      DeviceReachabilityUtil.getStatus(
+        {
+          isReachable: device.isReachable,
+          lastPolledAt: device.lastPolledAt,
+          lastSeenAt: device.lastSeenAt,
+          pollingIntervalInMinutes: device.pollingIntervalInMinutes,
+        },
+        now,
+      );
+
+    if (reachability === NetworkDeviceReachability.Pending) {
+      return "unknown";
+    }
+
+    isUp = reachability === NetworkDeviceReachability.Up;
+  }
+
+  if (!isUp) {
+    return "down";
+  }
+
+  if (
+    typeof device.interfacesDown === "number" &&
+    Number.isFinite(device.interfacesDown) &&
+    device.interfacesDown > 0
+  ) {
+    return "degraded";
+  }
+
+  return "healthy";
+}
+
+/** A fresh, all-zero tally. */
+export function emptyDeviceHealthCounts(): DeviceHealthCounts {
+  return {
+    total: 0,
+    down: 0,
+    degraded: 0,
+    healthy: 0,
+    unknown: 0,
+  };
+}
+
+/**
+ * Add one device's verdict to a tally, in place.
+ *
+ * Mutating on purpose: the hierarchy aggregator walks tens of thousands of
+ * devices into a few hundred buckets in one pass, and allocating a fresh
+ * five-field object per device is the whole cost of that pass.
+ */
+export function addDeviceHealth(
+  counts: DeviceHealthCounts,
+  state: NetworkDeviceHealthState,
+): void {
+  counts.total += 1;
+  counts[state] += 1;
+}
+
+/** The sum of two tallies, as a new object. */
+export function mergeDeviceHealthCounts(
+  first: DeviceHealthCounts,
+  second: DeviceHealthCounts,
+): DeviceHealthCounts {
+  return {
+    total: first.total + second.total,
+    down: first.down + second.down,
+    degraded: first.degraded + second.degraded,
+    healthy: first.healthy + second.healthy,
+    unknown: first.unknown + second.unknown,
+  };
+}
+
+/**
+ * How many devices in this tally need somebody to look at them — the union
+ * of down and degraded, which is what every "needs attention" control in
+ * the product means by the phrase.
+ */
+export function deviceAttentionCount(counts: DeviceHealthCounts): number {
+  return counts.down + counts.degraded;
+}
+
+/**
+ * The worst state present in a tally, or "unknown" for an empty one.
+ *
+ * Used to color a site by its devices: one dark switch in a store of forty
+ * makes the store's device rollup read "down", the same worst-of rule
+ * SiteStatusRollupUtil applies to the site's own MonitorStatus.
+ */
+export function worstDeviceHealthState(
+  counts: DeviceHealthCounts,
+): NetworkDeviceHealthState {
+  if (counts.down > 0) {
+    return "down";
+  }
+  if (counts.degraded > 0) {
+    return "degraded";
+  }
+  if (counts.healthy > 0) {
+    return "healthy";
+  }
+  return "unknown";
+}

package/Utils/SecurityEvent/GenericNormalizer.ts

@@ -0,0 +1,208 @@
+import { JSONObject } from "../../Types/JSON";
+import NormalizedSecurityEvent from "../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity, {
+  OcsfSeverityId,
+  normalizeOcsfSeverity,
+} from "../../Types/SecurityEvent/OcsfSeverity";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+  readString,
+  readValue,
+} from "./NormalizerHelpers";
+import { prettifyUdmEventType } from "./UdmNormalizer";
+
+/*
+ * Best-effort normalizer for security events that are neither OCSF nor
+ * UDM — arbitrary vendor JSON forwarded from a SIEM, a webhook, or a
+ * custom script. Field lookup walks common aliases; anything not
+ * recognized still lands in `attributes`, so nothing is lost.
+ */
+
+const MESSAGE_FIELDS: Array<string> = [
+  "message",
+  "msg",
+  "summary",
+  "description",
+  "title",
+  "alert_name",
+  "alertName",
+  "name",
+];
+
+const SEVERITY_FIELDS: Array<string> = [
+  "severity",
+  "severity_name",
+  "level",
+  "priority",
+  "risk_level",
+  "riskLevel",
+];
+
+const TIME_FIELDS: Array<string> = [
+  "timestamp",
+  "time",
+  "@timestamp",
+  "event_time",
+  "eventTime",
+  "created_at",
+  "createdAt",
+  "date",
+  "detected_at",
+  "detectedAt",
+];
+
+const USER_FIELDS: Array<string> = [
+  "user",
+  "username",
+  "user_name",
+  "userName",
+  "account",
+  "principal",
+  "actor",
+];
+
+const HOST_FIELDS: Array<string> = [
+  "host",
+  "hostname",
+  "host_name",
+  "computer",
+  "computer_name",
+  "device",
+  "device_name",
+  "machine",
+];
+
+const SOURCE_IP_FIELDS: Array<string> = [
+  "source_ip",
+  "src_ip",
+  "sourceIp",
+  "srcIp",
+  "client_ip",
+  "clientIp",
+  "ip",
+  "ip_address",
+  "ipAddress",
+];
+
+const TARGET_IP_FIELDS: Array<string> = [
+  "destination_ip",
+  "dest_ip",
+  "dst_ip",
+  "destinationIp",
+  "target_ip",
+  "targetIp",
+  "server_ip",
+];
+
+const TYPE_FIELDS: Array<string> = [
+  "event_type",
+  "eventType",
+  "category",
+  "type",
+  "action",
+];
+
+const VENDOR_FIELDS: Array<string> = ["vendor", "vendor_name", "vendorName"];
+
+const PRODUCT_FIELDS: Array<string> = [
+  "product",
+  "product_name",
+  "productName",
+  "source",
+  "log_source",
+  "logSource",
+];
+
+const RULE_NAME_FIELDS: Array<string> = [
+  "rule",
+  "rule_name",
+  "ruleName",
+  "signature",
+  "detection",
+];
+
+const ID_FIELDS: Array<string> = [
+  "id",
+  "uid",
+  "uuid",
+  "event_id",
+  "eventId",
+  "alert_id",
+  "alertId",
+];
+
+function readFirst(payload: JSONObject, fields: Array<string>): string {
+  for (const field of fields) {
+    const value: string = readString(payload, field);
+    if (value) {
+      return value;
+    }
+  }
+
+  return "";
+}
+
+export default class GenericNormalizer {
+  public static normalize(payload: JSONObject): NormalizedSecurityEvent {
+    const severityName: OcsfSeverity =
+      normalizeOcsfSeverity(readFirst(payload, SEVERITY_FIELDS)) ||
+      OcsfSeverity.Unknown;
+
+    let time: Date | null = null;
+    for (const field of TIME_FIELDS) {
+      time = parseEventTime(readValue(payload, field));
+      if (time) {
+        break;
+      }
+    }
+
+    const typeText: string = readFirst(payload, TYPE_FIELDS);
+    const className: string = typeText
+      ? prettifyUdmEventType(typeText.replace(/[\s.-]+/g, "_"))
+      : "Base Event";
+
+    const principalUser: string = readFirst(payload, USER_FIELDS);
+    const principalHost: string = readFirst(payload, HOST_FIELDS);
+    const principalIp: string = readFirst(payload, SOURCE_IP_FIELDS);
+    const targetIp: string = readFirst(payload, TARGET_IP_FIELDS);
+
+    return {
+      time: time || new Date(),
+      eventUid: readFirst(payload, ID_FIELDS) || contentHashEventUid(payload),
+      categoryUid: 0,
+      categoryName: "Uncategorized",
+      classUid: 0,
+      className,
+      activityName: "",
+      severityId: OcsfSeverityId[severityName],
+      severityName,
+      statusName: readString(payload, "status"),
+      message: readFirst(payload, MESSAGE_FIELDS) || "Security event",
+      vendorName: readFirst(payload, VENDOR_FIELDS),
+      productName: readFirst(payload, PRODUCT_FIELDS),
+      ruleId: readString(payload, "rule_id") || readString(payload, "ruleId"),
+      ruleName: readFirst(payload, RULE_NAME_FIELDS),
+      mitreTactics: [],
+      mitreTechniques: [],
+      principalUser,
+      principalHost,
+      principalIp,
+      principalProcess: readString(payload, "process"),
+      targetUser: readString(payload, "target_user"),
+      targetHost: readString(payload, "target_host"),
+      targetIp,
+      targetPort: 0,
+      targetResource: readString(payload, "target"),
+      observables: buildObservables([
+        principalUser,
+        principalHost,
+        principalIp,
+        targetIp,
+      ]),
+      attributes: flattenPayload(payload),
+    };
+  }
+}