@oneuptime/common 12.0.15 → 12.0.16

package/Types/Marketing/Attribution.ts

@@ -0,0 +1,75 @@
+/*
+ * The visitor-attribution wire contract, shared by every place that reads or
+ * writes it.
+ *
+ * Attribution starts in the browser (Home/Views/head-basic.ejs stores it in
+ * localStorage) and reaches the server through two unrelated doors:
+ *
+ *   - the signup form (App/FeatureSet/Accounts/src/Pages/Register.tsx), which
+ *     posts it onto the User record;
+ *   - the Cal.com booking webhook (App/API/CalWebhook.ts), which reads it back
+ *     out of the booking metadata the embed carried. Every page that books —
+ *     /enterprise/demo, /support, /enterprise/self-hosted — goes through it.
+ *
+ * Both doors are reachable by an unauthenticated caller, so both must whitelist
+ * and length-bound what they accept. Keeping the key lists here rather than in
+ * each door means a key added for the browser cannot be silently dropped by one
+ * of the readers — which is exactly what happened to UTM parameters on the Cal
+ * path, where the webhook parsed click IDs the embed never sent.
+ */
+
+// Ad-platform click identifiers, in the spelling each platform uses on the URL.
+export const AdClickIdKeys: Array<string> = [
+  "gclid",
+  "wbraid",
+  "gbraid",
+  "fbclid",
+  "msclkid",
+  "li_fat_id",
+  "twclid",
+  "rdt_cid",
+];
+
+/*
+ * UTM parameters travel as snake_case on a URL and in Cal booking metadata,
+ * and as camelCase once they are columns on User/Project/MarketingConversion.
+ * Both spellings are accepted on the way in — Cal booking questions and hand
+ * written links produce either — and only the camelCase form is stored.
+ */
+export const UtmWireKeyToPropertyKey: Record<string, string> = {
+  utm_source: "utmSource",
+  utm_medium: "utmMedium",
+  utm_campaign: "utmCampaign",
+  utm_term: "utmTerm",
+  utm_content: "utmContent",
+};
+
+export const UtmPropertyKeys: Array<string> = Object.values(
+  UtmWireKeyToPropertyKey,
+);
+
+/*
+ * The landing URL of the attributed visit. Stored separately from the UTM
+ * values because it is the only field that survives a campaign whose link
+ * carried no UTMs at all (Google Ads auto-tagging sends gclid and nothing
+ * else).
+ */
+export const UtmUrlPropertyKey: string = "utmUrl";
+
+/*
+ * The shape the marketing site writes to localStorage under `firstTouch` and
+ * never overwrites. `clickIds` is nested inside it and handled separately.
+ */
+export const FirstTouchStringKeys: Array<string> = [
+  ...UtmPropertyKeys,
+  "landingUrl",
+  "referrer",
+  "timestamp",
+];
+
+/*
+ * Every attribution value is bounded to this before it is persisted. The utm*
+ * columns are LongText, so the bound is not the column width — it is a cap on
+ * what an unauthenticated caller can push into the row.
+ */
+export const MaxAttributionValueLength: number = 500;

package/Types/Marketing/MarketingConversion.ts

@@ -6,18 +6,48 @@ export enum MarketingConversionType {
 }
 
 /*
- * Conversion types that ad platforms have an explicit conversion-action
- * mapping for. Every provider picks its platform conversion action by
- * branching on SignUp vs not-SignUp, so a type that is not listed here would
- * be uploaded as a purchase — add a type only once every provider has a
- * mapping for it. Types left out stay ledger-only and are recorded as Skipped.
+ * Conversion types ad platforms may be told about.
+ *
+ * This list used to hold only SignUp and PaidSubscription because every
+ * provider chose its platform conversion action with a two-way branch on
+ * isSignUp(), so any third type would have been uploaded as a *purchase*
+ * carrying whatever value the row held. That branch is gone: providers now
+ * declare a Record<MarketingConversionType, ...> mapping, which the compiler
+ * refuses to accept unless every member of the enum above is named. Adding a
+ * conversion type is therefore a type error in each provider until that
+ * provider says what the type means on its platform.
+ *
+ * A mapping may legitimately be an empty string, meaning "this deployment has
+ * not configured a conversion action for this type yet". That is a config gap,
+ * not a modelling gap: the worker leaves such rows pending rather than
+ * skipping them, so they upload once the id is set.
  */
 export const AdUploadableMarketingConversionTypes: Array<MarketingConversionType> =
