@oneuptime/common 12.0.15 → 12.0.17

package/Utils/SecurityEvent/GoogleSecOpsAlertNormalizer.ts

@@ -0,0 +1,206 @@
+import { JSONObject, JSONValue } from "../../Types/JSON";
+import NormalizedSecurityEvent from "../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity, {
+  OcsfSeverityId,
+  normalizeOcsfSeverity,
+} from "../../Types/SecurityEvent/OcsfSeverity";
+import { ocsfCategoryForClassUid } from "../../Types/SecurityEvent/OcsfEventClass";
+import UdmNormalizer from "./UdmNormalizer";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+  readString,
+  readValue,
+} from "./NormalizerHelpers";
+
+/*
+ * Google SecOps (Chronicle) detection/alert payload -> a Detection Finding
+ * (OCSF class 2004).
+ *
+ * This is the shape a SecOps SOAR playbook webhook or the detections
+ * stream (legacyStreamDetectionAlerts) delivers: rule metadata in a
+ * `detection` array plus the matched UDM events in `collectionElements`.
+ * The matched sample events are run through the UDM entity extraction so
+ * the finding row inherits their observables — that is what makes a
+ * detection joinable to the hosts/users it fired on.
+ */
+
+const DETECTION_FINDING_CLASS_UID: number = 2004;
+
+/*
+ * How many sample events to mine for observables. Detections can carry
+ * hundreds of matched events; a handful is enough to identify the
+ * entities involved without turning one finding row into a megabyte.
+ */
+const MAX_SAMPLE_EVENTS: number = 25;
+
+function collectSampleEvents(payload: JSONObject): Array<JSONObject> {
+  const events: Array<JSONObject> = [];
+
+  const collectionElements: JSONValue =
+    readValue(payload, "collectionElements") ??
+    readValue(payload, "collection_elements");
+
+  if (!Array.isArray(collectionElements)) {
+    return events;
+  }
+
+  for (const element of collectionElements) {
+    if (typeof element !== "object" || element === null) {
+      continue;
+    }
+
+    const references: JSONValue = readValue(
+      element as JSONObject,
+      "references",
+    );
+
+    if (!Array.isArray(references)) {
+      continue;
+    }
+
+    for (const reference of references) {
+      if (events.length >= MAX_SAMPLE_EVENTS) {
+        return events;
+      }
+
+      if (typeof reference !== "object" || reference === null) {
+        continue;
+      }
+
+      const event: JSONValue = readValue(reference as JSONObject, "event");
+
+      if (event && typeof event === "object" && !Array.isArray(event)) {
+        events.push(event as JSONObject);
+      }
+    }
+  }
+
+  return events;
+}
+
+function readDetectionEntry(payload: JSONObject): JSONObject | null {
+  const detection: JSONValue = readValue(payload, "detection");
+
+  if (Array.isArray(detection)) {
+    const first: JSONValue = detection[0] as JSONValue;
+    if (first && typeof first === "object" && !Array.isArray(first)) {
+      return first as JSONObject;
+    }
+    return null;
+  }
+
+  if (detection && typeof detection === "object") {
+    return detection as JSONObject;
+  }
+
+  return null;
+}
+
+export default class GoogleSecOpsAlertNormalizer {
+  public static isGoogleSecOpsAlert(payload: JSONObject): boolean {
+    const type: string = readString(payload, "type").toUpperCase();
+
+    return Boolean(
+      readDetectionEntry(payload) ||
+        type.includes("RULE_DETECTION") ||
+        readValue(payload, "collectionElements") ||
+        readValue(payload, "collection_elements"),
+    );
+  }
+
+  public static normalize(payload: JSONObject): NormalizedSecurityEvent {
+    const detection: JSONObject | null = readDetectionEntry(payload);
+
+    const ruleName: string = detection
+      ? readString(detection, "ruleName") || readString(detection, "rule_name")
+      : "";
+
+    const ruleId: string = detection
+      ? readString(detection, "ruleId") ||
+        readString(detection, "rule_id") ||
+        readString(detection, "ruleVersionId") ||
+        readString(detection, "rule_version_id")
+      : "";
+
+    const severityName: OcsfSeverity =
+      (detection && normalizeOcsfSeverity(readString(detection, "severity"))) ||
+      normalizeOcsfSeverity(readString(payload, "severity")) ||
+      OcsfSeverity.Unknown;
+
+    const time: Date | null = parseEventTime(
+      readValue(payload, "detectionTime") ??
+        readValue(payload, "detection_time") ??
+        readValue(payload, "createdTime") ??
+        readValue(payload, "created_time"),
+    );
+
+    /*
+     * Mine the matched UDM sample events for entities. The detection row's
+     * observables become the union across samples, and the first sample
+     * supplies the principal/target columns so the finding points at a
+     * concrete actor instead of nothing.
+     */
+    const sampleEvents: Array<JSONObject> = collectSampleEvents(payload);
+    const sampleObservables: Array<string> = [];
+    let firstSample: NormalizedSecurityEvent | null = null;
+
+    for (const sampleEvent of sampleEvents) {
+      const normalized: NormalizedSecurityEvent =
+        UdmNormalizer.normalize(sampleEvent);
+
+      if (!firstSample) {
+        firstSample = normalized;
+      }
+
+      sampleObservables.push(...normalized.observables);
+    }
+
+    const { categoryUid, categoryName } = ocsfCategoryForClassUid(
+      DETECTION_FINDING_CLASS_UID,
+    );
+
+    const description: string = detection
+      ? readString(detection, "description")
+      : "";
+
+    const message: string =
+      ruleName || description || "Google SecOps detection";
+
+    return {
+      time: time || new Date(),
+      eventUid: readString(payload, "id") || contentHashEventUid(payload),
+      categoryUid,
+      categoryName,
+      classUid: DETECTION_FINDING_CLASS_UID,
+      className: "Detection Finding",
+      activityName: "Create",
+      severityId: OcsfSeverityId[severityName],
+      severityName,
+      statusName:
+        readString(payload, "detection.alertState") ||
+        readString(payload, "detection.alert_state") ||
+        "",
+      message,
+      vendorName: "Google",
+      productName: "Google SecOps",
+      ruleId,
+      ruleName,
+      mitreTactics: firstSample ? firstSample.mitreTactics : [],
+      mitreTechniques: firstSample ? firstSample.mitreTechniques : [],
+      principalUser: firstSample ? firstSample.principalUser : "",
+      principalHost: firstSample ? firstSample.principalHost : "",
+      principalIp: firstSample ? firstSample.principalIp : "",
+      principalProcess: firstSample ? firstSample.principalProcess : "",
+      targetUser: firstSample ? firstSample.targetUser : "",
+      targetHost: firstSample ? firstSample.targetHost : "",
+      targetIp: firstSample ? firstSample.targetIp : "",
+      targetPort: firstSample ? firstSample.targetPort : 0,
+      targetResource: firstSample ? firstSample.targetResource : "",
+      observables: buildObservables(sampleObservables),
+      attributes: flattenPayload(payload),
+    };
+  }
+}

