@oneuptime/common 12.0.15 → 12.0.16

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

@@ -0,0 +1,252 @@
+import { describe, expect, test } from "@jest/globals";
+import { JSONObject } from "../../../Types/JSON";
+import NormalizedSecurityEvent from "../../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity from "../../../Types/SecurityEvent/OcsfSeverity";
+import GoogleSecOpsAlertNormalizer from "../../../Utils/SecurityEvent/GoogleSecOpsAlertNormalizer";
+
+/*
+ * A Chronicle detection alert is only useful in the SIEM if it stays
+ * joinable to the hosts/users it fired on — that linkage comes entirely
+ * from mining the matched UDM sample events in collectionElements into the
+ * observables column and inheriting the first sample's principal/target
+ * columns. Nothing errors if that mining silently stops working; the
+ * finding row just becomes an island. These tests pin the mining, the
+ * Detection Finding (2004) framing, the rule/severity lift from the
+ * `detection` entry, and the MAX_SAMPLE_EVENTS cap that keeps a detection
+ * with hundreds of matches from bloating one row.
+ */
+describe("GoogleSecOpsAlertNormalizer", () => {
+  function buildDetectionPayload(): JSONObject {
+    return {
+      id: "de_12345",
+      type: "RULE_DETECTION",
+      detectionTime: "2024-05-01T12:00:00Z",
+      detection: [
+        {
+          ruleName: "Brute Force Login",
+          ruleId: "ru_abc123",
+          ruleVersionId: "ru_abc123@v1",
+          severity: "HIGH",
+          description: "Multiple failed logins followed by a success",
+          alertState: "ALERTING",
+        },
+      ],
+      collectionElements: [
+        {
+          label: "e",
+          references: [
+            {
+              event: {
+                metadata: { event_type: "USER_LOGIN" },
+                principal: {
+                  user: { userid: "alice" },
+                  hostname: "workstation-1",
+                  ip: ["10.0.0.1"],
+                },
+                target: { hostname: "server-1" },
+              },
+            },
+            {
+              event: {
+                metadata: { event_type: "USER_LOGIN" },
+                principal: { user: { userid: "bob" }, ip: ["10.0.0.2"] },
+              },
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  describe("isGoogleSecOpsAlert", () => {
+    test("detects each of the alert markers", () => {
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert(
+          buildDetectionPayload(),
+        ),
+      ).toBe(true);
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({
+          detection: [{ ruleName: "r" }],
+        }),
+      ).toBe(true);
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({
+          type: "RULE_DETECTION",
+        }),
+      ).toBe(true);
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({
+          collectionElements: [{}],
+        }),
+      ).toBe(true);
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({
+          collection_elements: [{}],
+        }),
+      ).toBe(true);
+    });
+
+    test("rejects unrelated payloads", () => {
+      expect(GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({})).toBe(false);
+      expect(
+        GoogleSecOpsAlertNormalizer.isGoogleSecOpsAlert({
+          message: "hello",
+          type: "audit",
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe("normalize: detection stream payload", () => {
+    const result: NormalizedSecurityEvent =
+      GoogleSecOpsAlertNormalizer.normalize(buildDetectionPayload());
+
+    test("always a Detection Finding (2004) under Findings", () => {
+      expect(result.classUid).toBe(2004);
+      expect(result.className).toBe("Detection Finding");
+      expect(result.categoryUid).toBe(2);
+      expect(result.categoryName).toBe("Findings");
+      expect(result.activityName).toBe("Create");
+    });
+
+    test("rule provenance lifts from the detection entry", () => {
+      expect(result.ruleId).toBe("ru_abc123");
+      expect(result.ruleName).toBe("Brute Force Login");
+    });
+
+    test("detection severity normalizes", () => {
+      expect(result.severityName).toBe(OcsfSeverity.High);
+      expect(result.severityId).toBe(4);
+    });
+
+    test("vendor/product are fixed to Google SecOps", () => {
+      expect(result.vendorName).toBe("Google");
+      expect(result.productName).toBe("Google SecOps");
+    });
+
+    test("time comes from detectionTime, uid from id", () => {
+      expect(result.time.getTime()).toBe(1714564800000);
+      expect(result.eventUid).toBe("de_12345");
+    });
+
+    test("alertState becomes the status, ruleName the message", () => {
+      expect(result.statusName).toBe("ALERTING");
+      expect(result.message).toBe("Brute Force Login");
+    });
+
+    test("observables are the union across sample events", () => {
+      expect(result.observables).toEqual([
+        "alice",
+        "workstation-1",
+        "server-1",
+        "10.0.0.1",
+        "bob",
+        "10.0.0.2",
+      ]);
+    });
+
+    test("principal/target columns inherit from the first sample", () => {
+      expect(result.principalUser).toBe("alice");
+      expect(result.principalHost).toBe("workstation-1");
+      expect(result.principalIp).toBe("10.0.0.1");
+      expect(result.targetHost).toBe("server-1");
+    });
+  });
+
+  describe("normalize: snake_case webhook spelling", () => {
+    const payload: JSONObject = {
+      detection: { rule_name: "Lateral Movement", rule_id: "ru_snake" },
+      detection_time: 1714564800,
+      collection_elements: [
+        {
+          references: [
+            {
+              event: {
+                metadata: { event_type: "NETWORK_CONNECTION" },
+                principal: { hostname: "snake-host" },
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result: NormalizedSecurityEvent =
+      GoogleSecOpsAlertNormalizer.normalize(payload);
+
+    test("detection as a bare object with snake_case fields still lifts", () => {
+      expect(result.ruleName).toBe("Lateral Movement");
+      expect(result.ruleId).toBe("ru_snake");
+      expect(result.time.getTime()).toBe(1714564800000);
+      expect(result.observables).toEqual(["snake-host"]);
+    });
+  });
+
+  describe("normalize: fallbacks", () => {
+    test("severity falls back to the payload level, ruleVersionId backs up ruleId", () => {
+      const result: NormalizedSecurityEvent =
+        GoogleSecOpsAlertNormalizer.normalize({
+          id: "de_2",
+          severity: "MEDIUM",
+          detection: [{ ruleVersionId: "ru_v2@v1" }],
+        });
+
+      expect(result.severityName).toBe(OcsfSeverity.Medium);
+      expect(result.ruleId).toBe("ru_v2@v1");
+    });
+
+    test("without a rule name, message falls back to the description", () => {
+      const result: NormalizedSecurityEvent =
+        GoogleSecOpsAlertNormalizer.normalize({
+          detection: [{ description: "Something suspicious" }],
+        });
+
+      expect(result.message).toBe("Something suspicious");
+    });
+
+    test("without any detection detail, message is the generic label", () => {
+      const result: NormalizedSecurityEvent =
+        GoogleSecOpsAlertNormalizer.normalize({
+          type: "RULE_DETECTION",
+        });
+
+      expect(result.message).toBe("Google SecOps detection");
+      expect(result.severityName).toBe(OcsfSeverity.Unknown);
+      expect(result.eventUid).toMatch(/^sha256:[0-9a-f]{64}$/);
+    });
+  });
+
+  describe("normalize: sample-event mining is capped", () => {
+    test("only the first 25 references contribute observables", () => {
+      const references: Array<JSONObject> = [];
+
+      for (let i: number = 1; i <= 30; i++) {
+        references.push({
+          event: {
+            metadata: { event_type: "USER_LOGIN" },
+            principal: { hostname: `host-${i}` },
+          },
+        });
+      }
+
+      const payload: JSONObject = {
+        id: "de_capped",
+        detection: [{ ruleName: "Noisy Rule", severity: "LOW" }],
+        collectionElements: [{ label: "e", references: references }],
+      };
+
+      const result: NormalizedSecurityEvent =
+        GoogleSecOpsAlertNormalizer.normalize(payload);
+
+      expect(result.observables).toHaveLength(25);
+      expect(result.observables).toContain("host-1");
+      expect(result.observables).toContain("host-25");
+      expect(result.observables).not.toContain("host-26");
+      expect(result.observables).not.toContain("host-30");
+
+      // The first sample still supplies the principal columns.
+      expect(result.principalHost).toBe("host-1");
+    });
+  });
+});

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

@@ -0,0 +1,274 @@
+import { describe, expect, test } from "@jest/globals";
+import { JSONObject } from "../../../Types/JSON";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+  readNumber,
+  readString,
+  readStringArray,
+} from "../../../Utils/SecurityEvent/NormalizerHelpers";
+
+/*
+ * Every normalizer leans on these helpers for the parts that silently
+ * corrupt data when they drift: `attributes` is a Map(String,String)
+ * ClickHouse column so flattening must always produce scalar strings; UDM
+ * nests entities inside arrays so path reads must tolerate arrays mid-path;
+ * timestamps arrive in four different epoch scales and picking the wrong
+ * one puts an event 50,000 years out; and the content-hash eventUid is the
+ * dedupe key for sources that send no id — if it wobbles between deliveries
+ * of the same payload, duplicates multiply. These tests pin each contract.
+ */
+describe("NormalizerHelpers", () => {
+  describe("flattenPayload", () => {
+    test("nested objects become dot-notation keys", () => {
+      const payload: JSONObject = {
+        metadata: { event_type: "USER_LOGIN", nested: { deep: "value" } },
+      };
+
+      expect(flattenPayload(payload)).toEqual({
+        "metadata.event_type": "USER_LOGIN",
+        "metadata.nested.deep": "value",
+      });
+    });
+
+    test("scalar arrays collapse to a comma-joined string", () => {
+      const payload: JSONObject = {
+        ip: ["10.0.0.1", "10.0.0.2"],
+        ports: [80, 443],
+      };
+
+      expect(flattenPayload(payload)).toEqual({
+        ip: "10.0.0.1,10.0.0.2",
+        ports: "80,443",
+      });
+    });
+
+    test("arrays of objects recurse with the index in the key", () => {
+      const payload: JSONObject = {
+        security_result: [{ severity: "LOW" }, { severity: "HIGH" }],
+      };
+
+      expect(flattenPayload(payload)).toEqual({
+        "security_result.0.severity": "LOW",
+        "security_result.1.severity": "HIGH",
+      });
+    });
+
+    test("mixed arrays recurse per element", () => {
+      const payload: JSONObject = { mixed: ["scalar", { key: "value" }] };
+
+      expect(flattenPayload(payload)).toEqual({
+        "mixed.0": "scalar",
+        "mixed.1.key": "value",
+      });
+    });
+
+    test("objects past the depth cap fall back to JSON.stringify", () => {
+      const payload: JSONObject = { a: { b: { c: "d" } } };
+
+      expect(flattenPayload(payload, 2)).toEqual({
+        "a.b": JSON.stringify({ c: "d" }),
+      });
+    });
+
+    test("null, undefined, empty arrays and empty objects emit nothing", () => {
+      const payload: JSONObject = {
+        gone: null,
+        missing: undefined,
+        emptyList: [],
+        emptyObject: {},
+        kept: "value",
+      };
+
+      expect(flattenPayload(payload)).toEqual({ kept: "value" });
+    });
+
+    test("scalars stringify", () => {
+      const payload: JSONObject = { count: 42, active: true, label: "x" };
+
+      expect(flattenPayload(payload)).toEqual({
+        count: "42",
+        active: "true",
+        label: "x",
+      });
+    });
+  });
+
+  describe("readString", () => {
+    test("reads a nested scalar by dot path", () => {
+      const payload: JSONObject = { metadata: { id: "evt-1" } };
+
+      expect(readString(payload, "metadata.id")).toBe("evt-1");
+    });
+
+    test("arrays along the path take the first element", () => {
+      const payload: JSONObject = {
+        security_result: [{ severity: "LOW" }, { severity: "HIGH" }],
+      };
+
+      expect(readString(payload, "security_result.severity")).toBe("LOW");
+    });
+
+    test("an array value returns its first scalar", () => {
+      const payload: JSONObject = { ip: ["10.0.0.1", "10.0.0.2"] };
+
+      expect(readString(payload, "ip")).toBe("10.0.0.1");
+    });
+
+    test("missing path, object value and null all read as empty string", () => {
+      const payload: JSONObject = {
+        metadata: { nested: { x: "y" } },
+        gone: null,
+      };
+
+      expect(readString(payload, "does.not.exist")).toBe("");
+      expect(readString(payload, "metadata.nested")).toBe("");
+      expect(readString(payload, "gone")).toBe("");
+    });
+
+    test("numbers stringify", () => {
+      const payload: JSONObject = { target: { port: 443 } };
+
+      expect(readString(payload, "target.port")).toBe("443");
+    });
+  });
+
+  describe("readNumber", () => {
+    test("reads numbers and numeric strings", () => {
+      const payload: JSONObject = { a: 42, b: "42", c: "4.5" };
+
+      expect(readNumber(payload, "a")).toBe(42);
+      expect(readNumber(payload, "b")).toBe(42);
+      expect(readNumber(payload, "c")).toBe(4.5);
+    });
+
+    test("missing paths and non-numeric values -> null", () => {
+      const payload: JSONObject = { a: "abc", b: "", c: true };
+
+      expect(readNumber(payload, "a")).toBeNull();
+      expect(readNumber(payload, "b")).toBeNull();
+      expect(readNumber(payload, "c")).toBeNull();
+      expect(readNumber(payload, "missing")).toBeNull();
+    });
+  });
+
+  describe("readStringArray", () => {
+    test("keeps scalars, drops objects and nulls, stringifies the rest", () => {
+      const payload: JSONObject = { list: ["x", 1, null, { o: 1 }, true] };
+
+      expect(readStringArray(payload, "list")).toEqual(["x", "1", "true"]);
+    });
+
+    test("a lone scalar wraps into a one-element array", () => {
+      const payload: JSONObject = { host: "web-1" };
+
+      expect(readStringArray(payload, "host")).toEqual(["web-1"]);
+    });
+
+    test("arrays along the path take the first element", () => {
+      const payload: JSONObject = { a: [{ b: ["x", "y"] }, { b: ["z"] }] };
+
+      expect(readStringArray(payload, "a.b")).toEqual(["x", "y"]);
+    });
+
+    test("missing path -> empty array", () => {
+      expect(readStringArray({}, "nope")).toEqual([]);
+    });
+  });
+
+  describe("parseEventTime", () => {
+    // 2024-05-01T12:00:00Z in every scale the dialects use.
+    const expectedMillis: number = 1714564800000;
+
+    test("RFC3339 string", () => {
+      expect(parseEventTime("2024-05-01T12:00:00Z")?.getTime()).toBe(
+        expectedMillis,
+      );
+    });
+
+    test("epoch seconds", () => {
+      expect(parseEventTime(1714564800)?.getTime()).toBe(expectedMillis);
+    });
+
+    test("epoch millis", () => {
+      expect(parseEventTime(1714564800000)?.getTime()).toBe(expectedMillis);
+    });
+
+    test("epoch micros", () => {
+      expect(parseEventTime(1714564800000000)?.getTime()).toBe(expectedMillis);
+    });
+
+    test("epoch nanos", () => {
+      expect(parseEventTime(1714564800000000000)?.getTime()).toBe(
+        expectedMillis,
+      );
+    });
+
+    test("numeric string routes through the epoch-scale logic", () => {
+      expect(parseEventTime("1714564800")?.getTime()).toBe(expectedMillis);
+    });
+
+    test.each<[string]>([["garbage"], ["not a date"]])(
+      "garbage string %s -> null",
+      (input: string) => {
+        expect(parseEventTime(input)).toBeNull();
+      },
+    );
+
+    test("null, empty, zero and negative values -> null", () => {
+      expect(parseEventTime(null)).toBeNull();
+      expect(parseEventTime(undefined)).toBeNull();
+      expect(parseEventTime("")).toBeNull();
+      expect(parseEventTime("   ")).toBeNull();
+      expect(parseEventTime(0)).toBeNull();
+      expect(parseEventTime(-1714564800)).toBeNull();
+    });
+  });
+
+  describe("buildObservables", () => {
+    test("dedupes case-insensitively but keeps the first casing", () => {
+      expect(buildObservables(["Alice", "alice", "ALICE", "bob"])).toEqual([
+        "Alice",
+        "bob",
+      ]);
+    });
+
+    test("drops empties and trims whitespace", () => {
+      expect(
+        buildObservables(["", "  ", undefined, " host-1 ", "10.0.0.1"]),
+      ).toEqual(["host-1", "10.0.0.1"]);
+    });
+
+    test("preserves input order", () => {
+      expect(buildObservables(["b", "a", "c", "a"])).toEqual(["b", "a", "c"]);
+    });
+  });
+
+  describe("contentHashEventUid", () => {
+    test("same payload -> same uid with the sha256: prefix", () => {
+      const payload: JSONObject = { metadata: { event_type: "USER_LOGIN" } };
+
+      const first: string = contentHashEventUid(payload);
+      const second: string = contentHashEventUid({
+        metadata: { event_type: "USER_LOGIN" },
+      });
+
+      expect(first).toBe(second);
+      expect(first).toMatch(/^sha256:[0-9a-f]{64}$/);
+    });
+
+    test("key order does not change the uid", () => {
+      expect(contentHashEventUid({ a: "1", b: "2" })).toBe(
+        contentHashEventUid({ b: "2", a: "1" }),
+      );
+    });
+
+    test("different payloads -> different uids", () => {
+      expect(contentHashEventUid({ a: "1" })).not.toBe(
+        contentHashEventUid({ a: "2" }),
+      );
+    });
+  });
+});