@oneuptime/common 13.0.3 → 13.0.5

package/Types/SecurityEvent/Connectors/SecurityEventConnectorProvider.ts

@@ -0,0 +1,41 @@
+/*
+ * The security sources OneUptime can poll through the managed
+ * Security Event Connections framework. Each value is the stable
+ * identifier stored on SecurityEventConnection.provider, used to look up
+ * the server-side connector in SecurityEventConnectorRegistry and the
+ * form/help metadata in SecurityEventConnectorCatalog.
+ *
+ * Google SecOps predates this framework and keeps its own model
+ * (GoogleSecOpsConnection) and poller; it is deliberately not listed here.
+ */
+enum SecurityEventConnectorProvider {
+  MicrosoftSentinel = "microsoft-sentinel",
+  MicrosoftDefenderXdr = "microsoft-defender-xdr",
+  CrowdStrikeFalcon = "crowdstrike-falcon",
+  SplunkEnterpriseSecurity = "splunk",
+  ElasticSecurity = "elastic-security",
+  AwsSecurityHub = "aws-security-hub",
+  OktaSystemLog = "okta",
+}
+
+export default SecurityEventConnectorProvider;
+
+export const AllSecurityEventConnectorProviders: Array<SecurityEventConnectorProvider> =
+  [
+    SecurityEventConnectorProvider.MicrosoftSentinel,
+    SecurityEventConnectorProvider.MicrosoftDefenderXdr,
+    SecurityEventConnectorProvider.CrowdStrikeFalcon,
+    SecurityEventConnectorProvider.SplunkEnterpriseSecurity,
+    SecurityEventConnectorProvider.ElasticSecurity,
+    SecurityEventConnectorProvider.AwsSecurityHub,
+    SecurityEventConnectorProvider.OktaSystemLog,
+  ];
+
+export function isSecurityEventConnectorProvider(
+  value: unknown,
+): value is SecurityEventConnectorProvider {
+  return (
+    typeof value === "string" &&
+    (AllSecurityEventConnectorProviders as Array<string>).includes(value)
+  );
+}

package/Types/SecurityEvent/GoogleSecOpsDiagnostics.ts

@@ -23,13 +23,50 @@ export interface GoogleSecOpsDetectionSample {
   isAlert?: boolean | undefined;
 }
 
+/*
+ * "warn" is a step that completed but left something for the reader: an
+ * optional source (curated rules) the tenant cannot read, returned objects
+ * that were counted and discarded, or a pass a request or time budget
+ * stopped. A budget-stopped pass leaves the poll partial, so the next
+ * scheduled window is narrowed; the other warnings do not affect the
+ * cursor. "failed" is a step that threw, and the cursor is held.
+ */
 export interface GoogleSecOpsDiagnosticCheck {
   name: string;
-  status: "success" | "failed";
+  status: "success" | "failed" | "warn";
   durationMs: number;
   message: string;
 }
 