package/Utils/SecurityEvent/NormalizerHelpers.ts

@@ -0,0 +1,263 @@
+import { JSONObject, JSONValue } from "../../Types/JSON";
+import Crypto from "../Crypto";
+
+/*
+ * Shared helpers for the security-event normalizers (OCSF, UDM, SecOps
+ * alert, generic). Pure and isomorphic — no server imports — so the same
+ * code is unit-testable and usable from the UI if ever needed.
+ */
+
+/*
+ * Flatten a nested payload into dot-notation keys with scalar values, the
+ * shape the SecurityEvent `attributes` Map(String,String) column stores.
+ *
+ * Arrays of scalars collapse to a comma-joined string (queryable with a
+ * "contains" filter); arrays of objects recurse with the index in the key.
+ * Depth is capped so a hostile payload cannot recurse unboundedly.
+ */
+export function flattenPayload(
+  payload: JSONObject,
+  maxDepth: number = 10,
+): JSONObject {
+  const result: JSONObject = {};
+
+  const visit: (value: JSONValue, prefix: string, depth: number) => void = (
+    value: JSONValue,
+    prefix: string,
+    depth: number,
+  ): void => {
+    if (value === null || value === undefined) {
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      const scalars: Array<JSONValue> = value.filter(
+        (item: JSONValue): boolean => {
+          return typeof item !== "object" || item === null;
+        },
+      );
+
+      if (scalars.length === value.length) {
+        if (value.length > 0) {
+          result[prefix] = value
+            .map((item: JSONValue): string => {
+              return String(item);
+            })
+            .join(",");
+        }
+        return;
+      }
+
+      value.forEach((item: JSONValue, index: number): void => {
+        visit(item, `${prefix}.${index}`, depth + 1);
+      });
+
+      return;
+    }
+
+    if (typeof value === "object") {
+      if (depth >= maxDepth) {
+        result[prefix] = JSON.stringify(value);
+        return;
+      }
+
+      for (const key of Object.keys(value as JSONObject)) {
+        const child: JSONValue = (value as JSONObject)[key];
+        visit(child, prefix ? `${prefix}.${key}` : key, depth + 1);
+      }
+
+      return;
+    }
+
+    result[prefix] = String(value);
+  };
+
+  visit(payload, "", 0);
+
+  return result;
+}
+
+/*
+ * Read a string off a nested payload by dot path, tolerating arrays along
+ * the way (first element wins). Returns '' when the path is absent or not
+ * scalar — normalizers treat empty string as "source did not say".
+ */
+export function readString(payload: JSONObject, path: string): string {
+  const value: JSONValue = readValue(payload, path);
+
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    const first: JSONValue = value.find((item: JSONValue): boolean => {
+      return item !== null && item !== undefined && typeof item !== "object";
+    });
+    return first === undefined ? "" : String(first);
+  }
+
+  if (typeof value === "object") {
+    return "";
+  }
+
+  return String(value);
+}
+
+export function readNumber(payload: JSONObject, path: string): number | null {
+  const value: JSONValue = readValue(payload, path);
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed: number = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+
+  return null;
+}
+
+export function readStringArray(
+  payload: JSONObject,
+  path: string,
+): Array<string> {
+  const value: JSONValue = readValue(payload, path);
+
+  if (value === null || value === undefined) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value
+      .filter((item: JSONValue): boolean => {
+        return item !== null && item !== undefined && typeof item !== "object";
+      })
+      .map((item: JSONValue): string => {
+        return String(item);
+      });
+  }
+
+  if (typeof value === "object") {
+    return [];
+  }
+
+  return [String(value)];
+}
+
+export function readValue(payload: JSONObject, path: string): JSONValue {
+  const parts: Array<string> = path.split(".");
+  let current: JSONValue = payload;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return null;
+    }
+
+    if (Array.isArray(current)) {
+      current = current[0] as JSONValue;
+    }
+
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object" ||
+      Array.isArray(current)
+    ) {
+      return null;
+    }
+
+    current = (current as JSONObject)[part] as JSONValue;
+  }
+
+  return current === undefined ? null : current;
+}
+
+/*
+ * Parse the timestamps security payloads actually carry: RFC3339 strings,
+ * epoch seconds, epoch millis, and epoch micros/nanos (which UDM and OCSF
+ * both use in places). Returns null rather than guessing when the value is
+ * unparseable — the caller decides the fallback.
+ */
+export function parseEventTime(value: JSONValue): Date | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  if (typeof value === "string" && value.trim() !== "") {
+    const numeric: number = Number(value);
+
+    if (!Number.isFinite(numeric)) {
+      const parsed: Date = new Date(value);
+      return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+
+    return parseEventTime(numeric);
+  }
+
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    // Epoch scale by magnitude: seconds < 1e11 < millis < 1e14 < micros < 1e17 < nanos.
+    let millis: number = value;
+
+    if (value >= 1e17) {
+      millis = value / 1e6;
+    } else if (value >= 1e14) {
+      millis = value / 1e3;
+    } else if (value < 1e11) {
+      millis = value * 1000;
+    }
+
+    const parsed: Date = new Date(Math.trunc(millis));
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+
+  return null;
+}
+
+/*
+ * Build the deduplicated observables array from the entity fields a
+ * normalizer extracted. Order is stable (users, hosts, ips, then extras)
+ * so tests and content hashing are deterministic.
+ */
+export function buildObservables(
+  values: Array<string | undefined>,
+): Array<string> {
+  const seen: Set<string> = new Set<string>();
+  const observables: Array<string> = [];
+
+  for (const value of values) {
+    const trimmed: string = (value || "").trim();
+
+    if (!trimmed) {
+      continue;
+    }
+
+    const canonical: string = trimmed.toLowerCase();
+
+    if (seen.has(canonical)) {
+      continue;
+    }
+
+    seen.add(canonical);
+    observables.push(trimmed);
+  }
+
+  return observables;
+}
+
+/*
+ * Stable content hash used as eventUid when the source payload carries no
+ * id of its own. Repeated deliveries of the same payload produce the same
+ * uid, so downstream consumers can dedupe.
+ */
+export function contentHashEventUid(payload: JSONObject): string {
+  const flattened: JSONObject = flattenPayload(payload);
+  const canonical: string = JSON.stringify(
+    flattened,
+    Object.keys(flattened).sort(),
+  );
+
+  return `sha256:${Crypto.getSha256Hash(canonical)}`;
+}