-  [MarketingConversionType.SignUp, MarketingConversionType.PaidSubscription];
+  [
+    MarketingConversionType.SignUp,
+    MarketingConversionType.MeetingBooked,
+    MarketingConversionType.PaidSubscription,
+  ];
+
+/*
+ * Types that represent a sales-led lead rather than a completed self-serve
+ * transaction. They carry no revenue of their own — a booked meeting is not
+ * money — so providers must not attach a conversion value to them even when
+ * the row happens to have one, and platforms that demand a value for their
+ * purchase-shaped events must not be handed these as purchases.
+ *
+ * Every sales-led step is a booked meeting. The enterprise licence request is
+ * not a separate type: asking about a licence and booking an architecture
+ * assessment are the same conversation, reached through the same Cal embed, so
+ * they are the same conversion.
+ */
+export const LeadMarketingConversionTypes: Array<MarketingConversionType> = [
+  MarketingConversionType.MeetingBooked,
+];
 
 export enum MarketingConversionUploadStatus {
   Uploaded = "Uploaded",
   Failed = "Failed",
-  // No click id relevant to this ad platform — nothing to upload.
+  // No identifier relevant to this ad platform — nothing to upload.
   Skipped = "Skipped",
 }

package/Types/Measurement/MeasurementAggregationType.ts

@@ -0,0 +1,43 @@
+import AggregationType from "../BaseDatabase/AggregationType";
+
+/*
+ * The aggregation a measurement's chart should default to.
+ *
+ * Kept as a narrow subset of AggregationType: summing durations across
+ * incidents produces a number with no meaning, so Sum is deliberately absent.
+ */
+enum MeasurementAggregationType {
+  Avg = "Avg",
+  Max = "Max",
+  Min = "Min",
+  P50 = "P50",
+  P90 = "P90",
+  P95 = "P95",
+  P99 = "P99",
+}
+
+export class MeasurementAggregationTypeUtil {
+  public static toAggregationType(
+    type: MeasurementAggregationType | undefined,
+  ): AggregationType {
+    switch (type) {
+      case MeasurementAggregationType.Max:
+        return AggregationType.Max;
+      case MeasurementAggregationType.Min:
+        return AggregationType.Min;
+      case MeasurementAggregationType.P50:
+        return AggregationType.P50;
+      case MeasurementAggregationType.P90:
+        return AggregationType.P90;
+      case MeasurementAggregationType.P95:
+        return AggregationType.P95;
+      case MeasurementAggregationType.P99:
+        return AggregationType.P99;
+      case MeasurementAggregationType.Avg:
+      default:
+        return AggregationType.Avg;
+    }
+  }
+}
+
+export default MeasurementAggregationType;

package/Types/Measurement/MeasurementAnchorKind.ts

@@ -0,0 +1,23 @@
+/*
+ * The three ways a measurement endpoint can be located in time.
+ *
+ * Domain services translate their own anchor-type enum into one of these
+ * before handing the definition to MeasurementEvaluator, which is what lets
+ * one evaluator serve incidents, alerts and scheduled maintenance events.
+ */
+enum MeasurementAnchorKind {
+  // A timestamp column on the entity itself, already resolved by the caller.
+  Timestamp = "Timestamp",
+
+  // The moment a specific state was entered, located by state id.
+  StateEntered = "State Entered",
+
+  /*
+   * The moment a state carrying a given role was entered -- "whichever state
+   * is the acknowledged one". Resolves by flag rather than pinning an id, so
+   * it keeps working when a project renames or replaces the state.
+   */
+  StateRoleEntered = "State Role Entered",
+}
+
+export default MeasurementAnchorKind;

package/Types/Measurement/MeasurementOccurrence.ts

