@cyvest/cyvest-js 4.4.1 → 5.0.2

package/src/getters.ts

@@ -2,7 +2,7 @@
  * Getter utilities for retrieving entities from a Cyvest Investigation.
  *
  * These functions provide type-safe access to observables, checks, threat intel,
- * enrichments, and containers by their keys.
+ * enrichments, and tags by their keys.
  */
 
 import type {
@@ -11,8 +11,11 @@ import type {
   Check,
   ThreatIntel,
   Enrichment,
-  Container,
+  Tag,
+  Level,
 } from "./types.generated";
+import { generateObservableKey, isTagChildOf } from "./keys";
+import { getLevelFromScore } from "./levels";
 
 /**
  * Get an observable by its key.
@@ -68,6 +71,32 @@ export function getObservableByTypeValue(
   return undefined;
 }
 
+/**
+ * Get the root observable of the investigation.
+ *
+ * The root observable is identified using the `root_type` from data extraction
+ * metadata combined with value="root".
+ *
+ * @param inv - The investigation
+ * @returns The root observable, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const root = getRootObservable(investigation);
+ * if (root) {
+ *   console.log(`Root: ${root.type} = ${root.value}`);
+ * }
+ * ```
+ */
+export function getRootObservable(inv: CyvestInvestigation): Observable | undefined {
+  const rootType = inv.data_extraction.root_type;
+  if (!rootType) {
+    return undefined;
+  }
+  const rootKey = generateObservableKey(rootType, "root");
+  return inv.observables[rootKey];
+}
+
 /**
  * Get a check by its key.
  *
@@ -84,60 +113,32 @@ export function getCheck(
   inv: CyvestInvestigation,
   key: string
 ): Check | undefined {
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.key === key) {
-        return check;
-      }
-    }
-  }
-  return undefined;
+  return inv.checks[key];
 }
 
 /**
- * Get a check by its ID and scope.
+ * Get a check by its name.
  *
  * @param inv - The investigation to search
- * @param checkId - Check identifier
- * @param scope - Check scope
+ * @param checkName - Check name
  * @returns The check or undefined if not found
  *
  * @example
  * ```ts
- * const check = getCheckByIdScope(investigation, "sender_verification", "email_headers");
+ * const check = getCheckByName(investigation, "sender_verification");
  * ```
  */
-export function getCheckByIdScope(
+export function getCheckByName(
   inv: CyvestInvestigation,
-  checkId: string,
-  scope: string
+  checkName: string
 ): Check | undefined {
-  const normalizedId = checkId.trim().toLowerCase();
-  const normalizedScope = scope.trim().toLowerCase();
-
-  const scopeChecks = inv.checks[normalizedScope] || inv.checks[scope];
-  if (scopeChecks) {
-    return scopeChecks.find(
-      (c) => c.check_id.toLowerCase() === normalizedId
-    );
-  }
-
-  // Fallback: search all scopes
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (
-        check.check_id.toLowerCase() === normalizedId &&
-        check.scope.toLowerCase() === normalizedScope
-      ) {
-        return check;
-      }
-    }
-  }
-  return undefined;
+  const normalizedName = checkName.trim().toLowerCase();
+  const key = `chk:${normalizedName}`;
+  return inv.checks[key];
 }
 
 /**
- * Get all checks as a flat array (not grouped by scope).
+ * Get all checks as an array.
  *
  * @param inv - The investigation
  * @returns Array of all checks
@@ -149,11 +150,7 @@ export function getCheckByIdScope(
  * ```
  */
 export function getAllChecks(inv: CyvestInvestigation): Check[] {
-  const result: Check[] = [];
-  for (const checks of Object.values(inv.checks)) {
-    result.push(...checks);
-  }
-  return result;
+  return Object.values(inv.checks);
 }
 
 /**
@@ -252,81 +249,62 @@ export function getAllEnrichments(inv: CyvestInvestigation): Enrichment[] {
 }
 
 /**
- * Get a container by its key.
+ * Get a tag by its key.
  *
  * @param inv - The investigation to search
- * @param key - Container key (e.g., "ctr:email/headers")
- * @returns The container or undefined if not found
+ * @param key - Tag key (e.g., "tag:header:auth")
+ * @returns The tag or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const tag = getTag(investigation, "tag:header:auth");
+ * if (tag) {
+ *   console.log(tag.name, tag.direct_level);
+ * }
+ * ```
  */
