@oneuptime/common 13.0.7 → 14.0.0

package/Server/Utils/Monitor/MonitorIncident.ts

@@ -99,6 +99,7 @@ export default class MonitorIncident {
       select: {
         _id: true,
         title: true,
+        createdAt: true,
         createdCriteriaId: true,
         createdIncidentTemplateId: true,
         projectId: true,
@@ -579,6 +580,7 @@ export default class MonitorIncident {
               relatedIncidentNumber: alreadyOpenIncident?.incidentNumber,
               relatedIncidentNumberWithPrefix:
                 alreadyOpenIncident?.incidentNumberWithPrefix,
+              relatedIncidentCreatedAt: alreadyOpenIncident?.createdAt,
               at: OneUptimeDate.getCurrentDate(),
             });
             continue;
@@ -913,7 +915,7 @@ export default class MonitorIncident {
             relatedIncidentNumber: createdIncident.incidentNumber,
             relatedIncidentNumberWithPrefix:
               createdIncident.incidentNumberWithPrefix,
-            at: OneUptimeDate.getCurrentDate(),
+            at: createdIncident.createdAt || OneUptimeDate.getCurrentDate(),
           });
         } catch (err) {
           /*

package/Server/Utils/Monitor/MonitoringIntervalValidator.ts

@@ -0,0 +1,116 @@
+import BadDataException from "../../../Types/Exception/BadDataException";
+import MonitoringIntervalUtil, {
+  MonitoringIntervalNormalization,
+  MonitoringIntervalNormalizationStatus,
+} from "../../../Utils/Monitor/MonitoringIntervalUtil";
+import CronTab from "../CronTab";
+
+/*
+ * Server-side policy for `Monitor.monitoringInterval`.
+ *
+ * MonitoringIntervalUtil says what a value MEANS and never throws.
+ * This says what we DO about it on a write: understood values are rewritten
+ * to canonical cron, and genuinely meaningless ones are refused with a
+ * message that names the cron to use instead.
+ *
+ * WHY THE RUNTIME PARSER GETS THE LAST WORD
+ *
+ * The isomorphic normalizer is a hand-rolled grammar; the scheduler runs on
+ * cron-parser. Where the two disagree, cron-parser wins, because it is what
+ * actually computes `nextPingAt`. Validation that rejected an expression the
+ * scheduler would happily honour ("@hourly", exotic step/range forms) would
+ * be this same bug in mirror image: the UI and the runtime disagreeing about
+ * a stored value, with the customer caught in between. So Unrecognized is
+ * re-checked against cron-parser before we refuse anything.
+ */
+
+/*
+ * The shortest cadence the probe fleet can honour.
+ *
+ * `claimMonitorProbesForProbing` is driven by a cron that ticks once a
+ * minute, so a sub-minute schedule is a promise we cannot keep. cron-parser
+ * accepts 6-field per-second expressions such as "* * * * * *" quite
+ * happily; without this floor an API client could ask for a per-second probe
+ * and silently get a per-minute one — the exact class of bug this file
+ * exists to close.
+ */
+export const MINIMUM_MONITORING_INTERVAL_IN_SECONDS: number = 60;
+
+export default class MonitoringIntervalValidator {
+  /**
+   * Validate and canonicalize an inbound monitoring interval.
+   *
+   * Returns the value to persist: null for "no schedule" (legitimate — a
+   * Manual monitor is never probed), otherwise a cron expression the
+   * scheduler can parse. Throws BadDataException when the value cannot be
+   * understood by either the normalizer or cron-parser.
+   */
+  public static validateAndNormalize(
+    value: string | null | undefined,
+  ): string | null {
+    const result: MonitoringIntervalNormalization =
+      MonitoringIntervalUtil.normalize(value);
+
+    if (result.status === MonitoringIntervalNormalizationStatus.Empty) {
+      return null;
+    }
+
+    if (result.cron) {
+      MonitoringIntervalValidator.assertMeetsFloor(result.cron, result.input);
+      return result.cron;
+    }
+
+    /*
+     * Unrecognized by the grammar. Before refusing, ask the parser that
+     * actually schedules the probe — if it can read the expression, the
+     * scheduler can honour it and there is nothing to refuse.
+     */
+    const trimmed: string = (result.input || "").trim();
+    const intervalInSeconds: number | null =
+      CronTab.getIntervalInSeconds(trimmed);
+
+    if (intervalInSeconds !== null) {
+      MonitoringIntervalValidator.assertMeetsFloor(trimmed, result.input);
+      return trimmed;
+    }
+
+    throw new BadDataException(
+      `Invalid Monitoring Interval "${trimmed}". Expected a cron expression - use "${MonitoringIntervalUtil.getSuggestedCronForMessage()}" for every 5 minutes.`,
+    );
+  }
+
+  /*
+   * Applied to every accepted value, normalized or passed through, because
+   * the floor is about what the probe fleet can deliver and not about which
+   * code path produced the expression.
+   */
+  private static assertMeetsFloor(
+    cron: string,
+    input: string | null | undefined,
+  ): void {
+    const intervalInSeconds: number | null = CronTab.getIntervalInSeconds(cron);
+
+    if (
+      intervalInSeconds !== null &&
+      intervalInSeconds < MINIMUM_MONITORING_INTERVAL_IN_SECONDS
+    ) {
+      throw new BadDataException(
+        `Monitoring Interval "${(input || cron).trim()}" is faster than once a minute, which probes cannot deliver. Use "* * * * *" for the fastest supported schedule.`,
+      );
+    }
+  }
+
+  /**
+   * The cron a stored value means, for READ paths.
+   *
+   * Read paths must stay total: a row written before this validator existed
+   * (or restored from a backup, or written through a hook-free path) is not
+   * an exception, it is just a row. Callers fall back to their own default
+   * when this returns null.
+   */
+  public static normalizeForRead(
+    value: string | null | undefined,
+  ): string | null {
+    return MonitoringIntervalUtil.toCronOrNull(value);
+  }
+}

package/Server/Utils/OnCall/OnCallCalendarFeedRenderer.ts

@@ -176,7 +176,7 @@ export interface EmptyOutcomeOptions {
 }
 
 /* The schedule facts every render needs, read once per request. */
-interface ScheduleInfo {
+export interface ScheduleInfo {
   id: ObjectID;
   name: string;
   timezone?: string | undefined;

package/Server/Utils/Realtime.ts

@@ -24,6 +24,19 @@ import Dictionary from "../../Types/Dictionary";
 import UserPermissionUtil from "./UserPermission/UserPermission";
 import CaptureSpan from "./Telemetry/CaptureSpan";
 
+// What became of one ListenToModelEvent request.
+export enum ListenToModelEventOutcome {
+  Joined = "Joined",
+  // No access token, or one that no longer decodes. The client was told.
+  AuthenticationRequired = "AuthenticationRequired",
+  // A valid session without access to this tenant or model.
+  NotAuthorized = "NotAuthorized",
+  // The request itself was malformed.
+  InvalidRequest = "InvalidRequest",
+  // Something failed while authorizing (for example the permission cache).
+  Failed = "Failed",
+}
+
 export default abstract class Realtime {
   private static socketServer: SocketServer | null = null;
 
@@ -45,37 +58,19 @@ export default abstract class Realtime {
       this.socketServer!.on("connection", (socket: Socket) => {
         logger.debug("New socket connection established");
 
-        socket.on(EventName.ListenToModalEvent, async (data: JSONObject) => {
-          logger.debug("Received ListenToModalEvent with data:");
-          logger.debug(data);
-
-          const socketLogAttributes: LogAttributes = {
-            projectId: data["tenantId"]?.toString(),
-          };
-
-          if (typeof data["eventType"] !== "string") {
-            logger.error("eventType is not a string", socketLogAttributes);
-            throw new BadDataException("eventType is not a string");
-          }
-          if (typeof data["modelType"] !== "string") {
-            logger.error("modelType is not a string", socketLogAttributes);
-            throw new BadDataException("modelType is not a string");
-          }
-          if (typeof data["modelName"] !== "string") {
-            logger.error("modelName is not a string", socketLogAttributes);
-            throw new BadDataException("modelName is not a string");
-          }
-          if (typeof data["tenantId"] !== "string") {
-            logger.error("tenantId is not a string", socketLogAttributes);
-            throw new BadDataException("tenantId is not a string");
-          }
-
-          await Realtime.listenToModelEvent(socket, {
-            eventType: data["eventType"] as ModelEventType,
-            modelType: data["modelType"] as DatabaseType,
-            modelName: data["modelName"] as string,
-            tenantId: data["tenantId"] as string,
-          });
+        /*
+         * socket.io calls a listener and throws away what it returns. An async
+         * listener that throws is therefore an unhandled rejection: nothing
+         * goes back to the client, and the subscription it asked for simply
+         * never happens. handleListenToModelEventRequest settles every outcome
+         * itself; the catch is a backstop, not the error handling.
+         */
+        socket.on(EventName.ListenToModalEvent, (data: JSONObject): void => {
+          Realtime.handleListenToModelEventRequest(socket, data).catch(
+            (err: unknown) => {
+              logger.error(err);
+            },
+          );
         });
       });
     }
@@ -83,11 +78,108 @@ export default abstract class Realtime {
     return this.socketServer;
   }
 
+  /*
+   * One ListenToModelEvent from a client, start to finish. Never throws: a
+   * malformed request, a missing or expired access token, a refused
+   * subscription and a failing permission lookup each end here as an outcome,
+   * so none of them can become an unhandled rejection in the socket listener.
+   */
+  @CaptureSpan()
+  public static async handleListenToModelEventRequest(
+    socket: Socket,
+    data: JSONObject,
+  ): Promise<ListenToModelEventOutcome> {
+    logger.debug("Received ListenToModalEvent with data:");
+    logger.debug(data);
+
+    let request: ListenToModelEventJSON;
+
+    try {
+      request = Realtime.parseListenToModelEventRequest(data);
+    } catch (err) {
+      logger.error(err);
+      return ListenToModelEventOutcome.InvalidRequest;
+    }
+
+    try {
+      return await Realtime.listenToModelEvent(socket, request);
+    } catch (err) {
+      // A permission-cache (Redis) failure, say. The room is not joined.
+      const failureLogAttributes: LogAttributes = {
+        projectId: request.tenantId,
+      };
+
+      logger.error(err, failureLogAttributes);
+      return ListenToModelEventOutcome.Failed;
+    }
+  }
+
+  private static parseListenToModelEventRequest(
+    data: JSONObject,
+  ): ListenToModelEventJSON {
+    if (!data || typeof data !== "object") {
+      logger.error("ListenToModelEvent data is not an object");
+      throw new BadDataException("ListenToModelEvent data is not an object");
+    }
+
+    const socketLogAttributes: LogAttributes = {
+      projectId: data["tenantId"]?.toString(),
+    };
+
+    if (typeof data["eventType"] !== "string") {
+      logger.error("eventType is not a string", socketLogAttributes);
+      throw new BadDataException("eventType is not a string");
+    }
+    if (typeof data["modelType"] !== "string") {
+      logger.error("modelType is not a string", socketLogAttributes);
+      throw new BadDataException("modelType is not a string");
+    }
+    if (typeof data["modelName"] !== "string") {
+      logger.error("modelName is not a string", socketLogAttributes);
+      throw new BadDataException("modelName is not a string");
+    }
+    if (typeof data["tenantId"] !== "string") {
+      logger.error("tenantId is not a string", socketLogAttributes);
+      throw new BadDataException("tenantId is not a string");
+    }
+
+    return {
+      eventType: data["eventType"] as ModelEventType,
+      modelType: data["modelType"] as DatabaseType,
+      modelName: data["modelName"] as string,
+      tenantId: data["tenantId"] as string,
+    };
+  }
+
+  /*
+   * The socket has no usable user session: tell the client, which refreshes
+   * its session and reconnects so the new handshake carries the new cookie.
+   * Dropping the request silently is what used to happen, and it left every
+   * subscription made after the access token expired dead (no live counters
+   * after switching project, no live logs) with nothing in the browser to
+   * show why.
+   */
+  private static rejectForMissingAuthentication(
+    socket: Socket,
+    data: ListenToModelEventJSON,
+    reason: string,
+    listenLogAttributes: LogAttributes,
+  ): ListenToModelEventOutcome {
+    logger.debug(
+      `${reason}, aborting joining room and asking the client to re-authenticate`,
+      listenLogAttributes,
+    );
+
+    socket.emit(EventName.AuthenticationRequired, data);
+
+    return ListenToModelEventOutcome.AuthenticationRequired;
+  }
+
   @CaptureSpan()
   public static async listenToModelEvent(
     socket: Socket,
     data: ListenToModelEventJSON,
-  ): Promise<void> {
+  ): Promise<ListenToModelEventOutcome> {
     const listenLogAttributes: LogAttributes = {
       projectId: data.tenantId?.toString(),
     };
@@ -116,31 +208,51 @@ export default abstract class Realtime {
       this.getAccessTokenFromSocket(socket);
 
     if (!userAccessToken) {
-      logger.debug(
-        "User access token not found in socket, aborting joining room",
+      return this.rejectForMissingAuthentication(
+        socket,
+        data,
+        "User access token not found in socket",
         listenLogAttributes,
       );
-      return;
     }
 
     logger.debug("Decoding user access token", listenLogAttributes);
-    const userAuthorizationData: JSONWebTokenData =
-      JSONWebToken.decode(userAccessToken);
+
+    /*
+     * The token is the one the browser sent with the handshake, and it is not
+     * re-read for the life of the connection. Once it expires every decode
+     * throws, which is the normal state of a dashboard tab left open past the
+     * access token's lifetime, not an error in the request.
+     */
+    let userAuthorizationData: JSONWebTokenData;
+
+    try {
+      userAuthorizationData = JSONWebToken.decode(userAccessToken);
+    } catch {
+      return this.rejectForMissingAuthentication(
+        socket,
+        data,
+        "User access token in socket is invalid or expired",
+        listenLogAttributes,
+      );
+    }
 
     if (!userAuthorizationData) {
-      logger.debug(
-        "User authorization data not found in socket, aborting joining room",
+      return this.rejectForMissingAuthentication(
+        socket,
+        data,
+        "User authorization data not found in socket",
         listenLogAttributes,
       );
-      return;
     }
 
     if (!userAuthorizationData.userId) {
-      logger.debug(
-        "User ID not found in socket, aborting joining room",
+      return this.rejectForMissingAuthentication(
+        socket,
+        data,
+        "User ID not found in socket",
         listenLogAttributes,
       );
-      return;
     }
 
     logger.debug("Checking user access permissions", listenLogAttributes);
@@ -179,7 +291,7 @@ export default abstract class Realtime {
           "User does not have access to this tenant, aborting joining room",
           listenLogAttributes,
         );
-        return;
+        return ListenToModelEventOutcome.NotAuthorized;
       }
 
       logger.debug(
@@ -214,12 +326,16 @@ export default abstract class Realtime {
       }
     }
 
+    /*
+     * Authenticated but not allowed. The room is not joined and, as before,
+     * nothing is sent back: a fresh session would not change the answer.
+     */
     if (!hasAccess) {
       logger.debug(
         "User does not have access to this tenant, aborting joining room",
         listenLogAttributes,
       );
-      return;
+      return ListenToModelEventOutcome.NotAuthorized;
     }
 
     if (data.modelId) {
@@ -244,6 +360,8 @@ export default abstract class Realtime {
       // join the room.
       await socket.join(roomId);
     }
+
+    return ListenToModelEventOutcome.Joined;
   }
 
   @CaptureSpan()

package/Server/Utils/SecurityEvent/DetectionRuleEvaluator.ts

@@ -8,13 +8,18 @@ import OcsfSeverity, {
   OcsfSeverityId,
 } from "../../../Types/SecurityEvent/OcsfSeverity";
 import { ocsfCategoryForClassUid } from "../../../Types/SecurityEvent/OcsfEventClass";
-import SigmaRule, { SigmaLevel } from "../../../Types/SecurityEvent/SigmaRule";
+import SigmaRule, {
+  SIGMA_LEVEL_TO_OCSF_SEVERITY,
+  isSevereSigmaLevel,
+} from "../../../Types/SecurityEvent/SigmaRule";
 import {
   DETECTION_DISTINCT_COUNT_ATTRIBUTE,
   DETECTION_FINDING_CLASS_NAME,
   DETECTION_FINDING_CLASS_UID,
   DETECTION_GROUP_VALUE_ATTRIBUTE,
   DETECTION_MATCH_COUNT_ATTRIBUTE,
+  DETECTION_MAX_GROUPS_PER_EVALUATION,
+  DETECTION_MAX_LOOKBACK_IN_MINUTES,
   DETECTION_RULE_ID_ATTRIBUTE,
   DETECTION_RULE_NAME_ATTRIBUTE,
   DETECTION_SIGMA_ID_ATTRIBUTE,
@@ -49,24 +54,6 @@ import { buildSecurityEventDbRow } from "./SecurityEventRow";
 
 const DETECTIONS_SERVICE_NAME: string = "OneUptime Detections";
 
-/*
- * Cap on how far back one evaluation may scan, whatever lastEvaluatedAt
- * says — a rule re-enabled after a month must not trigger a month-long
- * table scan.
- */
-const MAX_LOOKBACK_IN_MINUTES: number = 24 * 60;
-
-// One alert per distinct group value per cycle, at most.
-const MAX_GROUPS_PER_EVALUATION: number = 100;
-
-const SIGMA_LEVEL_TO_OCSF: Record<SigmaLevel, OcsfSeverity> = {
-  [SigmaLevel.Informational]: OcsfSeverity.Informational,
-  [SigmaLevel.Low]: OcsfSeverity.Low,
-  [SigmaLevel.Medium]: OcsfSeverity.Medium,
-  [SigmaLevel.High]: OcsfSeverity.High,
-  [SigmaLevel.Critical]: OcsfSeverity.Critical,
-};
-
 export interface DetectionRuleEvaluationResult {
   ruleId: string;
   matchedGroups: number;
@@ -190,7 +177,7 @@ export default class DetectionRuleEvaluator {
 
     const earliestAllowed: Date = OneUptimeDate.addRemoveMinutes(
       endTime,
-      -MAX_LOOKBACK_IN_MINUTES,
+      -DETECTION_MAX_LOOKBACK_IN_MINUTES,
     );
 
     let startTime: Date = rule.lastEvaluatedAt
@@ -220,7 +207,7 @@ export default class DetectionRuleEvaluator {
         groupByExpression,
         distinctCountExpression,
         minMatchCount: matchCountThreshold,
-        maxGroups: MAX_GROUPS_PER_EVALUATION,
+        maxGroups: DETECTION_MAX_GROUPS_PER_EVALUATION,
       });
 
     /*
@@ -500,7 +487,7 @@ export default class DetectionRuleEvaluator {
     });
 
     const severityName: OcsfSeverity =
-      SIGMA_LEVEL_TO_OCSF[parsedRule.level] || OcsfSeverity.Medium;
+      SIGMA_LEVEL_TO_OCSF_SEVERITY[parsedRule.level] || OcsfSeverity.Medium;
 
     const { categoryUid, categoryName } = ocsfCategoryForClassUid(
       DETECTION_FINDING_CLASS_UID,
@@ -625,7 +612,7 @@ export default class DetectionRuleEvaluator {
       projectId: data.projectId,
       explicitSeverityId: data.rule.alertSeverityId,
       severityLabel: data.parsedRule.level,
-      isSevere: this.isSevereLevel(data.parsedRule.level),
+      isSevere: isSevereSigmaLevel(data.parsedRule.level),
     });
   }
 
@@ -647,11 +634,7 @@ export default class DetectionRuleEvaluator {
       projectId: data.projectId,
       explicitSeverityId: data.rule.incidentSeverityId,
       severityLabel: data.parsedRule.level,
-      isSevere: this.isSevereLevel(data.parsedRule.level),
+      isSevere: isSevereSigmaLevel(data.parsedRule.level),
     });
   }
-
-  private static isSevereLevel(level: SigmaLevel): boolean {
-    return level === SigmaLevel.Critical || level === SigmaLevel.High;
-  }
 }

package/Server/Utils/SecurityEvent/GoogleSecOpsSeverityRepair.ts

@@ -0,0 +1,170 @@
+import OcsfSeverity, {
+  OCSF_SEVERITY_ALIASES,
+  OcsfSeverityId,
+} from "../../../Types/SecurityEvent/OcsfSeverity";
+import {
+  DETECTION_FINDING_CLASS_UID,
+  GOOGLE_SECOPS_PRODUCT_NAME,
+  GOOGLE_SECOPS_RISK_SCORE_BANDS,
+  GOOGLE_SECOPS_VENDOR_NAME,
+} from "../../../Utils/SecurityEvent/GoogleSecOpsAlertNormalizer";
+
+/*
+ * Re-grades Google SecOps detections that were stored as Unknown before the
+ * normalizer learned to read a custom rule's severity.
+ *
+ * Every stored row keeps its source payload flattened into `attributes`
+ * (`detection.0.ruleLabels.2.key` = "severity", `...2.value` = "Medium"), so
+ * the grade the fixed GoogleSecOpsAlertNormalizer would give a row can be
+ * computed in SQL from the row itself. The expression below is that
+ * normalizer's resolveSeverity, written against the flattened keys:
+ *
+ *   1. detection[0].severity   (Google's grade on curated rules)
+ *   2. the Collection's severity
+ *   3. the first ruleLabels "severity" that names a grade (YARA-L meta)
+ *   4. the first outcomes "risk_score" that grades, on Google's bands
+ *
+ * Its text tables are generated from OCSF_SEVERITY_ALIASES and
+ * GOOGLE_SECOPS_RISK_SCORE_BANDS, the same tables the normalizer reads, so
+ * the two cannot drift apart. It reads the list form of ruleLabels and
+ * outcomes Google returns; a label map in a hand-built webhook body is
+ * graded at ingest but not here.
+ *
+ * Only rows that are still Unknown and that the expression grades are
+ * touched, so the repair is idempotent and never overrides a grade.
+ */
+export default class GoogleSecOpsSeverityRepair {
+  /*
+   * The OCSF severity name a stored row's attributes grade to, or '' when
+   * nothing in them grades.
+   */
+  public static gradeExpression(): string {
+    const detectionSeverity: string = `if(attributes['detection.0.severity'] != '', attributes['detection.0.severity'], attributes['detection.severity'])`;
+    const graded: Array<string> = [
+      GoogleSecOpsSeverityRepair.gradeText(detectionSeverity),
+      GoogleSecOpsSeverityRepair.gradeText("attributes['severity']"),
+      GoogleSecOpsSeverityRepair.firstKeyedGrade(
+        "(ruleLabels|rule_labels)",
+        "severity",
+        GoogleSecOpsSeverityRepair.gradeText,
+      ),
+      GoogleSecOpsSeverityRepair.firstKeyedGrade(
+        "outcomes",
+        "risk_score",
+        GoogleSecOpsSeverityRepair.gradeRiskScore,
+      ),
+    ];
+
+    // The first of the four grades that is set, in the normalizer's order.
+    return `arrayFirst(grade -> grade != '', [${graded.join(", ")}])`;
+  }
+
+  /*
+   * The async ON CLUSTER mutation. `storageTable` is the local storage
+   * table and `onCluster` the cluster clause, as every data mutation on
+   * the clustered analytics schema is written.
+   */
+  public static repairStatement(data: {
+    storageTable: string;
+    onCluster: string;
+  }): string {
+    const grade: string = GoogleSecOpsSeverityRepair.gradeExpression();
+    const names: Array<OcsfSeverity> = Object.keys(
+      OcsfSeverityId,
+    ) as Array<OcsfSeverity>;
+    const severityId: string = `transform(${grade}, [${names
+      .map((name: OcsfSeverity): string => {
+        return GoogleSecOpsSeverityRepair.literal(name);
+      })
+      .join(", ")}], [${names
+      .map((name: OcsfSeverity): string => {
+        return String(OcsfSeverityId[name]);
+      })
+      .join(", ")}], ${OcsfSeverityId[OcsfSeverity.Unknown]})`;
+
+    return `ALTER TABLE ${data.storageTable}${data.onCluster} UPDATE severityName = ${grade}, severityId = ${severityId} WHERE ${GoogleSecOpsSeverityRepair.condition()}`;
+  }
+
+  /*
+   * The rows the repair rewrites: Google SecOps detection findings still
+   * stored as Unknown whose attributes now grade. The cheap column checks
+   * come first so ClickHouse evaluates the attribute expression only for
+   * those rows.
+   */
+  public static condition(): string {
+    return [
+      `vendorName = ${GoogleSecOpsSeverityRepair.literal(GOOGLE_SECOPS_VENDOR_NAME)}`,
+      `productName = ${GoogleSecOpsSeverityRepair.literal(GOOGLE_SECOPS_PRODUCT_NAME)}`,
+      `classUid = ${DETECTION_FINDING_CLASS_UID}`,
+      `severityId = ${OcsfSeverityId[OcsfSeverity.Unknown]}`,
+      `${GoogleSecOpsSeverityRepair.gradeExpression()} != ''`,
+    ].join(" AND ");
+  }
+
+  // normalizeOcsfSeverity, minus Unknown: text that names no grade is ''.
+  private static gradeText(expression: string): string {
+    const graded: Array<[string, OcsfSeverity]> = Object.entries(
+      OCSF_SEVERITY_ALIASES,
+    ).filter((entry: [string, OcsfSeverity]): boolean => {
+      return entry[1] !== OcsfSeverity.Unknown;
+    });
+
+    const from: string = graded
+      .map((entry: [string, OcsfSeverity]): string => {
+        return GoogleSecOpsSeverityRepair.literal(entry[0]);
+      })
+      .join(", ");
+    const to: string = graded
+      .map((entry: [string, OcsfSeverity]): string => {
+        return GoogleSecOpsSeverityRepair.literal(entry[1]);
+      })
+      .join(", ");
+
+    return `transform(upperUTF8(${GoogleSecOpsSeverityRepair.trimmed(expression)}), [${from}], [${to}], '')`;
+  }
+
+  /*
+   * The normalizer's gradeRiskScore: a finite score above zero grades into
+   * the first band whose minimum it reaches.
+   */
+  private static gradeRiskScore(expression: string): string {
+    const bands: string = GOOGLE_SECOPS_RISK_SCORE_BANDS.map(
+      (band: { minimum: number; severity: OcsfSeverity }): string => {
+        return `score >= ${band.minimum}, ${GoogleSecOpsSeverityRepair.literal(band.severity)}`;
+      },
+    ).join(", ");
+
+    return `arrayMap(score -> multiIf(NOT isFinite(score) OR score <= 0, '', ${bands}, ''), [ifNull(toFloat64OrNull(${GoogleSecOpsSeverityRepair.trimmed(expression)}), 0)])[1]`;
+  }
+
+  /*
+   * The first grade among the entries of detection[0].<list> whose key is
+   * `key`, in list order: the normalizer's readKeyedValues + firstGrade.
+   * A flattened entry is `detection.0.<list>.<index>.key` / `.value`
+   * (`detection.<list>...` when the webhook sent detection as an object).
+   */
+  private static firstKeyedGrade(
+    listPattern: string,
+    key: string,
+    grade: (expression: string) => string,
+  ): string {
+    const keyPattern: string = `^detection[.](0[.])?${listPattern}[.][0-9]+[.]key$`;
+    const keys: string = `arraySort(entryKey -> toUInt64OrZero(extract(entryKey, '[.]([0-9]+)[.]key$')), arrayFilter(entryKey -> match(entryKey, ${GoogleSecOpsSeverityRepair.literal(keyPattern)}), mapKeys(attributes)))`;
+    const value: string =
+      "attributes[concat(substring(entryKey, 1, length(entryKey) - 3), 'value')]";
+
+    return `arrayFirst(entryGrade -> entryGrade != '', arrayMap(entryKey -> if(lowerUTF8(${GoogleSecOpsSeverityRepair.trimmed("attributes[entryKey]")}) = ${GoogleSecOpsSeverityRepair.literal(key)}, ${grade(value)}, ''), ${keys}))`;
+  }
+
+  /*
+   * JavaScript's String.trim strips all surrounding whitespace; ClickHouse's
+   * trim() strips spaces only.
+   */
+  private static trimmed(expression: string): string {
+    return `replaceRegexpAll(${expression}, '^[[:space:]]+|[[:space:]]+$', '')`;
+  }
+
+  private static literal(value: string): string {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+  }
+}