package/Utils/SecurityEvent/OcsfNormalizer.ts

@@ -0,0 +1,194 @@
+import { JSONObject, JSONValue } from "../../Types/JSON";
+import NormalizedSecurityEvent from "../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity, {
+  OcsfSeverityId,
+  normalizeOcsfSeverity,
+  ocsfSeverityFromId,
+} from "../../Types/SecurityEvent/OcsfSeverity";
+import {
+  OcsfEventClassProps,
+  ocsfCategoryForClassUid,
+  ocsfEventClassByUid,
+} from "../../Types/SecurityEvent/OcsfEventClass";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+  readNumber,
+  readString,
+  readValue,
+} from "./NormalizerHelpers";
+
+/*
+ * Native OCSF event JSON -> NormalizedSecurityEvent.
+ *
+ * OCSF is already our canonical shape, so this normalizer mostly lifts
+ * fields as-is, trusting the payload's class/category/severity ids but
+ * re-deriving names when the payload omits them. Unknown class uids are
+ * kept — the schema evolves faster than our curated subset and dropping
+ * events over an unknown uid would be wrong.
+ *
+ * https://schema.ocsf.io/
+ */
+export default class OcsfNormalizer {
+  public static isOcsfEvent(payload: JSONObject): boolean {
+    return readNumber(payload, "class_uid") !== null;
+  }
+
+  public static normalize(payload: JSONObject): NormalizedSecurityEvent {
+    const classUid: number = readNumber(payload, "class_uid") ?? 0;
+    const knownClass: OcsfEventClassProps | undefined =
+      ocsfEventClassByUid(classUid);
+
+    const className: string =
+      readString(payload, "class_name") ||
+      (knownClass ? knownClass.name : "Base Event");
+
+    const derivedCategory: { categoryUid: number; categoryName: string } =
+      ocsfCategoryForClassUid(classUid);
+
+    const categoryUid: number =
+      readNumber(payload, "category_uid") ?? derivedCategory.categoryUid;
+    const categoryName: string =
+      readString(payload, "category_name") || derivedCategory.categoryName;
+
+    /*
+     * severity_id is authoritative when present; the severity text is a
+     * fallback for producers that only send the name.
+     */
+    const severityIdRaw: number | null = readNumber(payload, "severity_id");
+    const severityName: OcsfSeverity =
+      severityIdRaw !== null
+        ? ocsfSeverityFromId(severityIdRaw)
+        : normalizeOcsfSeverity(readString(payload, "severity")) ||
+          OcsfSeverity.Unknown;
+
+    const time: Date | null = parseEventTime(
+      readValue(payload, "time") ??
+        readValue(payload, "time_dt") ??
+        readValue(payload, "metadata.logged_time"),
+    );
+
+    const mitreTactics: Array<string> = [];
+    const mitreTechniques: Array<string> = [];
+
+    const attacks: JSONValue = readValue(payload, "attacks");
+    if (Array.isArray(attacks)) {
+      for (const attack of attacks) {
+        if (typeof attack !== "object" || attack === null) {
+          continue;
+        }
+
+        const tacticId: string =
+          readString(attack as JSONObject, "tactic.uid") ||
+          readString(attack as JSONObject, "tactic.id");
+        if (tacticId && !mitreTactics.includes(tacticId)) {
+          mitreTactics.push(tacticId);
+        }
+
+        const techniqueId: string =
+          readString(attack as JSONObject, "technique.uid") ||
+          readString(attack as JSONObject, "technique.id");
+        if (techniqueId && !mitreTechniques.includes(techniqueId)) {
+          mitreTechniques.push(techniqueId);
+        }
+      }
+    }
+
+    const principalUser: string =
+      readString(payload, "actor.user.name") ||
+      readString(payload, "actor.user.email_addr");
+
+    const principalProcess: string =
+      readString(payload, "actor.process.name") ||
+      readString(payload, "actor.process.cmd_line");
+
+    const principalHost: string =
+      readString(payload, "src_endpoint.hostname") ||
+      readString(payload, "device.hostname");
+
+    const principalIp: string =
+      readString(payload, "src_endpoint.ip") ||
+      readString(payload, "device.ip");
+
+    const targetUser: string = readString(payload, "user.name");
+    const targetHost: string = readString(payload, "dst_endpoint.hostname");
+    const targetIp: string = readString(payload, "dst_endpoint.ip");
+    const targetPort: number = readNumber(payload, "dst_endpoint.port") ?? 0;
+
+    const targetResource: string =
+      readString(payload, "resources.name") ||
+      readString(payload, "resources.uid") ||
+      readString(payload, "api.operation") ||
+      readString(payload, "http_request.url.hostname");
+
+    /*
+     * OCSF's own observables array carries pre-extracted values; merge
+     * them with the entity fields so the observables column is a superset.
+     */
+    const extraObservables: Array<string> = [];
+    const observablesArray: JSONValue = readValue(payload, "observables");
+    if (Array.isArray(observablesArray)) {
+      for (const observable of observablesArray) {
+        if (typeof observable !== "object" || observable === null) {
+          continue;
+        }
+        const value: string = readString(observable as JSONObject, "value");
+        if (value) {
+          extraObservables.push(value);
+        }
+      }
+    }
+
+    const message: string =
+      readString(payload, "message") ||
+      readString(payload, "finding_info.title") ||
+      className;
+
+    return {
+      time: time || new Date(),
+      eventUid:
+        readString(payload, "metadata.uid") || contentHashEventUid(payload),
+      categoryUid,
+      categoryName,
+      classUid,
+      className,
+      activityName: readString(payload, "activity_name"),
+      severityId: OcsfSeverityId[severityName],
+      severityName,
+      statusName:
+        readString(payload, "status") || readString(payload, "disposition"),
+      message,
+      vendorName: readString(payload, "metadata.product.vendor_name"),
+      productName: readString(payload, "metadata.product.name"),
+      ruleId:
+        readString(payload, "metadata.rule.uid") ||
+        readString(payload, "finding_info.uid"),
+      ruleName:
+        readString(payload, "metadata.rule.name") ||
+        readString(payload, "finding_info.title"),
+      mitreTactics,
+      mitreTechniques,
+      principalUser,
+      principalHost,
+      principalIp,
+      principalProcess,
+      targetUser,
+      targetHost,
+      targetIp,
+      targetPort,
+      targetResource,
+      observables: buildObservables([
+        principalUser,
+        targetUser,
+        principalHost,
+        targetHost,
+        principalIp,
+        targetIp,
+        ...extraObservables,
+      ]),
+      attributes: flattenPayload(payload),
+    };
+  }
+}