-export function getContainer(
+export function getTag(
   inv: CyvestInvestigation,
   key: string
-): Container | undefined {
-  // First check top-level containers
-  if (inv.containers[key]) {
-    return inv.containers[key];
-  }
-
-  // Search recursively in sub-containers
-  function searchSubContainers(containers: Record<string, Container>): Container | undefined {
-    for (const container of Object.values(containers)) {
-      if (container.key === key) {
-        return container;
-      }
-      const found = searchSubContainers(container.sub_containers);
-      if (found) return found;
-    }
-    return undefined;
-  }
-
-  return searchSubContainers(inv.containers);
+): Tag | undefined {
+  return inv.tags[key];
 }
 
 /**
- * Get a container by its path.
+ * Get a tag by its name.
  *
  * @param inv - The investigation to search
- * @param path - Container path
- * @returns The container or undefined if not found
+ * @param name - Tag name (e.g., "header:auth:dkim")
+ * @returns The tag or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const tag = getTagByName(investigation, "header:auth:dkim");
+ * ```
  */
-export function getContainerByPath(
+export function getTagByName(
   inv: CyvestInvestigation,
-  path: string
-): Container | undefined {
-  const normalizedPath = path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").toLowerCase();
-
-  function searchContainers(containers: Record<string, Container>): Container | undefined {
-    for (const container of Object.values(containers)) {
-      if (container.path.toLowerCase() === normalizedPath) {
-        return container;
-      }
-      const found = searchContainers(container.sub_containers);
-      if (found) return found;
-    }
-    return undefined;
-  }
-
-  return searchContainers(inv.containers);
+  name: string
+): Tag | undefined {
+  const normalizedName = name.trim().toLowerCase();
+  const key = `tag:${normalizedName}`;
+  return inv.tags[key];
 }
 
 /**
- * Get all containers as a flat array (including sub-containers).
+ * Get all tags as an array.
  *
  * @param inv - The investigation
- * @returns Array of all containers
+ * @returns Array of all tags
+ *
+ * @example
+ * ```ts
+ * const allTags = getAllTags(investigation);
+ * console.log(`Total tags: ${allTags.length}`);
+ * ```
  */
-export function getAllContainers(inv: CyvestInvestigation): Container[] {
-  const result: Container[] = [];
-
-  function collectContainers(containers: Record<string, Container>): void {
-    for (const container of Object.values(containers)) {
-      result.push(container);
-      collectContainers(container.sub_containers);
-    }
-  }
-
-  collectContainers(inv.containers);
-  return result;
+export function getAllTags(inv: CyvestInvestigation): Tag[] {
+  return Object.values(inv.tags);
 }
 
 /**
@@ -377,7 +355,7 @@ export interface InvestigationCounts {
   checks: number;
   threatIntels: number;
   enrichments: number;
-  containers: number;
+  tags: number;
   whitelists: number;
 }
 
@@ -393,7 +371,7 @@ export function getCounts(inv: CyvestInvestigation): InvestigationCounts {
     checks: getAllChecks(inv).length,
     threatIntels: Object.keys(inv.threat_intels).length,
     enrichments: Object.keys(inv.enrichments).length,
-    containers: getAllContainers(inv).length,
+    tags: getAllTags(inv).length,
     whitelists: inv.whitelists.length,
   };
 }
@@ -420,3 +398,97 @@ export function getStartedAt(inv: CyvestInvestigation): string | undefined {
   );
   return event?.timestamp;
 }
+
+// ============================================================================
+// Tag Aggregation
+// ============================================================================
+
+/**
+ * Get direct child tags of a given tag.
+ *
+ * @param inv - The investigation
+ * @param tagName - Parent tag name
+ * @returns Array of direct child tags
+ *
+ * @example
+ * ```ts
+ * const children = getTagChildren(investigation, "bodies");
+ * // Returns tags like "bodies:urls", "bodies:domains" (but not "bodies:urls:something")
+ * ```
+ */
+export function getTagChildren(inv: CyvestInvestigation, tagName: string): Tag[] {
+  return Object.values(inv.tags).filter((tag) => isTagChildOf(tag.name, tagName));
+}
+
+/**
+ * Get all descendant tags of a given tag (any depth).
+ *
+ * @param inv - The investigation
+ * @param tagName - Ancestor tag name
+ * @returns Array of all descendant tags
+ *
+ * @example
+ * ```ts
+ * const descendants = getTagDescendants(investigation, "bodies");
+ * // Returns all tags starting with "bodies:"
+ * ```
+ */
+export function getTagDescendants(inv: CyvestInvestigation, tagName: string): Tag[] {
+  const prefix = tagName + ":";
+  return Object.values(inv.tags).filter((tag) => tag.name.startsWith(prefix));
+}
+
+/**
+ * Get the aggregated score for a tag including all descendant tags.
+ *
+ * The aggregated score includes:
+ * - The tag's direct_score (from its direct checks)
+ * - Recursively, the aggregated scores of all child tags
+ *
+ * @param inv - The investigation
+ * @param tagName - Name of the tag
+ * @returns Total aggregated score, or 0 if tag not found
+ *
+ * @example
+ * ```ts
+ * const score = getTagAggregatedScore(investigation, "bodies");
+ * // Includes scores from bodies, bodies:urls, bodies:domains, etc.
+ * ```
+ */
+export function getTagAggregatedScore(inv: CyvestInvestigation, tagName: string): number {
+  const tag = getTagByName(inv, tagName);
+  if (!tag) {
+    return 0;
+  }
+
+  // Start with direct score
+  let total = tag.direct_score;
+
+  // Add scores from direct children (they will recursively add their children)
+  const children = getTagChildren(inv, tagName);
+  for (const child of children) {
+    total += getTagAggregatedScore(inv, child.name);
+  }
+
+  return total;
+}
+
+/**
+ * Get the aggregated level for a tag including all descendant tags.
+ *
+ * The level is calculated from the aggregated score using the standard
+ * score-to-level mapping.
+ *
+ * @param inv - The investigation
+ * @param tagName - Name of the tag
+ * @returns Level based on aggregated score
+ *
+ * @example
+ * ```ts
+ * const level = getTagAggregatedLevel(investigation, "bodies");
+ * // Returns "MALICIOUS" if aggregated score >= 5, etc.
+ * ```
+ */
+export function getTagAggregatedLevel(inv: CyvestInvestigation, tagName: string): Level {
+  return getLevelFromScore(getTagAggregatedScore(inv, tagName));
+}

package/src/graph.ts

@@ -325,15 +325,15 @@ export function getObservableGraph(inv: CyvestInvestigation): InvestigationGraph
 // ============================================================================
 
 /**
- * Find the root observable(s) of the investigation.
+ * Find source observables in the investigation graph.
  *
- * Root observables are those that have no incoming relationships
+ * Source observables are those that have no incoming relationships
  * (nothing points to them as a target).
  *
  * @param inv - The investigation
- * @returns Array of root observables
+ * @returns Array of source observables
  */
-export function findRootObservables(inv: CyvestInvestigation): Observable[] {
+export function findSourceObservables(inv: CyvestInvestigation): Observable[] {
   const targetKeys = new Set<string>();
 
   // Collect all target keys from relationships

package/src/keys.ts

@@ -8,7 +8,7 @@
 /**
  * Key type prefixes used in Cyvest.
  */
-export type KeyType = "obs" | "chk" | "ti" | "enr" | "ctr";
+export type KeyType = "obs" | "chk" | "ti" | "enr" | "tag";
 
 /**
  * Normalize a string value for consistent key generation.
@@ -58,22 +58,20 @@ export function generateObservableKey(obsType: string, value: string): string {
 /**
  * Generate a unique key for a check.
  *
- * Format: chk:{check_id}:{scope}
+ * Format: chk:{check_name}
  *
- * @param checkId - Identifier of the check
- * @param scope - Scope of the check
+ * @param checkName - Name of the check
  * @returns Unique check key
  *
  * @example
  * ```ts
- * generateCheckKey("sender_verification", "email_headers")
- * // => "chk:sender_verification:email_headers"
+ * generateCheckKey("sender_verification")
+ * // => "chk:sender_verification"
  * ```
  */
-export function generateCheckKey(checkId: string, scope: string): string {
-  const normalizedId = normalizeValue(checkId);
-  const normalizedScope = normalizeValue(scope);
-  return `chk:${normalizedId}:${normalizedScope}`;
+export function generateCheckKey(checkName: string): string {
+  const normalizedName = normalizeValue(checkName);
+  return `chk:${normalizedName}`;
 }
 
 /**
@@ -127,31 +125,88 @@ export function generateEnrichmentKey(name: string, context?: string): string {
 }
 
 /**
- * Generate a unique key for a container.
+ * Generate a unique key for a tag.
  *
- * Format: ctr:{normalized_path}
+ * Format: tag:{normalized_name}
  *
- * @param path - Path of the container (can use / or . as separator)
- * @returns Unique container key
+ * @param name - Name of the tag (can use : as hierarchy delimiter)
+ * @returns Unique tag key
  *
  * @example
  * ```ts
- * generateContainerKey("email/headers")
- * // => "ctr:email/headers"
+ * generateTagKey("header:auth:dkim")
+ * // => "tag:header:auth:dkim"
  * ```
  */
-export function generateContainerKey(path: string): string {
-  // Normalize path separators
-  let normalizedPath = path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
-  normalizedPath = normalizeValue(normalizedPath);
-  return `ctr:${normalizedPath}`;
+export function generateTagKey(name: string): string {
+  const normalizedName = normalizeValue(name);
+  return `tag:${normalizedName}`;
+}
+
+/**
+ * Get all ancestor tag names from a hierarchical tag name.
+ *
+ * @param name - Tag name with : delimiter
+ * @returns Array of ancestor tag names
+ *
+ * @example
+ * ```ts
+ * getTagAncestors("header:auth:dkim")
+ * // => ["header", "header:auth"]
+ * ```
+ */
+export function getTagAncestors(name: string): string[] {
+  const parts = name.split(":");
+  const ancestors: string[] = [];
+  for (let i = 0; i < parts.length - 1; i++) {
+    ancestors.push(parts.slice(0, i + 1).join(":"));
+  }
+  return ancestors;
+}
+
+/**
+ * Check if a tag is a direct child of another tag.
+ *
+ * @param childName - Potential child tag name
+ * @param parentName - Potential parent tag name
+ * @returns True if childName is a direct child of parentName
+ *
+ * @example
+ * ```ts
+ * isTagChildOf("header:auth", "header") // => true
+ * isTagChildOf("header:auth:dkim", "header") // => false (grandchild)
+ * ```
+ */
+export function isTagChildOf(childName: string, parentName: string): boolean {
+  if (!childName.startsWith(parentName + ":")) {
+    return false;
+  }
+  const remaining = childName.slice(parentName.length + 1);
+  return !remaining.includes(":");
+}
+
+/**
+ * Check if a tag is a descendant of another tag (any depth).
+ *
+ * @param descendantName - Potential descendant tag name
+ * @param ancestorName - Potential ancestor tag name
+ * @returns True if descendantName is a descendant of ancestorName
+ *
+ * @example
+ * ```ts
+ * isTagDescendantOf("header:auth:dkim", "header") // => true
+ * isTagDescendantOf("header", "header") // => false (same)
+ * ```
+ */
+export function isTagDescendantOf(descendantName: string, ancestorName: string): boolean {
+  return descendantName.startsWith(ancestorName + ":");
 }
 
 /**
  * Extract the type prefix from a key.
  *
  * @param key - The key to parse
- * @returns Type prefix (obs, chk, ti, enr, ctr) or null if invalid
+ * @returns Type prefix (obs, chk, ti, enr, tag) or null if invalid
  *
  * @example
  * ```ts
@@ -162,7 +217,7 @@ export function generateContainerKey(path: string): string {
 export function parseKeyType(key: string): KeyType | null {
   if (key.includes(":")) {
     const prefix = key.split(":", 1)[0] as KeyType;
-    if (["obs", "chk", "ti", "enr", "ctr"].includes(prefix)) {
+    if (["obs", "chk", "ti", "enr", "tag"].includes(prefix)) {
       return prefix;
     }
   }
@@ -233,25 +288,24 @@ export function parseObservableKey(
  * Extract components from a check key.
  *
  * @param key - Check key to parse
- * @returns Object with checkId and scope, or null if invalid
+ * @returns Object with checkName, or null if invalid
  *
  * @example
  * ```ts
- * parseCheckKey("chk:sender_verification:email_headers")
- * // => { checkId: "sender_verification", scope: "email_headers" }
+ * parseCheckKey("chk:sender_verification")
+ * // => { checkName: "sender_verification" }
  * ```
  */
 export function parseCheckKey(
   key: string
-): { checkId: string; scope: string } | null {
+): { checkName: string } | null {
   if (!validateKey(key, "chk")) {
     return null;
   }
   const parts = key.split(":");
-  if (parts.length >= 3) {
+  if (parts.length >= 2) {
     return {
-      checkId: parts[1],
-      scope: parts.slice(2).join(":"),
+      checkName: parts.slice(1).join(":"),
     };
   }
   return null;

package/src/levels.ts

@@ -9,7 +9,7 @@ import type {
   Observable,
   Check,
   ThreatIntel,
-  Container,
+  Tag,
   Level,
 } from "./types.generated";
 
@@ -254,15 +254,15 @@ export function hasLevel(obj: unknown): obj is { level: Level } {
 }
 
 /**
- * Extract level from an entity (Observable, Check, ThreatIntel, Container).
+ * Extract level from an entity (Observable, Check, ThreatIntel, Tag).
  */
 export function getEntityLevel(
-  entity: Observable | Check | ThreatIntel | Container
+  entity: Observable | Check | ThreatIntel | Tag
 ): Level {
-  if ("aggregated_level" in entity) {
-    const aggregatedLevel = entity.aggregated_level;
-    if (typeof aggregatedLevel === "string" && isValidLevel(aggregatedLevel)) {
-      return aggregatedLevel;
+  if ("direct_level" in entity) {
+    const directLevel = entity.direct_level;
+    if (typeof directLevel === "string" && isValidLevel(directLevel)) {
+      return directLevel;
     }
   }
   if ("level" in entity && isValidLevel(entity.level)) {