+/*
+ * Which timestamp the run's window was applied to. Polls list by the time
+ * Google CREATED a detection, because a rule that runs hourly creates its
+ * detections long after the events they describe; preview and backfill
+ * use the detection-time range the person picked (with created time read
+ * as well) so what they see matches the SecOps alerts view.
+ */
+export type GoogleSecOpsRunBasis = "created-time" | "detection-time";
+
+// How many records each of the three read passes returned, before the union.
+export interface GoogleSecOpsSourceCounts {
+  ruleDetections: number;
+  curatedDetections: number;
+  alertsView: number;
+}
+
+/*
+ * createdTime minus detectionTime over the fetched records. A lag larger
+ * than the poll interval is the exact case a detection-time cursor would
+ * skip, which is why the numbers are kept on every run.
+ */
+export interface GoogleSecOpsCreationLag {
+  // Records carrying both timestamps.
+  measured: number;
+  // Records created more than pollIntervalInMinutes + 1 minute after their detection time.
+  lateCount: number;
+  maxLagMinutes: number;
+}
+
 export interface GoogleSecOpsRunResult {
   type: GoogleSecOpsRunType;
   runId?: string | undefined;
@@ -40,6 +77,9 @@ export interface GoogleSecOpsRunResult {
   windowStart: string;
   windowEnd: string;
   includeNonAlertingDetections: boolean;
+  basis?: GoogleSecOpsRunBasis | undefined;
+  sourceCounts?: GoogleSecOpsSourceCounts | undefined;
+  creationLag?: GoogleSecOpsCreationLag | undefined;
   fetchedCount: number;
   ingestedCount: number;
   duplicateCount: number;
@@ -53,4 +93,19 @@ export interface GoogleSecOpsRunResult {
   eventTimeStart?: string | undefined;
   eventTimeEnd?: string | undefined;
   error?: string | undefined;
+  /*
+   * Adaptive catch-up, scheduled polls only. chunkMinutes is the minutes of
+   * creation time this poll read past the saved cursor (from the window
+   * start when there was no usable cursor); the overlap before the cursor is
+   * not counted. nextChunkMinutes is the chunk the next scheduled poll is
+   * given. A poll that could not read its window halves it (or, when the
+   * source reads in ascending creation order, resumes from the last record
+   * read); a complete poll never shrinks it and doubles it back towards the
+   * 24 hour maximum; a failed poll keeps it. forcedAdvance records a one
+   * minute window that still could not be read completely and was skipped
+   * past so polling keeps moving.
+   */
+  chunkMinutes?: number | undefined;
+  nextChunkMinutes?: number | undefined;
+  forcedAdvance?: boolean | undefined;
 }

package/Types/SecurityEvent/GoogleSecOpsRegion.ts

@@ -0,0 +1,34 @@
+/*
+ * Regional service endpoint prefixes published for chronicle.googleapis.com.
+ *
+ * Keep this list shared by server-side validation and the connection form. A
+ * free-text form in front of a stricter server allowlist lets a typo survive
+ * until save, while two copied allowlists eventually disagree as Google adds
+ * endpoints.
+ *
+ * Source: https://cloud.google.com/chronicle/docs/reference/rest
+ */
+export const GOOGLE_SECOPS_SUPPORTED_REGIONS: ReadonlyArray<string> = [
+  "us",
+  "eu",
+  "europe",
+  "africa-south1",
+  "asia-east1",
+  "asia-northeast1",
+  "asia-northeast3",
+  "asia-south1",
+  "asia-southeast1",
+  "asia-southeast2",
+  "australia-southeast1",
+  "europe-central2",
+  "europe-west12",
+  "europe-west2",
+  "europe-west3",
+  "europe-west6",
+  "europe-west9",
+  "me-central1",
+  "me-central2",
+  "me-west1",
+  "northamerica-northeast2",
+  "southamerica-east1",
+];

package/Types/Telemetry/EntityType.ts

@@ -72,6 +72,20 @@ enum EntityType {
   DockerSwarmService = "docker.swarm.service",
   DockerSwarmTask = "docker.swarm.task",
   TelemetrySdk = "telemetry.sdk",
+  /*
+   * Dependency types, discovered from the CLIENT / PRODUCER spans of an
+   * instrumented service rather than from a resource of their own. They are
+   * the far end of a call nothing on the other side reported: a PostgreSQL
+   * or Redis a service queries (`db.system.name` / `db.system`), or an HTTP /
+   * gRPC / messaging endpoint it talks to (`server.address`, `peer.service`,
+   * `messaging.system`). OneUptime-defined — semconv describes these only as
+   * span attributes, never as entities. Discovered (heartbeat-bumped by the
+   * ComputeServiceDependencies cron), so they age out like any other
+   * discovered row. Deliberately distinct from the manual ExternalService /
+   * ExternalDatabase types below, which nothing ever observes.
+   */
+  Database = "database",
+  RemoteService = "remote.service",
   /*
    * Inventory-mirrored types. Unlike everything above, these are never
    * derived from an OTLP resource — the estate they describe is collected

package/Types/Telemetry/ExceptionSpanScope.ts

@@ -0,0 +1,83 @@
+/*
+ * Scope a span query to the spans that raised one exception group.
+ *
+ * Spans carry no fingerprint of their own; an exception group's occurrences
+ * (ExceptionInstance rows) record the (traceId, spanId) they were raised in.
+ * The server compiles this scope to
+ *
+ *   (traceId, spanId) IN (
+ *     SELECT traceId, spanId FROM <exception occurrences>
+ *     WHERE projectId = <the query's project>
+ *       AND fingerprint = <fingerprint>
+ *       [AND primaryEntityId = <service>]
+ *   )
+ *
+ * so the span list, its count, the histogram and the facets all describe
+ * exactly the spans behind the exception's occurrences — with no cap on how
+ * many occurrences there are. It only ever narrows a query: authorization
+ * still runs on the span query's own projectId and primaryEntityId.
+ */
+
+// The synthetic query key the span list endpoint reads.
+export const EXCEPTION_SPAN_SCOPE_QUERY_KEY: string = "exceptionScope";
+
+// Fingerprints are SHA-256 hex today; the cap only rejects junk.
+export const EXCEPTION_SPAN_SCOPE_MAX_FINGERPRINT_LENGTH: number = 512;
+
+export interface ExceptionSpanScope {
+  fingerprint: string;
+  // The exception group's service; a fingerprint is only unique per service.
+  primaryEntityId?: string | undefined;
+}
+
+const UUID_PATTERN: RegExp =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/*
+ * Validate an untrusted scope (request body, deserialized query). Returns
+ * null for anything malformed so callers can decide how to fail; a blank or
+ * oversized fingerprint, or a service id that is not a UUID, is malformed.
+ */
+export function parseExceptionSpanScope(
+  value: unknown,
+): ExceptionSpanScope | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const record: Record<string, unknown> = value as Record<string, unknown>;
+  const fingerprint: unknown = record["fingerprint"];
+
+  if (typeof fingerprint !== "string") {
+    return null;
+  }
+
+  const trimmedFingerprint: string = fingerprint.trim();
+
+  if (
+    trimmedFingerprint.length === 0 ||
+    trimmedFingerprint.length > EXCEPTION_SPAN_SCOPE_MAX_FINGERPRINT_LENGTH
+  ) {
+    return null;
+  }
+
+  const rawEntityId: unknown = record["primaryEntityId"];
+
+  if (rawEntityId === undefined || rawEntityId === null || rawEntityId === "") {
+    return { fingerprint: trimmedFingerprint };
+  }
+
+  const primaryEntityId: string =
+    typeof rawEntityId === "string"
+      ? rawEntityId.trim()
+      : typeof rawEntityId === "object" &&
+          typeof (rawEntityId as Record<string, unknown>)["value"] === "string"
+        ? ((rawEntityId as Record<string, unknown>)["value"] as string).trim()
+        : "";
+
+  if (!UUID_PATTERN.test(primaryEntityId)) {
+    return null;
+  }
+
+  return { fingerprint: trimmedFingerprint, primaryEntityId };
+}

package/Types/Telemetry/LockedFilterDetail.ts

@@ -0,0 +1,46 @@
+/*
+ * What a LOCKED telemetry filter chip can explain about itself.
+ *
+ * A resource page (a Kubernetes cluster, a Docker host, a RUM application,
+ * an incident's stored query, ...) pins the telemetry explorers it embeds to
+ * its own scope. The viewer shows that scope as a grey chip with a lock icon
+ * — "Cluster: production" — and nothing else, so a reader cannot tell whether
+ * the match is by resource attribute, by entity membership, by service id,
+ * or by something else, nor how to reproduce it on the main explorer page.
+ *
+ * The chip builders in the Dashboard fill one of these per locked chip; the
+ * shared chip renderer turns it into a rich tooltip and into the
+ * "Copy filter" affordance. Display-only: nothing here changes the query.
+ */
+
+/** One predicate the server evaluates for the locked filter. */
+export interface LockedFilterPredicate {
+  /** "Attribute", "Entity key", "Entity id", "Trace ID", ... */
+  label: string;
+  /** The predicate as text, e.g. `resource.k8s.cluster.name = "prod-eks-01"`. */
+  expression: string;
+  /** Optional plain-language note under the expression. */
+  note?: string | undefined;
+}
+
+/** How several predicates of one locked filter combine. Defaults to "all". */
+export type LockedFilterCombinator = "any" | "all";
+
+export interface LockedFilterDetail {
+  /** Why the chip is locked, e.g. "Pinned by this page". */
+  source: string;
+  /** Plain-language summary, e.g. "Only logs from this Kubernetes cluster are shown." */
+  summary: string;
+  /** How rows are matched, in display order. */
+  predicates: Array<LockedFilterPredicate>;
+  /** "any" when the predicates are OR-ed (entity scope), "all" otherwise. */
+  combinator?: LockedFilterCombinator | undefined;
+  /**
+   * Search-bar text that reproduces this filter on the explorer for the same
+   * signal, e.g. `@resource.k8s.cluster.name:prod-eks-01`. Absent when the
+   * grammar cannot express the filter.
+   */
+  searchToken?: string | undefined;
+  /** Why `searchToken` is absent, when it is — shown in place of the syntax. */
+  searchTokenUnavailableReason?: string | undefined;
+}

package/Types/Telemetry/ResourceEntityFacet.ts

@@ -1,3 +1,5 @@
+import { RESOURCE_FACET_CATALOG_KEYS } from "./ResourceFacetCatalog";
+
 /*
  * The resource facets of the telemetry explorers (Logs / Traces), split by
  * how a selection has to be turned into a predicate.
@@ -8,8 +10,9 @@
  * selection has to be matched against depends on the ingestion path:
  *
  *   - Agent-ingested resource telemetry (Infrastructure / Docker / Podman /
- *     Kubernetes agents) has no `service.name`, so the resource IS the
- *     primary entity and `primaryEntityId` holds its Postgres id.
+ *     Kubernetes / Proxmox / Ceph / VMware ... agents) has no
+ *     `service.name`, so the resource IS the primary entity and
+ *     `primaryEntityId` holds its Postgres id.
  *   - OTLP telemetry that carries a `service.name` is primary-keyed on its
  *     Service (`OtelIngestBaseService.selectPrimaryEntity`); the host /
  *     cluster it runs on is recorded only in `entityKeys`.
@@ -34,16 +37,20 @@ export const SERVICE_FACET_KEYS: ReadonlyArray<string> = [
 ];
 
 /**
- * Facets whose values are ids of a NON-Service resource row. These are the
- * ones that need the entity-key treatment; the value is a Postgres id
- * (Host / DockerHost / PodmanHost / KubernetesCluster) which the server
- * resolves to the resource's identifying value and then to its entity key.
+ * Facets whose values are ids of a NON-Service resource row — every entry
+ * of the shared resource facet catalog, in catalog (sidebar) order. The
+ * value is a Postgres id which the server resolves, where the resource type
+ * has a telemetry identity, to its identifying value and from there to its
+ * entity key and resource attribute (see ResourceEntityFilter). Types with
+ * no such identity keep an id-only `primaryEntityId IN (...)` predicate.
+ *
+ * Derived rather than listed: a hand-kept copy of the catalog is exactly
+ * how Proxmox / vCenter / Ceph / Docker Swarm / Serverless / Cloud / RUM /
+ * IoT selections ended up silently dropped by the parser below while their
+ * facets were already on screen.
  */
 export const RESOURCE_ENTITY_FACET_KEYS: ReadonlyArray<string> = [
-  "hostId",
-  "dockerHostId",
-  "podmanHostId",
-  "kubernetesClusterId",
+  ...RESOURCE_FACET_CATALOG_KEYS,
 ];
 
 const RESOURCE_ENTITY_FACET_KEY_SET: ReadonlySet<string> = new Set<string>(

package/Types/Telemetry/ResourceFacetCatalog.ts

@@ -0,0 +1,171 @@
+import IconProp from "../Icon/IconProp";
+import ServiceType from "./ServiceType";
+
+/*
+ * The one list of non-Service resource types the telemetry explorers
+ * (Logs / Traces / Exceptions) offer as filter facets.
+ *
+ * Every per-resource table used to be copied by hand — the facet keys a
+ * viewer requests, the sidebar titles, the ServiceType each aggregation
+ * service counts, the keys the server resolves from Postgres — and the
+ * copies drifted: Host / Docker / Podman / Kubernetes were wired end to
+ * end while Proxmox, vCenter, Ceph, Docker Swarm, Serverless, Cloud, RUM
+ * and IoT were each missing from one layer or another. Deriving those
+ * tables from this catalog keeps a new resource type a one-line change.
+ *
+ * Kept free of React and database models so both the server and the
+ * browser (and plain unit tests) can import it.
+ */
+
+export interface ResourceFacetDefinition {
+  // Facet key used on the wire, in chips and in saved views.
+  facetKey: string;
+  /*
+   * `primaryEntityType` stamped on telemetry whose primary entity is this
+   * resource. IoT fleet telemetry is stamped `IoTDevice` with the fleet id
+   * (there is no fleet member), and RUM applications `RealUserMonitor`.
+   */
+  serviceType: ServiceType;
+  // Singular, title-cased label ("Kubernetes Cluster").
+  label: string;
+  // Plural label for sentences ("Kubernetes Clusters").
+  pluralLabel: string;
+  icon: IconProp;
+}
+
+export const RESOURCE_FACET_CATALOG: ReadonlyArray<ResourceFacetDefinition> = [
+  {
+    facetKey: "hostId",
+    serviceType: ServiceType.Host,
+    label: "Host",
+    pluralLabel: "Hosts",
+    icon: IconProp.Server,
+  },
+  {
+    facetKey: "dockerHostId",
+    serviceType: ServiceType.DockerHost,
+    label: "Docker Host",
+    pluralLabel: "Docker Hosts",
+    icon: IconProp.Docker,
+  },
+  {
+    facetKey: "podmanHostId",
+    serviceType: ServiceType.PodmanHost,
+    label: "Podman Host",
+    pluralLabel: "Podman Hosts",
+    icon: IconProp.Podman,
+  },
+  {
+    facetKey: "kubernetesClusterId",
+    serviceType: ServiceType.KubernetesCluster,
+    label: "Kubernetes Cluster",
+    pluralLabel: "Kubernetes Clusters",
+    icon: IconProp.Kubernetes,
+  },
+  {
+    facetKey: "dockerSwarmClusterId",
+    serviceType: ServiceType.DockerSwarmCluster,
+    label: "Docker Swarm Cluster",
+    pluralLabel: "Docker Swarm Clusters",
+    icon: IconProp.DockerSwarm,
+  },
+  {
+    facetKey: "proxmoxClusterId",
+    serviceType: ServiceType.ProxmoxCluster,
+    label: "Proxmox Cluster",
+    pluralLabel: "Proxmox Clusters",
+    icon: IconProp.Proxmox,
+  },
+  {
+    facetKey: "vmwareVCenterId",
+    serviceType: ServiceType.VMwareVCenter,
+    label: "vCenter",
+    pluralLabel: "vCenters",
+    icon: IconProp.VMware,
+  },
+  {
+    facetKey: "cephClusterId",
+    serviceType: ServiceType.CephCluster,
+    label: "Ceph Cluster",
+    pluralLabel: "Ceph Clusters",
+    icon: IconProp.Ceph,
+  },
+  {
+    facetKey: "serverlessFunctionId",
+    serviceType: ServiceType.ServerlessFunction,
+    label: "Serverless Function",
+    pluralLabel: "Serverless Functions",
+    icon: IconProp.Bolt,
+  },
+  {
+    facetKey: "cloudResourceId",
+    serviceType: ServiceType.CloudResource,
+    label: "Cloud Resource",
+    pluralLabel: "Cloud Resources",
+    icon: IconProp.Cloud,
+  },
+  {
+    facetKey: "rumApplicationId",
+    serviceType: ServiceType.RealUserMonitor,
+    label: "RUM Application",
+    pluralLabel: "RUM Applications",
+    icon: IconProp.Globe,
+  },
+  {
+    facetKey: "iotFleetId",
+    serviceType: ServiceType.IoTDevice,
+    label: "IoT Fleet",
+    pluralLabel: "IoT Fleets",
+    icon: IconProp.IoT,
+  },
+];
+
+// Catalog order — the order the sidebars list resource facets in.
+export const RESOURCE_FACET_CATALOG_KEYS: ReadonlyArray<string> =
+  RESOURCE_FACET_CATALOG.map((definition: ResourceFacetDefinition): string => {
+    return definition.facetKey;
+  });
+
+const DEFINITIONS_BY_KEY: ReadonlyMap<string, ResourceFacetDefinition> =
+  new Map<string, ResourceFacetDefinition>(
+    RESOURCE_FACET_CATALOG.map(
+      (
+        definition: ResourceFacetDefinition,
+      ): [string, ResourceFacetDefinition] => {
+        return [definition.facetKey, definition];
+      },
+    ),
+  );
+
+export function getResourceFacetDefinition(
+  facetKey: string,
+): ResourceFacetDefinition | undefined {
+  return DEFINITIONS_BY_KEY.get(facetKey);
+}
+
+export function isCatalogResourceFacetKey(facetKey: string): boolean {
+  return DEFINITIONS_BY_KEY.has(facetKey);
+}
+
+/*
+ * facetKey → ServiceType, the shape the aggregation services count
+ * resource facets with (`primaryEntityType = <ServiceType>`).
+ */
+export function getResourceFacetServiceTypeMap(): Map<string, ServiceType> {
+  return new Map<string, ServiceType>(
+    RESOURCE_FACET_CATALOG.map(
+      (definition: ResourceFacetDefinition): [string, ServiceType] => {
+        return [definition.facetKey, definition.serviceType];
+      },
+    ),
+  );
+}
+
+// facetKey → singular label, for chip keys and section titles.
+export function getResourceFacetLabelMap(): Record<string, string> {
+  const labels: Record<string, string> = {};
+  for (const definition of RESOURCE_FACET_CATALOG) {
+    labels[definition.facetKey] = definition.label;
+  }
+  return labels;
+}