@oneuptime/common 12.0.14 → 12.0.16

package/Types/SecurityEvent/OcsfEventClass.ts

@@ -0,0 +1,205 @@
+/*
+ * OCSF event classes and categories — the curated subset OneUptime maps
+ * ingested security events onto.
+ *
+ * OCSF groups event classes into categories (System Activity, Findings,
+ * IAM, Network Activity, Discovery, Application Activity). Each class has a
+ * stable uid; category uid is floor(class_uid / 1000). Events whose source
+ * dialect has no OCSF equivalent keep class uid 0 with a source-derived
+ * class name, so nothing is dropped just because it does not map.
+ *
+ * https://schema.ocsf.io/classes
+ */
+export enum OcsfCategory {
+  Uncategorized = "Uncategorized",
+  SystemActivity = "System Activity",
+  Findings = "Findings",
+  IdentityAndAccessManagement = "Identity & Access Management",
+  NetworkActivity = "Network Activity",
+  Discovery = "Discovery",
+  ApplicationActivity = "Application Activity",
+}
+
+export const OcsfCategoryId: Record<OcsfCategory, number> = {
+  [OcsfCategory.Uncategorized]: 0,
+  [OcsfCategory.SystemActivity]: 1,
+  [OcsfCategory.Findings]: 2,
+  [OcsfCategory.IdentityAndAccessManagement]: 3,
+  [OcsfCategory.NetworkActivity]: 4,
+  [OcsfCategory.Discovery]: 5,
+  [OcsfCategory.ApplicationActivity]: 6,
+};
+
+export interface OcsfEventClassProps {
+  uid: number;
+  name: string;
+  category: OcsfCategory;
+}
+
+/*
+ * Class uids come from the OCSF schema. The Windows extension's Registry
+ * Key Activity (201001) is included because Google SecOps UDM registry
+ * events are common in the wild.
+ */
+export const OcsfEventClasses: Array<OcsfEventClassProps> = [
+  { uid: 0, name: "Base Event", category: OcsfCategory.Uncategorized },
+
+  // System Activity (1xxx)
+  {
+    uid: 1001,
+    name: "File System Activity",
+    category: OcsfCategory.SystemActivity,
+  },
+  {
+    uid: 1005,
+    name: "Module Activity",
+    category: OcsfCategory.SystemActivity,
+  },
+  {
+    uid: 1006,
+    name: "Scheduled Job Activity",
+    category: OcsfCategory.SystemActivity,
+  },
+  {
+    uid: 1007,
+    name: "Process Activity",
+    category: OcsfCategory.SystemActivity,
+  },
+
+  // Findings (2xxx)
+  {
+    uid: 2002,
+    name: "Vulnerability Finding",
+    category: OcsfCategory.Findings,
+  },
+  { uid: 2003, name: "Compliance Finding", category: OcsfCategory.Findings },
+  { uid: 2004, name: "Detection Finding", category: OcsfCategory.Findings },
+  { uid: 2005, name: "Incident Finding", category: OcsfCategory.Findings },
+
+  // Identity & Access Management (3xxx)
+  {
+    uid: 3001,
+    name: "Account Change",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+  {
+    uid: 3002,
+    name: "Authentication",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+  {
+    uid: 3003,
+    name: "Authorize Session",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+  {
+    uid: 3004,
+    name: "Entity Management",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+  {
+    uid: 3005,
+    name: "User Access Management",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+  {
+    uid: 3006,
+    name: "Group Management",
+    category: OcsfCategory.IdentityAndAccessManagement,
+  },
+
+  // Network Activity (4xxx)
+  {
+    uid: 4001,
+    name: "Network Activity",
+    category: OcsfCategory.NetworkActivity,
+  },
+  { uid: 4002, name: "HTTP Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4003, name: "DNS Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4004, name: "DHCP Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4005, name: "RDP Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4006, name: "SMB Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4007, name: "SSH Activity", category: OcsfCategory.NetworkActivity },
+  { uid: 4008, name: "FTP Activity", category: OcsfCategory.NetworkActivity },
+  {
+    uid: 4009,
+    name: "Email Activity",
+    category: OcsfCategory.NetworkActivity,
+  },
+
+  // Discovery (5xxx)
+  {
+    uid: 5001,
+    name: "Device Inventory Info",
+    category: OcsfCategory.Discovery,
+  },
+  {
+    uid: 5002,
+    name: "Device Config State",
+    category: OcsfCategory.Discovery,
+  },
+
+  // Application Activity (6xxx)
+  {
+    uid: 6001,
+    name: "Web Resources Activity",
+    category: OcsfCategory.ApplicationActivity,
+  },
+  {
+    uid: 6002,
+    name: "Application Lifecycle",
+    category: OcsfCategory.ApplicationActivity,
+  },
+  {
+    uid: 6003,
+    name: "API Activity",
+    category: OcsfCategory.ApplicationActivity,
+  },
+
+  // Windows extension.
+  {
+    uid: 201001,
+    name: "Registry Key Activity",
+    category: OcsfCategory.SystemActivity,
+  },
+];
+
+export function ocsfEventClassByUid(
+  uid: number,
+): OcsfEventClassProps | undefined {
+  return OcsfEventClasses.find((cls: OcsfEventClassProps): boolean => {
+    return cls.uid === uid;
+  });
+}
+
+export function ocsfCategoryForClassUid(uid: number): {
+  categoryUid: number;
+  categoryName: string;
+} {
+  const cls: OcsfEventClassProps | undefined = ocsfEventClassByUid(uid);
+
+  if (cls) {
+    return {
+      categoryUid: OcsfCategoryId[cls.category],
+      categoryName: cls.category,
+    };
+  }
+
+  /*
+   * Unknown class uid — derive the category from the uid's thousands digit
+   * when it lands on a known category, otherwise Uncategorized.
+   */
+  const derived: number = Math.floor(uid / 1000);
+  const entries: Array<[string, number]> = Object.entries(OcsfCategoryId);
+
+  for (const [name, value] of entries) {
+    if (value === derived && value !== 0) {
+      return { categoryUid: value, categoryName: name };
+    }
+  }
+
+  return {
+    categoryUid: OcsfCategoryId[OcsfCategory.Uncategorized],
+    categoryName: OcsfCategory.Uncategorized,
+  };
+}

package/Types/SecurityEvent/OcsfSeverity.ts

@@ -0,0 +1,88 @@
+/*
+ * OCSF (Open Cybersecurity Schema Framework) severity levels.
+ *
+ * Security events are normalized to OCSF at ingest, whatever dialect they
+ * arrived in (Google SecOps UDM, native OCSF, generic JSON). The severity a
+ * row stores is always one of these names plus the matching numeric id —
+ * writers must take both from this file or a row will say one thing in its
+ * text and another in its number.
+ *
+ * https://schema.ocsf.io/ (severity_id on the base event class)
+ */
+enum OcsfSeverity {
+  Unknown = "Unknown",
+  Informational = "Informational",
+  Low = "Low",
+  Medium = "Medium",
+  High = "High",
+  Critical = "Critical",
+  Fatal = "Fatal",
+  Other = "Other",
+}
+
+export const OcsfSeverityId: Record<OcsfSeverity, number> = {
+  [OcsfSeverity.Unknown]: 0,
+  [OcsfSeverity.Informational]: 1,
+  [OcsfSeverity.Low]: 2,
+  [OcsfSeverity.Medium]: 3,
+  [OcsfSeverity.High]: 4,
+  [OcsfSeverity.Critical]: 5,
+  [OcsfSeverity.Fatal]: 6,
+  [OcsfSeverity.Other]: 99,
+};
+
+export function ocsfSeverityFromId(id: number): OcsfSeverity {
+  const entries: Array<[string, number]> = Object.entries(OcsfSeverityId);
+
+  for (const [name, value] of entries) {
+    if (value === id) {
+      return name as OcsfSeverity;
+    }
+  }
+
+  return OcsfSeverity.Unknown;
+}
+
+/*
+ * Loose severity text -> OCSF severity. Accepts the dialects we ingest:
+ * UDM security_result severities (EMERGENCY/ALERT/CRITICAL/ERROR/HIGH/...),
+ * syslog-style levels, and common vendor strings. Returns null for anything
+ * unrecognised — callers decide the fallback, guessing here would silently
+ * misgrade events.
+ */
+export function normalizeOcsfSeverity(text: string): OcsfSeverity | null {
+  const normalized: string = (text || "").trim().toUpperCase();
+
+  if (!normalized) {
+    return null;
+  }
+
+  const aliases: Record<string, OcsfSeverity> = {
+    UNKNOWN: OcsfSeverity.Unknown,
+    UNKNOWN_SEVERITY: OcsfSeverity.Unknown,
+    NONE: OcsfSeverity.Informational,
+    INFO: OcsfSeverity.Informational,
+    INFORMATION: OcsfSeverity.Informational,
+    INFORMATIONAL: OcsfSeverity.Informational,
+    NOTICE: OcsfSeverity.Informational,
+    DEBUG: OcsfSeverity.Informational,
+    LOW: OcsfSeverity.Low,
+    WARN: OcsfSeverity.Low,
+    WARNING: OcsfSeverity.Low,
+    MEDIUM: OcsfSeverity.Medium,
+    MODERATE: OcsfSeverity.Medium,
+    ERR: OcsfSeverity.Medium,
+    ERROR: OcsfSeverity.Medium,
+    HIGH: OcsfSeverity.High,
+    SEVERE: OcsfSeverity.High,
+    CRITICAL: OcsfSeverity.Critical,
+    CRIT: OcsfSeverity.Critical,
+    ALERT: OcsfSeverity.Critical,
+    FATAL: OcsfSeverity.Fatal,
+    EMERGENCY: OcsfSeverity.Fatal,
+  };
+
+  return aliases[normalized] || null;
+}
+
+export default OcsfSeverity;

package/Types/SecurityEvent/SecurityEventFormat.ts

@@ -0,0 +1,23 @@
+/*
+ * Wire dialects the security-events ingest endpoint accepts. Clients can
+ * name the format explicitly (query param or header); when they do not,
+ * ingest sniffs it per event — see SecurityEventFormatDetector.
+ */
+enum SecurityEventFormat {
+  // Native OCSF event JSON (class_uid / category_uid / severity_id ...).
+  Ocsf = "ocsf",
+
+  // Google SecOps / Chronicle UDM event JSON (metadata.event_type ...).
+  Udm = "udm",
+
+  /*
+   * Google SecOps detection/alert payloads — what a SOAR playbook webhook
+   * or the detections stream delivers (rule metadata + matched events).
+   */
+  GoogleSecOpsAlert = "google-secops-alert",
+
+  // Anything else — best-effort field mapping.
+  Generic = "generic",
+}
+
+export default SecurityEventFormat;

package/Types/SecurityEvent/SigmaRule.ts

@@ -0,0 +1,70 @@
+import Dictionary from "../Dictionary";
+import { JSONValue } from "../JSON";
+
+/*
+ * Typed representation of a parsed Sigma rule — the subset OneUptime's
+ * detection engine evaluates. Produced by SigmaRuleParser, consumed by
+ * the ClickHouse compiler.
+ *
+ * https://sigmahq.io/docs/basics/rules.html
+ */
+
+export enum SigmaLevel {
+  Informational = "informational",
+  Low = "low",
+  Medium = "medium",
+  High = "high",
+  Critical = "critical",
+}
+
+/*
+ * One `field|modifier: value` requirement inside a selection map. `values`
+ * always has at least one entry; multiple entries are OR-ed (AND-ed when
+ * the `all` modifier is present).
+ */
+export interface SigmaFieldRequirement {
+  field: string;
+  modifiers: Array<string>;
+  values: Array<JSONValue>;
+}
+
+/*
+ * A named entry under `detection:`. Exactly one of the shapes is set:
+ * - fieldMaps: list of {field: requirement} maps; maps OR, fields AND.
+ * - keywords: bare string list matched against the event message.
+ */
+export interface SigmaSelection {
+  name: string;
+  fieldMaps: Array<Array<SigmaFieldRequirement>>;
+  keywords: Array<string>;
+}
+
+/*
+ * Condition AST. Parsed from the `condition:` expression grammar:
+ * identifiers, and/or/not, parentheses, and the `1 of x*` / `all of x*` /
+ * `any of them` quantifiers.
+ */
+export type SigmaConditionNode =
+  | { kind: "selection"; name: string }
+  | { kind: "and"; children: Array<SigmaConditionNode> }
+  | { kind: "or"; children: Array<SigmaConditionNode> }
+  | { kind: "not"; child: SigmaConditionNode }
+  | {
+      kind: "of";
+      quantifier: "any" | "all" | number;
+      pattern: string; // 'them' or a name pattern possibly ending in '*'
+    };
+
+export default interface SigmaRule {
+  title: string;
+  id: string;
+  description: string;
+  level: SigmaLevel;
+  status: string;
+  tags: Array<string>;
+  mitreTactics: Array<string>;
+  mitreTechniques: Array<string>;
+  logsource: Dictionary<string>;
+  selections: Array<SigmaSelection>;
+  condition: SigmaConditionNode;
+}

package/Types/Telemetry/LlmConventions.ts

@@ -64,12 +64,31 @@ export const LlmTotalTokenAttributeKeys: Array<string> = [
   "llm.usage.total_tokens",
 ];
 
-// Cost in USD. Only populated when the SDK reports it (no built-in pricing).
+/*
+ * Cost in USD. A reported cost always wins; when absent, ingest computes an
+ * estimate from token counts via Common/Types/Telemetry/LlmCostCatalog.ts.
+ */
 export const LlmCostAttributeKeys: Array<string> = [
   "gen_ai.usage.cost",
   "gen_ai.usage.cost_usd",
   "gen_ai.usage.total_cost",
   "llm.usage.total_cost",
+  // LiteLLM proxy: v1 otel callback / opt-in OTel v2 mode.
+  "gen_ai.cost.total_cost",
+  "litellm.cost.total",
+];
+
+/*
+ * Conversation / session id that groups the LLM calls of one user interaction
+ * across traces. gen_ai.conversation.id is the OTel semconv key; session.id is
+ * emitted by OpenInference and Langfuse-compatible SDKs; the traceloop
+ * association property is OpenLLMetry's spelling.
+ */
+export const LlmConversationIdAttributeKeys: Array<string> = [
+  "gen_ai.conversation.id",
+  "session.id",
+  "langfuse.session.id",
+  "traceloop.association.properties.session_id",
 ];
 
 export const LlmAgentNameAttributeKeys: Array<string> = [