@oneuptime/common 13.0.3 → 13.0.5

package/Utils/SecurityEvent/Connectors/CrowdStrikeFalconNormalizer.ts

@@ -0,0 +1,197 @@
+import { JSONObject } from "../../../Types/JSON";
+import NormalizedSecurityEvent from "../../../Types/SecurityEvent/NormalizedSecurityEvent";
+import OcsfSeverity, {
+  OcsfSeverityId,
+  normalizeOcsfSeverity,
+} from "../../../Types/SecurityEvent/OcsfSeverity";
+import { ocsfCategoryForClassUid } from "../../../Types/SecurityEvent/OcsfEventClass";
+import {
+  DETECTION_FINDING_CLASS_NAME,
+  DETECTION_FINDING_CLASS_UID,
+} from "../../../Types/SecurityEvent/DetectionFindingConstants";
+import SecurityEventConnectorProvider from "../../../Types/SecurityEvent/Connectors/SecurityEventConnectorProvider";
+import {
+  SecurityEventConnectorDefinition,
+  getSecurityEventConnectorDefinition,
+} from "../../../Types/SecurityEvent/Connectors/SecurityEventConnectorCatalog";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+  readNumber,
+  readString,
+  readValue,
+} from "../NormalizerHelpers";
+
+/*
+ * CrowdStrike Falcon alert (Alerts API, PostEntitiesAlertsV2 resource)
+ * -> OCSF Detection Finding (class 2004).
+ *
+ * The payload shape is the `resources[]` element of
+ * POST /alerts/entities/alerts/v2 (PostEntitiesAlertsV2 on
+ * https://developer.crowdstrike.com/api-reference/collections/alerts/).
+ * Field names follow the alert entity schema on that page and the sample
+ * event in Elastic's CrowdStrike integration (crowdstrike.alert data
+ * stream, https://www.elastic.co/docs/reference/integrations/crowdstrike):
+ * composite_id, id, display_name/name, description, severity (0-100) +
+ * severity_name, status, tactic/tactic_id, technique/technique_id,
+ * created_timestamp, timestamp, updated_timestamp, product, type,
+ * device.{hostname, local_ip, external_ip, platform_name}, user_name,
+ * user_id, filename, cmdline, sha256, falcon_host_link, pattern_id.
+ *
+ * Pure and isomorphic: only Common/Types and Common/Utils imports, so the
+ * same code is unit-testable without a server and reusable from the UI.
+ */
+
+/*
+ * Vendor/product attribution is read from the catalog rather than retyped:
+ * the poller dedupes on exactly these two values, and a typo here would
+ * silently split one connection's events into two dedupe scopes.
+ */
+const DEFINITION: SecurityEventConnectorDefinition | undefined =
+  getSecurityEventConnectorDefinition(
+    SecurityEventConnectorProvider.CrowdStrikeFalcon,
+  );
+
+const VENDOR_NAME: string = DEFINITION?.vendorName || "CrowdStrike";
+const PRODUCT_NAME: string = DEFINITION?.productName || "Falcon";
+
+/*
+ * Falcon's numeric severity is 0-100 and its severity_name is derived from
+ * it in 20-point bands (the Elastic sample carries severity 30 with
+ * severity_name "low"). severity_name is authoritative when present; the
+ * bands are only the fallback for a payload that carries the number alone.
+ */
+function severityFromNumeric(severity: number | null): OcsfSeverity | null {
+  if (severity === null) {
+    return null;
+  }
+
+  if (severity < 20) {
+    return OcsfSeverity.Informational;
+  }
+
+  if (severity < 40) {
+    return OcsfSeverity.Low;
+  }
+
+  if (severity < 60) {
+    return OcsfSeverity.Medium;
+  }
+
+  if (severity < 80) {
+    return OcsfSeverity.High;
+  }
+
+  return OcsfSeverity.Critical;
+}
+
+export default class CrowdStrikeFalconNormalizer {
+  public static readonly vendorName: string = VENDOR_NAME;
+  public static readonly productName: string = PRODUCT_NAME;
+
+  /*
+   * A Falcon alert always carries composite_id (the Alerts API's primary
+   * key). Older shapes carry `id` plus at least one alert-specific marker;
+   * anything else is not an alert and must be counted as rejected rather
+   * than stored as an empty finding.
+   */
+  public static isRecognized(raw: JSONObject): boolean {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return false;
+    }
+
+    if (readString(raw, "composite_id")) {
+      return true;
+    }
+
+    if (!readString(raw, "id")) {
+      return false;
+    }
+
+    return Boolean(
+      readString(raw, "created_timestamp") ||
+        readString(raw, "severity_name") ||
+        readString(raw, "tactic") ||
+        readString(raw, "pattern_id"),
+    );
+  }
+
+  public static normalize(raw: JSONObject): NormalizedSecurityEvent {
+    const severityName: OcsfSeverity =
+      normalizeOcsfSeverity(readString(raw, "severity_name")) ||
+      severityFromNumeric(readNumber(raw, "severity")) ||
+      OcsfSeverity.Unknown;
+
+    /*
+     * Time is the alert's CREATION time on purpose: the poll window is on
+     * created_timestamp, and a finding row dated by the underlying
+     * activity (`timestamp`) can be hours older than the window that
+     * imported it. The activity time stays queryable in attributes.
+     */
+    const time: Date | null =
+      parseEventTime(readValue(raw, "created_timestamp")) ||
+      parseEventTime(readValue(raw, "timestamp")) ||
+      parseEventTime(readValue(raw, "updated_timestamp"));
+
+    const displayName: string = readString(raw, "display_name");
+    const name: string = readString(raw, "name");
+    const description: string = readString(raw, "description");
+    const ruleName: string = displayName || name;
+
+    const hostname: string = readString(raw, "device.hostname");
+    const localIp: string = readString(raw, "device.local_ip");
+    const externalIp: string = readString(raw, "device.external_ip");
+    const userName: string = readString(raw, "user_name");
+    const filename: string = readString(raw, "filename");
+    const cmdline: string = readString(raw, "cmdline");
+    const sha256: string = readString(raw, "sha256");
+    const tacticId: string = readString(raw, "tactic_id");
+    const techniqueId: string = readString(raw, "technique_id");
+
+    const { categoryUid, categoryName } = ocsfCategoryForClassUid(
+      DETECTION_FINDING_CLASS_UID,
+    );
+
+    return {
+      time: time || new Date(),
+      eventUid:
+        readString(raw, "composite_id") ||
+        readString(raw, "id") ||
+        contentHashEventUid(raw),
+      categoryUid,
+      categoryName,
+      classUid: DETECTION_FINDING_CLASS_UID,
+      className: DETECTION_FINDING_CLASS_NAME,
+      activityName: "Create",
+      severityId: OcsfSeverityId[severityName],
+      severityName,
+      statusName: readString(raw, "status"),
+      message: description || ruleName || "CrowdStrike Falcon alert",
+      vendorName: VENDOR_NAME,
+      productName: PRODUCT_NAME,
+      ruleId: readString(raw, "pattern_id"),
+      ruleName,
+      mitreTactics: tacticId ? [tacticId] : [],
+      mitreTechniques: techniqueId ? [techniqueId] : [],
+      principalUser: userName,
+      principalHost: hostname,
+      principalIp: localIp,
+      principalProcess: filename || cmdline,
+      targetUser: "",
+      targetHost: "",
+      targetIp: "",
+      targetPort: 0,
+      targetResource: "",
+      observables: buildObservables([
+        hostname,
+        localIp,
+        externalIp,
+        userName,
+        sha256,
+      ]),
+      attributes: flattenPayload(raw),
+    };
+  }
+}