@@ -0,0 +1,14 @@
+/*
+ * Which entry to use when a state is entered more than once -- the reopen knob.
+ *
+ * `First` reproduces the behaviour of the built-in metrics, which resolve a
+ * state with `.find()` over a timeline sorted ascending. `Last` is the opt-in
+ * selector for teams who want a reopened incident's measurement to move to the
+ * final resolution rather than pinning to the first one.
+ */
+enum MeasurementOccurrence {
+  First = "First",
+  Last = "Last",
+}
+
+export default MeasurementOccurrence;

package/Types/Measurement/MeasurementStatus.ts

@@ -0,0 +1,34 @@
+/*
+ * The outcome of evaluating a measurement definition against one entity.
+ *
+ * A measurement is a named duration between two anchors. Every one of these
+ * values is a deliberate alternative to writing a number that looks plausible
+ * and is wrong -- which is the failure mode this feature exists to remove.
+ */
+enum MeasurementStatus {
+  // Both anchors resolved and the duration is meaningful.
+  Recorded = "Recorded",
+
+  /*
+   * An anchor has not happened yet but still can. The entity is mid-flight.
+   * This is the only status that is expected to change on its own.
+   */
+  Pending = "Pending",
+
+  /*
+   * An anchor can never resolve for this entity -- the state was skipped, the
+   * timestamp was never recorded, or the referenced state has been deleted.
+   * No metric point is written, so a skipped milestone does not pull an
+   * average towards zero.
+   */
+  NotApplicable = "Not Applicable",
+
+  /*
+   * Both anchors resolved but the end precedes the start. This is the "field
+   * whose value looks wrong" -- it means someone's recorded timestamps
+   * disagree with each other, and it is surfaced rather than clamped to zero.
+   */
+  Invalid = "Invalid",
+}
+
+export default MeasurementStatus;

package/Types/MeteredPlan/ProductType.ts

@@ -4,6 +4,7 @@ enum ProductType {
   Metrics = "Metrics",
   Profiles = "Profiles",
   SessionReplay = "Session Replay",
+  SecurityEvents = "Security Events",
   ActiveMonitoring = "Active Monitoring",
 }
 

package/Types/Monitor/CriteriaFilter.ts

