@oneuptime/common 11.4.1 → 11.5.0

package/Server/Utils/Monitor/NetworkDeviceHydrationUtil.ts

@@ -0,0 +1,201 @@
+import NetworkDevice from "../../../Models/DatabaseModels/NetworkDevice";
+import NetworkDeviceService from "../../Services/NetworkDeviceService";
+import MonitorSteps from "../../../Types/Monitor/MonitorSteps";
+import QueryHelper from "../../Types/Database/QueryHelper";
+import LIMIT_MAX from "../../../Types/Database/LimitMax";
+import MonitorType from "../../../Types/Monitor/MonitorType";
+import SnmpVersion from "../../../Types/Monitor/SnmpMonitor/SnmpVersion";
+import SnmpV3Auth from "../../../Types/Monitor/SnmpMonitor/SnmpV3Auth";
+import SnmpSecurityLevel from "../../../Types/Monitor/SnmpMonitor/SnmpSecurityLevel";
+import SnmpAuthProtocol from "../../../Types/Monitor/SnmpMonitor/SnmpAuthProtocol";
+import SnmpPrivProtocol from "../../../Types/Monitor/SnmpMonitor/SnmpPrivProtocol";
+import ObjectID from "../../../Types/ObjectID";
+import logger from "../Logger";
+
+/*
+ * Network Device monitor steps reference a NetworkDevice resource instead of
+ * carrying SNMP connection details. Probes are stateless and only understand
+ * concrete SNMP config, so before work is handed out the referenced device's
+ * hostname/credentials are hydrated into each step's `snmpMonitor` field.
+ */
+export interface HydratableMonitor {
+  id?: ObjectID | null | undefined;
+  monitorType?: MonitorType | undefined;
+  monitorSteps?: MonitorSteps | undefined;
+}
+
+export default class NetworkDeviceHydrationUtil {
+  // Accepts Monitor and MonitorTest alike (structural: monitorType + monitorSteps).
+  public static async hydrateNetworkDeviceMonitors(
+    monitors: Array<HydratableMonitor>,
+  ): Promise<void> {
+    const deviceIds: Set<string> = new Set();
+
+    for (const monitor of monitors) {
+      if (monitor.monitorType !== MonitorType.NetworkDevice) {
+        continue;
+      }
+
+      for (const step of monitor.monitorSteps?.data
+        ?.monitorStepsInstanceArray || []) {
+        const deviceId: string | undefined =
+          step.data?.networkDeviceMonitor?.networkDeviceId;
+        if (deviceId) {
+          deviceIds.add(deviceId);
+        }
+      }
+    }
+
+    if (deviceIds.size === 0) {
+      return;
+    }
+
+    const devices: Array<NetworkDevice> = await NetworkDeviceService.findBy({
+      query: {
+        _id: QueryHelper.any(Array.from(deviceIds)),
+      },
+      select: {
+        _id: true,
+        hostname: true,
+        snmpVersion: true,
+        snmpCommunityString: true,
+        snmpPort: true,
+        snmpV3Auth: true,
+        snmpV3SecurityLevel: true,
+        snmpV3Username: true,
+        snmpV3AuthProtocol: true,
+        snmpV3AuthKey: true,
+        snmpV3PrivProtocol: true,
+        snmpV3PrivKey: true,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+
+    const devicesById: Map<string, NetworkDevice> = new Map();
+    for (const device of devices) {
+      if (device.id) {
+        devicesById.set(device.id.toString(), device);
+      }
+    }
+
+    for (const monitor of monitors) {
+      if (monitor.monitorType !== MonitorType.NetworkDevice) {
+        continue;
+      }
+
+      for (const step of monitor.monitorSteps?.data
+        ?.monitorStepsInstanceArray || []) {
+        const deviceId: string | undefined =
+          step.data?.networkDeviceMonitor?.networkDeviceId;
+
+        if (!deviceId || !step.data) {
+          continue;
+        }
+
+        const device: NetworkDevice | undefined = devicesById.get(deviceId);
+
+        if (!device || !device.hostname) {
+          logger.warn(
+            `Network Device monitor ${monitor.id?.toString()} references missing device ${deviceId}. Step will not be executable.`,
+          );
+          continue;
+        }
+
+        step.data.snmpMonitor = {
+          snmpVersion: NetworkDeviceHydrationUtil.parseSnmpVersion(
+            device.snmpVersion,
+          ),
+          hostname: device.hostname,
+          port: device.snmpPort || 161,
+          communityString: device.snmpCommunityString || undefined,
+          snmpV3Auth: NetworkDeviceHydrationUtil.buildSnmpV3Auth(device),
+          oids: step.data.networkDeviceMonitor?.oids || [],
+          timeout: 5000,
+          retries: 3,
+          monitorInterfaces:
+            step.data.networkDeviceMonitor?.monitorInterfaces !== false,
+        };
+      }
+    }
+  }
+
+  /*
+   * Assembles the SnmpV3Auth object the probe expects. Prefers the flattened
+   * snmpV3* columns (the current storage), falling back to the deprecated
+   * snmpV3Auth JSON column so devices created before the columns existed keep
+   * working. Returns undefined when no v3 username is configured.
+   */
+  private static buildSnmpV3Auth(
+    device: NetworkDevice,
+  ): SnmpV3Auth | undefined {
+    if (device.snmpV3Username) {
+      return {
+        securityLevel:
+          (device.snmpV3SecurityLevel as SnmpSecurityLevel) ||
+          SnmpSecurityLevel.NoAuthNoPriv,
+        username: device.snmpV3Username,
+        authProtocol:
+          (device.snmpV3AuthProtocol as SnmpAuthProtocol | undefined) ||
+          undefined,
+        authKey: device.snmpV3AuthKey || undefined,
+        privProtocol:
+          (device.snmpV3PrivProtocol as SnmpPrivProtocol | undefined) ||
+          undefined,
+        privKey: device.snmpV3PrivKey || undefined,
+      };
+    }
+
+    // Legacy devices stored the whole object in the snmpV3Auth JSON column.
+    const legacy: SnmpV3Auth | undefined = device.snmpV3Auth as
+      | SnmpV3Auth
+      | undefined;
+    if (legacy && legacy.username) {
+      return legacy;
+    }
+
+    return undefined;
+  }
+
+  // Tolerates both enum values ("2c") and enum keys ("V2c") in stored config.
+  private static parseSnmpVersion(value: string | undefined): SnmpVersion {
+    switch ((value || "").toLowerCase()) {
+      case "1":
+      case "v1":
+        return SnmpVersion.V1;
+      case "3":
+      case "v3":
+        return SnmpVersion.V3;
+      default:
+        return SnmpVersion.V2c;
+    }
+  }
+
+  /*
+   * Resolves which NetworkDevices (polled by the given probe) match a trap
+   * source IP. Used by the trap ingest to fan traps out to device monitors.
+   */
+  public static async findDevicesByProbeAndSource(data: {
+    probeId: ObjectID;
+    sourceIpAddress: string;
+  }): Promise<Array<NetworkDevice>> {
+    return NetworkDeviceService.findBy({
+      query: {
+        probeId: data.probeId,
+        hostname: data.sourceIpAddress,
+      },
+      select: {
+        _id: true,
+        projectId: true,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+  }
+}

package/Server/Utils/Monitor/NetworkInventoryUtil.ts

@@ -0,0 +1,215 @@
+import Monitor from "../../../Models/DatabaseModels/Monitor";
+import NetworkInterface from "../../../Models/DatabaseModels/NetworkInterface";
+import NetworkDeviceService from "../../Services/NetworkDeviceService";
+import NetworkInterfaceService from "../../Services/NetworkInterfaceService";
+import LIMIT_MAX from "../../../Types/Database/LimitMax";
+import MonitorStep from "../../../Types/Monitor/MonitorStep";
+import SnmpInterface from "../../../Types/Monitor/SnmpMonitor/SnmpInterface";
+import LldpNeighbor from "../../../Types/Monitor/SnmpMonitor/LldpNeighbor";
+import ProbeMonitorResponse from "../../../Types/Probe/ProbeMonitorResponse";
+import ObjectID from "../../../Types/ObjectID";
+import OneUptimeDate from "../../../Types/Date";
+import logger from "../Logger";
+
+/*
+ * Keeps the NetworkDevice / NetworkInterface inventory in sync with each
+ * interface walk, then prunes the in-flight response down to MONITORED
+ * interfaces so criteria and metrics only consider ports the user cares
+ * about. Inventory rows always reflect every walked interface; the
+ * isMonitored flag is user-owned and never overwritten here.
+ */
+export default class NetworkInventoryUtil {
+  public static async updateFromWalk(data: {
+    monitor: Monitor;
+    dataToProcess: ProbeMonitorResponse;
+  }): Promise<void> {
+    const step: MonitorStep | undefined =
+      data.monitor.monitorSteps?.data?.monitorStepsInstanceArray?.find(
+        (monitorStep: MonitorStep) => {
+          return (
+            monitorStep.id.toString() ===
+            data.dataToProcess.monitorStepId.toString()
+          );
+        },
+      );
+
+    const deviceIdAsString: string | undefined =
+      step?.data?.networkDeviceMonitor?.networkDeviceId;
+
+    if (!deviceIdAsString || !data.monitor.projectId) {
+      return;
+    }
+
+    const deviceId: ObjectID = new ObjectID(deviceIdAsString);
+    const walkedInterfaces: Array<SnmpInterface> =
+      data.dataToProcess.snmpResponse?.interfaces || [];
+    const systemInfo:
+      | { sysDescr?: string | undefined; sysName?: string | undefined }
+      | undefined = data.dataToProcess.snmpResponse?.systemInfo;
+    const lldpNeighbors: Array<LldpNeighbor> | undefined =
+      data.dataToProcess.snmpResponse?.lldpNeighbors;
+
+    const now: Date = OneUptimeDate.getCurrentDate();
+
+    try {
+      // --- Device enrichment + cached counts ---
+      const deviceUpdate: Record<string, unknown> = {
+        lastSeenAt: now,
+      };
+
+      if (systemInfo?.sysDescr) {
+        deviceUpdate["sysDescr"] = systemInfo.sysDescr.substring(0, 500);
+      }
+      if (systemInfo?.sysName) {
+        deviceUpdate["sysName"] = systemInfo.sysName.substring(0, 100);
+      }
+
+      /*
+       * Store the LLDP snapshot (capped) whenever the walk ran, even if it
+       * found nothing — clearing stale neighbors is as important as adding
+       * new ones for keeping the topology accurate.
+       */
+      if (lldpNeighbors !== undefined) {
+        deviceUpdate["lldpNeighbors"] = lldpNeighbors.slice(0, 256);
+      }
+
+      if (walkedInterfaces.length > 0) {
+        deviceUpdate["interfacesTotal"] = walkedInterfaces.length;
+        deviceUpdate["interfacesUp"] = walkedInterfaces.filter(
+          (walked: SnmpInterface) => {
+            return walked.isAdministrativelyUp && walked.isOperationallyUp;
+          },
+        ).length;
+        deviceUpdate["interfacesDown"] = walkedInterfaces.filter(
+          (walked: SnmpInterface) => {
+            return walked.isAdministrativelyUp && !walked.isOperationallyUp;
+          },
+        ).length;
+      }
+
+      await NetworkDeviceService.updateOneById({
+        id: deviceId,
+        data: deviceUpdate as any,
+        props: {
+          isRoot: true,
+        },
+      });
+
+      if (walkedInterfaces.length === 0) {
+        return;
+      }
+
+      // --- Interface upsert ---
+      const existingInterfaces: Array<NetworkInterface> =
+        await NetworkInterfaceService.findBy({
+          query: {
+            networkDeviceId: deviceId,
+          },
+          select: {
+            _id: true,
+            interfaceIndex: true,
+            isMonitored: true,
+          },
+          limit: LIMIT_MAX,
+          skip: 0,
+          props: {
+            isRoot: true,
+          },
+        });
+
+      const existingByIndex: Map<number, NetworkInterface> = new Map();
+      for (const existing of existingInterfaces) {
+        if (existing.interfaceIndex !== undefined) {
+          existingByIndex.set(existing.interfaceIndex, existing);
+        }
+      }
+
+      const unmonitoredIndexes: Set<number> = new Set();
+
+      for (const walked of walkedInterfaces) {
+        const existing: NetworkInterface | undefined = existingByIndex.get(
+          walked.interfaceIndex,
+        );
+
+        if (existing && existing.isMonitored === false) {
+          unmonitoredIndexes.add(walked.interfaceIndex);
+        }
+
+        const interfaceData: Record<string, unknown> = {
+          name: (walked.name || "").substring(0, 100),
+          alias: walked.alias ? walked.alias.substring(0, 100) : null,
+          isOperationallyUp: walked.isOperationallyUp,
+          isAdministrativelyUp: walked.isAdministrativelyUp,
+          speedInMbps:
+            walked.speedInBitsPerSecond !== undefined
+              ? walked.speedInBitsPerSecond / 1000000
+              : null,
+          inRateMbps:
+            walked.inBitsPerSecond !== undefined
+              ? Math.round((walked.inBitsPerSecond / 1000000) * 1000) / 1000
+              : null,
+          outRateMbps:
+            walked.outBitsPerSecond !== undefined
+              ? Math.round((walked.outBitsPerSecond / 1000000) * 1000) / 1000
+              : null,
+          utilizationPercent: walked.utilizationPercent ?? null,
+          errorsPerSecond: walked.errorsPerSecond ?? null,
+          lastSeenAt: now,
+        };
+
+        if (existing && existing.id) {
+          await NetworkInterfaceService.updateOneById({
+            id: existing.id,
+            data: interfaceData as any,
+            props: {
+              isRoot: true,
+            },
+          });
+        } else {
+          const newInterface: NetworkInterface = new NetworkInterface();
+          newInterface.projectId = data.monitor.projectId;
+          newInterface.networkDeviceId = deviceId;
+          newInterface.interfaceIndex = walked.interfaceIndex;
+          newInterface.name = (walked.name || "").substring(0, 100);
+          if (walked.alias) {
+            newInterface.alias = walked.alias.substring(0, 100);
+          }
+          newInterface.isMonitored = true;
+          newInterface.isOperationallyUp = walked.isOperationallyUp;
+          newInterface.isAdministrativelyUp = walked.isAdministrativelyUp;
+          if (walked.speedInBitsPerSecond !== undefined) {
+            newInterface.speedInMbps = walked.speedInBitsPerSecond / 1000000;
+          }
+          newInterface.lastSeenAt = now;
+
+          await NetworkInterfaceService.create({
+            data: newInterface,
+            props: {
+              isRoot: true,
+            },
+          });
+        }
+      }
+
+      /*
+       * Prune the in-flight response to monitored interfaces only, so
+       * criteria (interface down / utilization / errors) and per-interface
+       * metrics ignore ports the user muted. The inventory above keeps the
+       * full picture.
+       */
+      if (unmonitoredIndexes.size > 0 && data.dataToProcess.snmpResponse) {
+        data.dataToProcess.snmpResponse.interfaces = walkedInterfaces.filter(
+          (walked: SnmpInterface) => {
+            return !unmonitoredIndexes.has(walked.interfaceIndex);
+          },
+        );
+      }
+    } catch (err) {
+      // Inventory bookkeeping must never fail the check pipeline.
+      logger.error(
+        `Failed to update network inventory for device ${deviceIdAsString}:`,
+      );
+      logger.error(err);
+    }
+  }
+}

package/Server/Utils/Monitor/SnmpInterfaceRateUtil.ts

@@ -0,0 +1,169 @@
+import { JSONObject } from "../../../Types/JSON";
+import SnmpInterface from "../../../Types/Monitor/SnmpMonitor/SnmpInterface";
+import ProbeMonitorResponse from "../../../Types/Probe/ProbeMonitorResponse";
+import OneUptimeDate from "../../../Types/Date";
+import logger from "../Logger";
+
+/*
+ * Computes per-interface rates (bandwidth, utilization, errors) for SNMP
+ * monitors by comparing the cumulative IF-MIB counters of the current check
+ * against the previous check stored in MonitorProbe.lastMonitoringLog.
+ *
+ * Probes stay stateless — the delta is computed here, on ingest, before the
+ * response is persisted. Negative deltas (counter wrap or device reboot) are
+ * skipped for that interface; rates resume on the following check.
+ */
+export default class SnmpInterfaceRateUtil {
+  public static attachInterfaceRates(data: {
+    probeMonitorResponse: ProbeMonitorResponse;
+    previousStepLog: JSONObject | undefined;
+  }): void {
+    const interfaces: Array<SnmpInterface> | undefined =
+      data.probeMonitorResponse.snmpResponse?.interfaces;
+
+    if (!interfaces || interfaces.length === 0) {
+      return;
+    }
+
+    if (!data.previousStepLog) {
+      return;
+    }
+
+    const previousSnmpResponse: JSONObject | undefined = data.previousStepLog[
+      "snmpResponse"
+    ] as JSONObject | undefined;
+
+    const previousInterfaces: Array<JSONObject> | undefined =
+      previousSnmpResponse?.["interfaces"] as Array<JSONObject> | undefined;
+
+    const previousMonitoredAtValue: unknown =
+      data.previousStepLog["monitoredAt"];
+
+    if (
+      !previousInterfaces ||
+      previousInterfaces.length === 0 ||
+      !previousMonitoredAtValue
+    ) {
+      return;
+    }
+
+    const previousMonitoredAt: Date = new Date(
+      previousMonitoredAtValue as string,
+    );
+
+    if (isNaN(previousMonitoredAt.getTime())) {
+      return;
+    }
+
+    /*
+     * lastMonitoringLog stores server receipt time as monitoredAt, so the
+     * current side of the delta uses server time too.
+     */
+    const elapsedSeconds: number =
+      (OneUptimeDate.getCurrentDate().getTime() -
+        previousMonitoredAt.getTime()) /
+      1000;
+
+    if (elapsedSeconds <= 0) {
+      return;
+    }
+
+    const counterDelta: (
+      currentValue: number | undefined,
+      previousValue: unknown,
+    ) => number | undefined = (
+      currentValue: number | undefined,
+      previousValue: unknown,
+    ) => {
+      if (
+        currentValue === undefined ||
+        typeof previousValue !== "number" ||
+        !isFinite(previousValue)
+      ) {
+        return undefined;
+      }
+
+      const delta: number = currentValue - previousValue;
+
+      // Negative delta: counter wrapped or the device rebooted.
+      return delta >= 0 ? delta : undefined;
+    };
+
+    const round: (value: number) => number = (value: number) => {
+      return Math.round(value * 100) / 100;
+    };
+
+    const previousByIndex: Map<number, JSONObject> = new Map();
+    for (const previousInterface of previousInterfaces) {
+      const index: unknown = previousInterface["interfaceIndex"];
+      if (typeof index === "number") {
+        previousByIndex.set(index, previousInterface);
+      }
+    }
+
+    for (const currentInterface of interfaces) {
+      const previousInterface: JSONObject | undefined = previousByIndex.get(
+        currentInterface.interfaceIndex,
+      );
+
+      if (!previousInterface) {
+        continue;
+      }
+
+      const inOctetsDelta: number | undefined = counterDelta(
+        currentInterface.inOctets,
+        previousInterface["inOctets"],
+      );
+      const outOctetsDelta: number | undefined = counterDelta(
+        currentInterface.outOctets,
+        previousInterface["outOctets"],
+      );
+
+      if (inOctetsDelta !== undefined) {
+        currentInterface.inBitsPerSecond = round(
+          (inOctetsDelta * 8) / elapsedSeconds,
+        );
+      }
+
+      if (outOctetsDelta !== undefined) {
+        currentInterface.outBitsPerSecond = round(
+          (outOctetsDelta * 8) / elapsedSeconds,
+        );
+      }
+
+      if (
+        currentInterface.speedInBitsPerSecond &&
+        currentInterface.speedInBitsPerSecond > 0 &&
+        (currentInterface.inBitsPerSecond !== undefined ||
+          currentInterface.outBitsPerSecond !== undefined)
+      ) {
+        const busiestDirectionBps: number = Math.max(
+          currentInterface.inBitsPerSecond || 0,
+          currentInterface.outBitsPerSecond || 0,
+        );
+        currentInterface.utilizationPercent = round(
+          (busiestDirectionBps / currentInterface.speedInBitsPerSecond) * 100,
+        );
+      }
+
+      const inErrorsDelta: number | undefined = counterDelta(
+        currentInterface.inErrors,
+        previousInterface["inErrors"],
+      );
+      const outErrorsDelta: number | undefined = counterDelta(
+        currentInterface.outErrors,
+        previousInterface["outErrors"],
+      );
+
+      if (inErrorsDelta !== undefined || outErrorsDelta !== undefined) {
+        currentInterface.errorsPerSecond = round(
+          ((inErrorsDelta || 0) + (outErrorsDelta || 0)) / elapsedSeconds,
+        );
+      }
+    }
+
+    logger.debug(
+      `Attached SNMP interface rates for monitor ${data.probeMonitorResponse.monitorId.toString()} over ${round(elapsedSeconds)}s window`,
+    );
+  }
+}