package/Utils/SecurityEvent/Connectors/ElasticSecurityNormalizer.ts

@@ -0,0 +1,464 @@
+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 {
+  DETECTION_FINDING_CLASS_NAME,
+  DETECTION_FINDING_CLASS_UID,
+} from "../../../Types/SecurityEvent/DetectionFindingConstants";
+import {
+  SecurityEventConnectorDefinition,
+  getSecurityEventConnectorDefinition,
+} from "../../../Types/SecurityEvent/Connectors/SecurityEventConnectorCatalog";
+import SecurityEventConnectorProvider from "../../../Types/SecurityEvent/Connectors/SecurityEventConnectorProvider";
+import {
+  buildObservables,
+  contentHashEventUid,
+  flattenPayload,
+  parseEventTime,
+} from "../NormalizerHelpers";
+
+/*
+ * Elastic Security detection alert -> OCSF Detection Finding (2004).
+ *
+ * The input is one hit of the Elasticsearch search response that
+ * POST /api/detection_engine/signals/search returns: `{ _id, _index,
+ * _source }`. A bare alert document (the `_source` alone, as a Kibana
+ * connector action or a forwarder would deliver it) is accepted too; it
+ * just has no `_id` to use as the event uid.
+ *
+ * Alert documents carry two field spellings at once and both must be
+ * read. Kibana's rule registry writes its own fields with DOTTED KEYS at
+ * the top level of `_source` (`"kibana.alert.rule.name": "..."`), while
+ * the ECS fields copied from the matched source event arrive as NESTED
+ * objects (`host: { name: "..." }`) or, depending on the shipper, dotted as
+ * well — and a dotted prefix can hold a nested object
+ * (`"kibana.alert.rule.parameters": { threat: [...] }`). Every read below
+ * therefore resolves a path against any mix of the two spellings. Field
+ * names follow the published alert schema:
+ * https://www.elastic.co/guide/en/security/current/alert-schema.html
+ *
+ * Pure and isomorphic: imports only from Common/Types and Common/Utils.
+ */
+
+const ELASTIC_DEFINITION: SecurityEventConnectorDefinition | undefined =
+  getSecurityEventConnectorDefinition(
+    SecurityEventConnectorProvider.ElasticSecurity,
+  );
+
+/*
+ * The vendor/product pair is the dedupe scope in the event store and the
+ * label the dashboard groups by, so it is read from the catalog rather
+ * than retyped here: a rename in one place must not orphan stored rows.
+ */
+export const ELASTIC_SECURITY_VENDOR_NAME: string =
+  ELASTIC_DEFINITION?.vendorName || "Elastic";
+export const ELASTIC_SECURITY_PRODUCT_NAME: string =
+  ELASTIC_DEFINITION?.productName || "Elastic Security";
+
+/*
+ * Rule risk_score bands, matching the severity defaults the rule editor
+ * assigns (low 21, medium 47, high 73, critical 99). Used only when
+ * `kibana.alert.severity` is missing, which happens on alerts written by
+ * older rule types.
+ */
+function severityFromRiskScore(riskScore: number | null): OcsfSeverity | null {
+  if (riskScore === null) {
+    return null;
+  }
+
+  if (riskScore >= 74) {
+    return OcsfSeverity.Critical;
+  }
+
+  if (riskScore >= 48) {
+    return OcsfSeverity.High;
+  }
+
+  if (riskScore >= 22) {
+    return OcsfSeverity.Medium;
+  }
+
+  return OcsfSeverity.Low;
+}
+
+function isJsonObject(
+  value: JSONValue | undefined | null,
+): value is JSONObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function firstObject(value: JSONValue | undefined | null): JSONObject | null {
+  if (isJsonObject(value)) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const found: unknown = (value as Array<unknown>).find(
+      (item: unknown): boolean => {
+        return isJsonObject(item as JSONValue);
+      },
+    );
+
+    return found ? (found as JSONObject) : null;
+  }
+
+  return null;
+}
+
+/*
+ * Resolve a dot path against a document whose keys may be dotted, nested
+ * or any mix of the two. At every level the longest dotted key present
+ * wins, so "kibana.alert.rule.parameters.threat" finds both
+ * `{"kibana.alert.rule.parameters": {threat}}` and `{kibana: {alert: ...}}`.
+ * Arrays along the way contribute their first object (readValue's rule).
+ */
+function resolvePath(
+  payload: JSONObject,
+  segments: Array<string>,
+  start: number,
+): JSONValue | null {
+  for (let length: number = segments.length - start; length >= 1; length--) {
+    const key: string = segments.slice(start, start + length).join(".");
+
+    if (!Object.prototype.hasOwnProperty.call(payload, key)) {
+      continue;
+    }
+
+    const value: JSONValue = payload[key];
+
+    if (value === null || value === undefined) {
+      continue;
+    }
+
+    if (start + length === segments.length) {
+      return value;
+    }
+
+    const child: JSONObject | null = firstObject(value);
+
+    if (child) {
+      const nested: JSONValue | null = resolvePath(
+        child,
+        segments,
+        start + length,
+      );
+
+      if (nested !== null) {
+        return nested;
+      }
+    }
+  }
+
+  return null;
+}
+
+function readField(payload: JSONObject, path: string): JSONValue | null {
+  return resolvePath(payload, path.split("."), 0);
+}
+
+function readFieldString(payload: JSONObject, path: string): string {
+  const value: JSONValue | null = readField(payload, path);
+
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    const first: unknown = (value as Array<unknown>).find(
+      (item: unknown): boolean => {
+        return item !== null && item !== undefined && typeof item !== "object";
+      },
+    );
+    return first === undefined ? "" : String(first);
+  }
+
+  if (typeof value === "object") {
+    return "";
+  }
+
+  return String(value);
+}
+
+function readFieldStrings(payload: JSONObject, path: string): Array<string> {
+  const value: JSONValue | null = readField(payload, path);
+
+  if (value === null || value === undefined) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return (value as Array<unknown>)
+      .filter((item: unknown): boolean => {
+        return item !== null && item !== undefined && typeof item !== "object";
+      })
+      .map((item: unknown): string => {
+        return String(item);
+      });
+  }
+
+  if (typeof value === "object") {
+    return [];
+  }
+
+  return [String(value)];
+}
+
+function readFieldNumber(payload: JSONObject, path: string): number | null {
+  const text: string = readFieldString(payload, path);
+
+  if (text.trim() === "") {
+    return null;
+  }
+
+  const parsed: number = Number(text);
+
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readFieldObjects(
+  payload: JSONObject,
+  path: string,
+): Array<JSONObject> {
+  const value: JSONValue | null = readField(payload, path);
+
+  if (Array.isArray(value)) {
+    return (value as Array<unknown>).filter((item: unknown): boolean => {
+      return isJsonObject(item as JSONValue);
+    }) as Array<JSONObject>;
+  }
+
+  if (isJsonObject(value)) {
+    return [value];
+  }
+
+  return [];
+}
+
+interface MitreReferences {
+  tactics: Array<string>;
+  techniques: Array<string>;
+}
+
+/*
+ * `kibana.alert.rule.threat[]` follows the rule schema's Threat object:
+ * { framework, tactic: { id, name, reference }, technique: [{ id, name,
+ * reference, subtechnique: [{ id, name, reference }] }] }. Only ids are
+ * kept — they are the stable join key across products. Sub-technique ids
+ * (T1078.004) are listed alongside their parent technique.
+ */
+function collectMitre(threats: Array<JSONObject>): MitreReferences {
+  const tactics: Array<string> = [];
+  const techniques: Array<string> = [];
+
+  for (const threat of threats) {
+    const tacticId: string = readFieldString(threat, "tactic.id");
+
+    if (tacticId) {
+      tactics.push(tacticId);
+    }
+
+    for (const technique of readFieldObjects(threat, "technique")) {
+      const techniqueId: string = readFieldString(technique, "id");
+
+      if (techniqueId) {
+        techniques.push(techniqueId);
+      }
+
+      for (const subtechnique of readFieldObjects(technique, "subtechnique")) {
+        const subtechniqueId: string = readFieldString(subtechnique, "id");
+
+        if (subtechniqueId) {
+          techniques.push(subtechniqueId);
+        }
+      }
+    }
+  }
+
+  return {
+    tactics: buildObservables(tactics),
+    techniques: buildObservables(techniques),
+  };
+}
+
+interface AlertParts {
+  id: string;
+  index: string;
+  source: JSONObject;
+}
+
+/*
+ * Accept either a search hit ({ _id, _index, _source }) or a bare alert
+ * document.
+ */
+function splitHit(raw: JSONObject): AlertParts {
+  const source: JSONValue | undefined = raw["_source"];
+
+  if (isJsonObject(source)) {
+    return {
+      id: readFieldString(raw, "_id"),
+      index: readFieldString(raw, "_index"),
+      source: source,
+    };
+  }
+
+  return {
+    id: "",
+    index: readFieldString(raw, "_index"),
+    source: raw,
+  };
+}
+
+export default class ElasticSecurityNormalizer {
+  /*
+   * A document is an Elastic Security alert when it carries the rule
+   * registry's alert fields or is marked event.kind "signal" (which the
+   * alert schema guarantees for every alert document).
+   */
+  public static isRecognized(raw: JSONObject): boolean {
+    if (!isJsonObject(raw)) {
+      return false;
+    }
+
+    const { source } = splitHit(raw);
+
+    return Boolean(
+      readFieldString(source, "kibana.alert.rule.uuid") ||
+        readFieldString(source, "kibana.alert.uuid") ||
+        readFieldString(source, "kibana.alert.rule.name") ||
+        readFieldString(source, "event.kind").toLowerCase() === "signal",
+    );
+  }
+
+  public static normalize(raw: JSONObject): NormalizedSecurityEvent {
+    const { id, index, source } = splitHit(raw);
+
+    const ruleName: string = readFieldString(source, "kibana.alert.rule.name");
+    const ruleId: string =
+      readFieldString(source, "kibana.alert.rule.uuid") ||
+      readFieldString(source, "kibana.alert.rule.rule_id");
+    const description: string = readFieldString(
+      source,
+      "kibana.alert.rule.description",
+    );
+    const reason: string = readFieldString(source, "kibana.alert.reason");
+
+    const severityName: OcsfSeverity =
+      normalizeOcsfSeverity(readFieldString(source, "kibana.alert.severity")) ||
+      severityFromRiskScore(
+        readFieldNumber(source, "kibana.alert.risk_score"),
+      ) ||
+      OcsfSeverity.Unknown;
+
+    /*
+     * Event time is the time of the ACTIVITY the alert describes:
+     * original_time is the matched source event's @timestamp; start is the
+     * alerting framework's first-detected time; the alert's own @timestamp
+     * (rule execution time) is the last resort. The connector pages on
+     * @timestamp separately, so this choice never affects polling.
+     */
+    const time: Date | null =
+      parseEventTime(readField(source, "kibana.alert.original_time")) ||
+      parseEventTime(readField(source, "kibana.alert.start")) ||
+      parseEventTime(readField(source, "@timestamp"));
+
+    const threats: Array<JSONObject> = readFieldObjects(
+      source,
+      "kibana.alert.rule.threat",
+    );
+    const mitre: MitreReferences = collectMitre(
+      threats.length > 0
+        ? threats
+        : readFieldObjects(source, "kibana.alert.rule.parameters.threat"),
+    );
+
+    const hostName: string = readFieldString(source, "host.name");
+    const hostIps: Array<string> = readFieldStrings(source, "host.ip");
+    const userName: string = readFieldString(source, "user.name");
+    const targetUserName: string = readFieldString(source, "user.target.name");
+    const sourceIp: string = readFieldString(source, "source.ip");
+    const destinationIp: string = readFieldString(source, "destination.ip");
+    const destinationDomain: string = readFieldString(
+      source,
+      "destination.domain",
+    );
+    const processName: string =
+      readFieldString(source, "process.name") ||
+      readFieldString(source, "process.executable");
+    const filePath: string = readFieldString(source, "file.path");
+
+    const { categoryUid, categoryName } = ocsfCategoryForClassUid(
+      DETECTION_FINDING_CLASS_UID,
+    );
+
+    const attributes: JSONObject = flattenPayload(source);
+
+    if (index) {
+      attributes["_index"] = index;
+    }
+
+    if (id) {
+      attributes["_id"] = id;
+    }
+
+    return {
+      time: time || new Date(),
+      /*
+       * The search hit's _id is the alert's stable identifier (it equals
+       * kibana.alert.uuid for detection alerts); a bare document falls
+       * back to that field, then to a content hash.
+       */
+      eventUid:
+        id ||
+        readFieldString(source, "kibana.alert.uuid") ||
+        contentHashEventUid(raw),
+      categoryUid,
+      categoryName,
+      classUid: DETECTION_FINDING_CLASS_UID,
+      className: DETECTION_FINDING_CLASS_NAME,
+      activityName: "Create",
+      severityId: OcsfSeverityId[severityName],
+      severityName,
+      statusName: readFieldString(source, "kibana.alert.workflow_status"),
+      message: reason || ruleName || description || "Elastic Security alert",
+      vendorName: ELASTIC_SECURITY_VENDOR_NAME,
+      productName: ELASTIC_SECURITY_PRODUCT_NAME,
+      ruleId,
+      ruleName,
+      mitreTactics: mitre.tactics,
+      mitreTechniques: mitre.techniques,
+      principalUser: userName,
+      principalHost: hostName,
+      principalIp: sourceIp || hostIps[0] || "",
+      principalProcess: processName,
+      targetUser: targetUserName,
+      targetHost: destinationDomain,
+      targetIp: destinationIp,
+      targetPort: readFieldNumber(source, "destination.port") || 0,
+      targetResource: filePath,
+      observables: buildObservables([
+        userName,
+        targetUserName,
+        ...readFieldStrings(source, "related.user"),
+        hostName,
+        ...readFieldStrings(source, "related.hosts"),
+        ...hostIps,
+        sourceIp,
+        destinationIp,
+        ...readFieldStrings(source, "related.ip"),
+        destinationDomain,
+        readFieldString(source, "dns.question.name"),
+        readFieldString(source, "url.domain"),
+        processName,
+        readFieldString(source, "file.hash.sha256"),
+        readFieldString(source, "file.hash.sha1"),
+        readFieldString(source, "file.hash.md5"),
+        ...readFieldStrings(source, "related.hash"),
+      ]),
+      attributes,
+    };
+  }
+}