@@ -49,6 +49,9 @@ export enum CheckOn {
   // Log monitors.
   LogCount = "Log Count",
 
+  // Security event monitors.
+  SecurityEventCount = "Security Event Count",
+
   // Trace monitors.
   SpanCount = "Span Count",
 

package/Types/Monitor/MonitorCriteriaInstance.ts

@@ -145,6 +145,39 @@ export default class MonitorCriteriaInstance extends DatabaseProperty {
       return monitorCriteriaInstance;
     }
 
+    if (arg.monitorType === MonitorType.SecurityEvents) {
+      const monitorCriteriaInstance: MonitorCriteriaInstance =
+        new MonitorCriteriaInstance();
+
+      /*
+       * Inverse of the Logs default on purpose: silence is the healthy
+       * state for a security-events monitor. Zero matching events means
+       * all clear; matches are what the offline/alerting criteria fires
+       * on.
+       */
+      monitorCriteriaInstance.data = {
+        id: ObjectID.generate().toString(),
+        monitorStatusId: arg.monitorStatusId,
+        filterCondition: FilterCondition.Any,
+        filters: [
+          {
+            checkOn: CheckOn.SecurityEventCount,
+            filterType: FilterType.EqualTo,
+            value: 0, // no matching security events - all clear.
+          },
+        ],
+        incidents: [],
+        alerts: [],
+        changeMonitorStatus: true,
+        createIncidents: false,
+        createAlerts: false,
+        name: `Check if ${arg.monitorName} is clear`,
+        description: `This criteria checks that ${arg.monitorName} has no matching security events`,
+      };
+
+      return monitorCriteriaInstance;
+    }
+
     if (arg.monitorType === MonitorType.Logs) {
       const monitorCriteriaInstance: MonitorCriteriaInstance =
         new MonitorCriteriaInstance();
@@ -986,6 +1019,37 @@ export default class MonitorCriteriaInstance extends DatabaseProperty {
       };
     }
 
+    if (arg.monitorType === MonitorType.SecurityEvents) {
+      monitorCriteriaInstance.data = {
+        id: ObjectID.generate().toString(),
+        monitorStatusId: arg.monitorStatusId,
+        filterCondition: FilterCondition.Any,
+        filters: [
+          {
+            checkOn: CheckOn.SecurityEventCount,
+            filterType: FilterType.GreaterThan,
+            value: 0, // matching security events were found.
+          },
+        ],
+        incidents: [],
+        alerts: [
+          {
+            title: `${arg.monitorName} detected security events`,
+            description: `${arg.monitorName} found matching security events.`,
+            alertSeverityId: arg.alertSeverityId,
+            autoResolveAlert: true,
+            id: ObjectID.generate().toString(),
+            onCallPolicyIds: [],
+          },
+        ],
+        createAlerts: true,
+        changeMonitorStatus: true,
+        createIncidents: false,
+        name: `Check if ${arg.monitorName} found security events`,
+        description: `This criteria fires when ${arg.monitorName} finds matching security events`,
+      };
+    }
+
     if (arg.monitorType === MonitorType.Logs) {
       monitorCriteriaInstance.data = {
         id: ObjectID.generate().toString(),

package/Types/Monitor/MonitorStep.ts

@@ -13,6 +13,9 @@ import MonitorCriteria from "./MonitorCriteria";
 import MonitorStepLogMonitor, {
   MonitorStepLogMonitorUtil,
 } from "./MonitorStepLogMonitor";
+import MonitorStepSecurityEventsMonitor, {
+  MonitorStepSecurityEventsMonitorUtil,
+} from "./MonitorStepSecurityEventsMonitor";
 import MonitorType from "./MonitorType";
 import BrowserType from "./SyntheticMonitors//BrowserType";
 import ScreenSizeType from "./SyntheticMonitors/ScreenSizeType";
@@ -163,6 +166,9 @@ export interface MonitorStepType {
   // Log monitor type.
   logMonitor?: MonitorStepLogMonitor | undefined;
 
+  // Security events monitor type.
+  securityEventsMonitor?: MonitorStepSecurityEventsMonitor | undefined;
+
   // trace monitor type.
   traceMonitor?: MonitorStepTraceMonitor | undefined;
 
@@ -251,6 +257,7 @@ export default class MonitorStep extends DatabaseProperty {
       requestTimeoutInMs: undefined,
       retryCount: undefined,
       logMonitor: undefined,
+      securityEventsMonitor: undefined,
       traceMonitor: undefined,
       metricMonitor: undefined,
       exceptionMonitor: undefined,
@@ -314,6 +321,10 @@ export default class MonitorStep extends DatabaseProperty {
         arg.monitorType === MonitorType.Logs
           ? MonitorStepLogMonitorUtil.getDefault()
           : undefined,
+      securityEventsMonitor:
+        arg.monitorType === MonitorType.SecurityEvents
+          ? MonitorStepSecurityEventsMonitorUtil.getDefault()
+          : undefined,
       traceMonitor:
         arg.monitorType === MonitorType.Traces
           ? MonitorStepTraceMonitorUtil.getDefault()
@@ -491,6 +502,13 @@ export default class MonitorStep extends DatabaseProperty {
     return this;
   }
 
+  public setSecurityEventsMonitor(
+    securityEventsMonitor: MonitorStepSecurityEventsMonitor,
+  ): MonitorStep {
+    this.data!.securityEventsMonitor = securityEventsMonitor;
+    return this;
+  }
+
   public setMetricMonitor(
     metricMonitor: MonitorStepMetricMonitor,
   ): MonitorStep {
@@ -643,6 +661,7 @@ export default class MonitorStep extends DatabaseProperty {
         requestTimeoutInMs: undefined,
         retryCount: undefined,
         logMonitor: undefined,
+        securityEventsMonitor: undefined,
         exceptionMonitor: undefined,
         kubernetesMonitor: undefined,
         dockerMonitor: undefined,
@@ -935,6 +954,11 @@ export default class MonitorStep extends DatabaseProperty {
                 this.data.logMonitor || MonitorStepLogMonitorUtil.getDefault(),
               )
             : undefined,
+          securityEventsMonitor: this.data.securityEventsMonitor
+            ? MonitorStepSecurityEventsMonitorUtil.toJSON(
+                this.data.securityEventsMonitor,
+              )
+            : undefined,
           metricMonitor: this.data.metricMonitor
             ? MonitorStepMetricMonitorUtil.toJSON(this.data.metricMonitor)
             : undefined,
@@ -1114,6 +1138,9 @@ export default class MonitorStep extends DatabaseProperty {
       logMonitor: json["logMonitor"]
         ? (json["logMonitor"] as JSONObject)
         : undefined,
+      securityEventsMonitor: json["securityEventsMonitor"]
+        ? (json["securityEventsMonitor"] as JSONObject)
+        : undefined,
       /*
        * Normalize rather than pass the raw JSON straight through. Steps saved
        * by older builds can carry a metricMonitor with no metricViewConfig,
@@ -1229,6 +1256,7 @@ export default class MonitorStep extends DatabaseProperty {
         requestTimeoutInMs: Zod.number().optional(),
         retryCount: Zod.number().optional(),
         logMonitor: Zod.any().optional(),
+        securityEventsMonitor: Zod.any().optional(),
         traceMonitor: Zod.any().optional(),
         metricMonitor: Zod.any().optional(),
         profileMonitor: Zod.any().optional(),

package/Types/Monitor/MonitorStepSecurityEventsMonitor.ts

@@ -0,0 +1,100 @@
+import SecurityEvent from "../../Models/AnalyticsModels/SecurityEvent";
+import InBetween from "../BaseDatabase/InBetween";
+import Includes from "../BaseDatabase/Includes";
+import Query from "../BaseDatabase/Query";
+import Search from "../BaseDatabase/Search";
+import OneUptimeDate from "../Date";
+import Dictionary from "../Dictionary";
+import { JSONObject } from "../JSON";
+import ObjectID from "../ObjectID";
+import OcsfSeverity from "../SecurityEvent/OcsfSeverity";
+
+export default interface MonitorStepSecurityEventsMonitor {
+  attributes: Dictionary<string | number | boolean>;
+  messageContains: string;
+  severityNames: Array<OcsfSeverity>;
+  classNames: Array<string>;
+  telemetryServiceIds: Array<ObjectID>;
+  lastXSecondsOfEvents: number;
+}
+
+export class MonitorStepSecurityEventsMonitorUtil {
+  public static toQuery(
+    monitorStep: MonitorStepSecurityEventsMonitor,
+  ): Query<SecurityEvent> {
+    const query: Query<SecurityEvent> = {};
+
+    if (
+      monitorStep.telemetryServiceIds &&
+      monitorStep.telemetryServiceIds.length > 0
+    ) {
+      query.primaryEntityId = new Includes(monitorStep.telemetryServiceIds);
+    }
+
+    if (
+      monitorStep.attributes &&
+      Object.keys(monitorStep.attributes).length > 0
+    ) {
+      query.attributes = monitorStep.attributes;
+    }
+
+    if (monitorStep.severityNames && monitorStep.severityNames.length > 0) {
+      query.severityName = new Includes(monitorStep.severityNames);
+    }
+
+    if (monitorStep.classNames && monitorStep.classNames.length > 0) {
+      query.className = new Includes(monitorStep.classNames);
+    }
+
+    if (monitorStep.messageContains) {
+      query.message = new Search(monitorStep.messageContains);
+    }
+
+    if (monitorStep.lastXSecondsOfEvents) {
+      const endDate: Date = OneUptimeDate.getCurrentDate();
+      const startDate: Date = OneUptimeDate.addRemoveSeconds(
+        endDate,
+        monitorStep.lastXSecondsOfEvents * -1,
+      );
+      query.time = new InBetween(startDate, endDate);
+    }
+
+    return query;
+  }
+
+  public static getDefault(): MonitorStepSecurityEventsMonitor {
+    return {
+      attributes: {},
+      messageContains: "",
+      severityNames: [],
+      classNames: [],
+      telemetryServiceIds: [],
+      lastXSecondsOfEvents: 60,
+    };
+  }
+
+  public static fromJSON(json: JSONObject): MonitorStepSecurityEventsMonitor {
+    return {
+      attributes:
+        (json["attributes"] as Dictionary<string | number | boolean>) || {},
+      messageContains: (json["messageContains"] as string) || "",
+      severityNames: (json["severityNames"] as Array<OcsfSeverity>) || [],
+      classNames: (json["classNames"] as Array<string>) || [],
+      telemetryServiceIds: ObjectID.fromJSONArray(
+        (json["telemetryServiceIds"] as Array<JSONObject>) || [],
+      ),
+      lastXSecondsOfEvents: (json["lastXSecondsOfEvents"] as number) || 60,
+    };
+  }
+
+  public static toJSON(monitor: MonitorStepSecurityEventsMonitor): JSONObject {
+    return {
+      attributes: monitor.attributes,
+      messageContains: monitor.messageContains,
+      severityNames: monitor.severityNames,
+      classNames: monitor.classNames,
+      telemetryServiceIds: ObjectID.toJSONArray(monitor.telemetryServiceIds),
+      lastXSecondsOfEvents: monitor.lastXSecondsOfEvents,
+    };
+  }
+}

package/Types/Monitor/MonitorType.ts

@@ -34,6 +34,7 @@ enum MonitorType {
   Traces = "Traces",
   Exceptions = "Exceptions",
   Profiles = "Profiles",
+  SecurityEvents = "Security Events",
 
   /*
    * Network device monitoring (SNMP-based). Replaced the retired SNMP
@@ -139,6 +140,7 @@ export class MonitorTypeHelper {
           MonitorType.Metrics,
           MonitorType.Traces,
           MonitorType.Exceptions,
+          MonitorType.SecurityEvents,
           /*
            * MonitorType.Profiles is intentionally not offered here: the
            * dashboard has no configuration form for the profile monitor
@@ -163,6 +165,7 @@ export class MonitorTypeHelper {
       monitorType === MonitorType.Traces ||
       monitorType === MonitorType.Exceptions ||
       monitorType === MonitorType.Profiles ||
+      monitorType === MonitorType.SecurityEvents ||
       monitorType === MonitorType.Kubernetes ||
       monitorType === MonitorType.Docker ||
       monitorType === MonitorType.Host ||
@@ -541,6 +544,22 @@ export class MonitorTypeHelper {
           "search logs",
         ],
       },
+      {
+        monitorType: MonitorType.SecurityEvents,
+        title: "Security Events",
+        description:
+          "Alert on SIEM signal volume or matching security events from any source.",
+        icon: IconProp.ShieldExclamation,
+        keywords: [
+          "security",
+          "siem",
+          "secops",
+          "chronicle",
+          "ocsf",
+          "detection",
+          "threat",
+        ],
+      },
       {
         monitorType: MonitorType.Exceptions,
         title: "Exceptions",
@@ -783,6 +802,7 @@ export class MonitorTypeHelper {
       MonitorType.Traces,
       MonitorType.Exceptions,
       MonitorType.Profiles,
+      MonitorType.SecurityEvents,
       MonitorType.NetworkDevice,
       MonitorType.DNS,
       MonitorType.DNSSEC,

package/Types/Monitor/SecurityEventsMonitor/SecurityEventsMonitorResponse.ts

@@ -0,0 +1,17 @@
+import SecurityEvent from "../../../Models/AnalyticsModels/SecurityEvent";
+import Query from "../../BaseDatabase/Query";
+import ObjectID from "../../ObjectID";
+import MonitorEvaluationSummary from "../MonitorEvaluationSummary";
+
+/*
+ * securityEventCount is the payload discriminator: DataToProcess payloads
+ * are matched by marker field (see MonitorCriteriaDataExtractor), so this
+ * field name must stay unique across every monitor response type.
+ */
+export default interface SecurityEventsMonitorResponse {
+  projectId: ObjectID;
+  securityEventCount: number;
+  securityEventQuery: Query<SecurityEvent>;
+  monitorId: ObjectID;
+  evaluationSummary?: MonitorEvaluationSummary | undefined;
+}