@cyvest/cyvest-js 4.4.1 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "4.4.1",
+  "version": "5.0.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",

package/src/finders.ts

@@ -10,7 +10,7 @@ import type {
   Observable,
   Check,
   ThreatIntel,
-  Container,
+  Tag,
   Level,
 } from "./types.generated";
 import { isLevelAtLeast, isLevelHigherThan, LEVEL_VALUES } from "./levels";
@@ -187,39 +187,6 @@ export function findObservablesWithThreatIntel(
 // Check Finders
 // ============================================================================
 
-/**
- * Find all checks in a specific scope.
- *
- * @param inv - The investigation to search
- * @param scope - Check scope
- * @returns Array of checks in the scope
- *
- * @example
- * ```ts
- * const emailChecks = findChecksByScope(investigation, "email_headers");
- * ```
- */
-export function findChecksByScope(
-  inv: CyvestInvestigation,
-  scope: string
-): Check[] {
-  const normalizedScope = scope.trim().toLowerCase();
-
-  // Try direct lookup first
-  if (inv.checks[scope]) {
-    return inv.checks[scope];
-  }
-
-  // Fallback to normalized search
-  for (const [key, checks] of Object.entries(inv.checks)) {
-    if (key.toLowerCase() === normalizedScope) {
-      return checks;
-    }
-  }
-
-  return [];
-}
-
 /**
  * Find all checks at a specific level.
  *
@@ -231,15 +198,7 @@ export function findChecksByLevel(
   inv: CyvestInvestigation,
   level: Level
 ): Check[] {
-  const result: Check[] = [];
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.level === level) {
-        result.push(check);
-      }
-    }
-  }
-  return result;
+  return Object.values(inv.checks).filter((check) => check.level === level);
 }
 
 /**
@@ -253,39 +212,26 @@ export function findChecksAtLeast(
   inv: CyvestInvestigation,
   minLevel: Level
 ): Check[] {
-  const result: Check[] = [];
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (isLevelAtLeast(check.level, minLevel)) {
-        result.push(check);
-      }
-    }
-  }
-  return result;
+  return Object.values(inv.checks).filter((check) =>
+    isLevelAtLeast(check.level, minLevel)
+  );
 }
 
 /**
- * Find checks by check ID (across all scopes).
+ * Find checks by check name.
  *
  * @param inv - The investigation to search
- * @param checkId - Check identifier to search for
- * @returns Array of matching checks
+ * @param checkName - Check name to search for
+ * @returns The matching check or undefined
  */
-export function findChecksByCheckId(
+export function findCheckByName(
   inv: CyvestInvestigation,
-  checkId: string
-): Check[] {
-  const normalizedId = checkId.trim().toLowerCase();
-  const result: Check[] = [];
-
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.check_id.toLowerCase() === normalizedId) {
-        result.push(check);
-      }
-    }
-  }
-  return result;
+  checkName: string
+): Check | undefined {
+  const normalizedName = checkName.trim().toLowerCase();
+  return Object.values(inv.checks).find(
+    (check) => check.check_name.toLowerCase() === normalizedName
+  );
 }
 
 // ============================================================================
@@ -340,59 +286,51 @@ export function findThreatIntelAtLeast(
 }
 
 // ============================================================================
-// Container Finders
+// Tag Finders
 // ============================================================================
 
 /**
- * Find containers at a specific aggregated level.
+ * Find tags at a specific direct level.
  *
  * @param inv - The investigation to search
- * @param level - Aggregated level to filter by
- * @returns Array of matching containers
+ * @param level - Direct level to filter by
+ * @returns Array of matching tags
  */
-export function findContainersByLevel(
+export function findTagsByLevel(
   inv: CyvestInvestigation,
   level: Level
-): Container[] {
-  const result: Container[] = [];
-
-  function searchContainers(containers: Record<string, Container>): void {
-    for (const container of Object.values(containers)) {
-      if (container.aggregated_level === level) {
-        result.push(container);
-      }
-      searchContainers(container.sub_containers);
-    }
-  }
-
-  searchContainers(inv.containers);
-  return result;
+): Tag[] {
+  return Object.values(inv.tags).filter((tag) => tag.direct_level === level);
 }
 
 /**
- * Find containers at or above a minimum aggregated level.
+ * Find tags at or above a minimum direct level.
  *
  * @param inv - The investigation to search
- * @param minLevel - Minimum aggregated level
- * @returns Array of matching containers
+ * @param minLevel - Minimum direct level
+ * @returns Array of matching tags
  */
-export function findContainersAtLeast(
+export function findTagsAtLeast(
   inv: CyvestInvestigation,
   minLevel: Level
-): Container[] {
-  const result: Container[] = [];
-
-  function searchContainers(containers: Record<string, Container>): void {
-    for (const container of Object.values(containers)) {
-      if (isLevelAtLeast(container.aggregated_level, minLevel)) {
-        result.push(container);
-      }
-      searchContainers(container.sub_containers);
-    }
-  }
+): Tag[] {
+  return Object.values(inv.tags).filter((tag) =>
+    isLevelAtLeast(tag.direct_level, minLevel)
+  );
+}
 
-  searchContainers(inv.containers);
-  return result;
+/**
+ * Find tags by name pattern.
+ *
+ * @param inv - The investigation to search
+ * @param pattern - Pattern to match against tag names
+ * @returns Array of matching tags
+ */
+export function findTagsByNamePattern(
+  inv: CyvestInvestigation,
+  pattern: RegExp
+): Tag[] {
+  return Object.values(inv.tags).filter((tag) => pattern.test(tag.name));
 }
 
 // ============================================================================
@@ -400,7 +338,7 @@ export function findContainersAtLeast(
 // ============================================================================
 
 /**
- * Get all checks that generated or reference a specific observable.
+ * Find all checks that generated or reference a specific observable.
  *
  * @param inv - The investigation to search
  * @param observableKey - Key of the observable
@@ -408,27 +346,20 @@ export function findContainersAtLeast(
  *
  * @example
  * ```ts
- * const checks = getChecksForObservable(investigation, "obs:ipv4-addr:192.168.1.1");
+ * const checks = findChecksForObservable(investigation, "obs:ipv4-addr:192.168.1.1");
  * ```
  */
-export function getChecksForObservable(
+export function findChecksForObservable(
   inv: CyvestInvestigation,
   observableKey: string
 ): Check[] {
   const result: Check[] = [];
   const seen = new Set<string>();
-  const checkLookup = new Map<string, Check>();
-
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      checkLookup.set(check.key, check);
-    }
-  }
 
   const observable = inv.observables[observableKey];
   if (observable) {
     for (const checkKey of observable.check_links) {
-      const check = checkLookup.get(checkKey);
+      const check = inv.checks[checkKey];
       if (check && !seen.has(check.key)) {
         result.push(check);
         seen.add(check.key);
@@ -436,7 +367,7 @@ export function getChecksForObservable(
     }
   }
 
-  for (const check of checkLookup.values()) {
+  for (const check of Object.values(inv.checks)) {
     if (seen.has(check.key)) {
       continue;
     }
@@ -451,13 +382,13 @@ export function getChecksForObservable(
 }
 
 /**
- * Get all threat intel entries for a specific observable.
+ * Find all threat intel entries for a specific observable.
  *
  * @param inv - The investigation to search
  * @param observableKey - Key of the observable
  * @returns Array of threat intel for this observable
  */
-export function getThreatIntelsForObservable(
+export function findThreatIntelsForObservable(
   inv: CyvestInvestigation,
   observableKey: string
 ): ThreatIntel[] {
@@ -476,83 +407,71 @@ export function getThreatIntelsForObservable(
 }
 
 /**
- * Get all observables referenced by a specific check.
+ * Find all observables referenced by a specific check.
  *
  * @param inv - The investigation to search
  * @param checkKey - Key of the check
  * @returns Array of observables referenced by this check
  */
-export function getObservablesForCheck(
+export function findObservablesForCheck(
   inv: CyvestInvestigation,
   checkKey: string
 ): Observable[] {
-  // Find the check
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.key === checkKey) {
-        const keys = new Set<string>();
-        for (const link of check.observable_links) {
-          keys.add(link.observable_key);
-        }
-
-        return Array.from(keys)
-          .map((obsKey) => inv.observables[obsKey])
-          .filter((obs): obs is Observable => obs !== undefined);
-      }
+  const check = inv.checks[checkKey];
+  if (check) {
+    const keys = new Set<string>();
+    for (const link of check.observable_links) {
+      keys.add(link.observable_key);
     }
+
+    return Array.from(keys)
+      .map((obsKey) => inv.observables[obsKey])
+      .filter((obs): obs is Observable => obs !== undefined);
   }
   return [];
 }
 
 /**
- * Get all checks for a specific container.
+ * Find all checks for a specific tag.
  *
  * @param inv - The investigation to search
- * @param containerKey - Key of the container
- * @param recursive - Include checks from sub-containers (default: false)
- * @returns Array of checks in the container
+ * @param tagKey - Key of the tag
+ * @param recursive - Include checks from descendant tags (default: false)
+ * @returns Array of checks in the tag
  */
-export function getChecksForContainer(
+export function findChecksForTag(
   inv: CyvestInvestigation,
-  containerKey: string,
+  tagKey: string,
   recursive = false
 ): Check[] {
   const result: Check[] = [];
+  const tag = inv.tags[tagKey];
 
-  function findContainer(
-    containers: Record<string, Container>
-  ): Container | undefined {
-    for (const container of Object.values(containers)) {
-      if (container.key === containerKey) {
-        return container;
-      }
-      const found = findContainer(container.sub_containers);
-      if (found) return found;
+  if (!tag) {
+    return result;
+  }
+
+  // Get direct checks
+  for (const checkKey of tag.checks) {
+    const check = inv.checks[checkKey];
+    if (check) {
+      result.push(check);
     }
-    return undefined;
   }
 
-  function collectChecks(container: Container): void {
-    for (const checkKey of container.checks) {
-      for (const checks of Object.values(inv.checks)) {
-        for (const check of checks) {
-          if (check.key === checkKey) {
+  // If recursive, get checks from descendant tags
+  if (recursive) {
+    const prefix = tag.name + ":";
+    for (const otherTag of Object.values(inv.tags)) {
+      if (otherTag.name.startsWith(prefix)) {
+        for (const checkKey of otherTag.checks) {
+          const check = inv.checks[checkKey];
+          if (check) {
             result.push(check);
           }
         }
       }
     }
-
-    if (recursive) {
-      for (const subContainer of Object.values(container.sub_containers)) {
-        collectChecks(subContainer);
-      }
-    }
-  }
-
-  const container = findContainer(inv.containers);
-  if (container) {
-    collectChecks(container);
   }
 
   return result;
@@ -611,13 +530,13 @@ export function sortChecksByLevel(checks: Check[]): Check[] {
 // ============================================================================
 
 /**
- * Get the highest scoring observables.
+ * Find the highest scoring observables.
  *
  * @param inv - The investigation to search
  * @param n - Number of results to return (default: 10)
  * @returns Array of highest scoring observables
  */
-export function getHighestScoringObservables(
+export function findHighestScoringObservables(
   inv: CyvestInvestigation,
   n = 10
 ): Observable[] {
@@ -625,70 +544,66 @@ export function getHighestScoringObservables(
 }
 
 /**
- * Get the highest scoring checks.
+ * Find the highest scoring checks.
  *
  * @param inv - The investigation to search
  * @param n - Number of results to return (default: 10)
  * @returns Array of highest scoring checks
  */
-export function getHighestScoringChecks(
+export function findHighestScoringChecks(
   inv: CyvestInvestigation,
   n = 10
 ): Check[] {
-  const allChecks: Check[] = [];
-  for (const checks of Object.values(inv.checks)) {
-    allChecks.push(...checks);
-  }
-  return sortChecksByScore(allChecks).slice(0, n);
+  return sortChecksByScore(Object.values(inv.checks)).slice(0, n);
 }
 
 /**
- * Get all malicious observables (convenience function).
+ * Find all malicious observables (convenience function).
  *
  * @param inv - The investigation to search
  * @returns Array of malicious observables
  */
-export function getMaliciousObservables(inv: CyvestInvestigation): Observable[] {
+export function findMaliciousObservables(inv: CyvestInvestigation): Observable[] {
   return findObservablesByLevel(inv, "MALICIOUS");
 }
 
 /**
- * Get all suspicious observables (convenience function).
+ * Find all suspicious observables (convenience function).
  *
  * @param inv - The investigation to search
  * @returns Array of suspicious observables
  */
-export function getSuspiciousObservables(inv: CyvestInvestigation): Observable[] {
+export function findSuspiciousObservables(inv: CyvestInvestigation): Observable[] {
   return findObservablesByLevel(inv, "SUSPICIOUS");
 }
 
 /**
- * Get all malicious checks (convenience function).
+ * Find all malicious checks (convenience function).
  *
  * @param inv - The investigation to search
  * @returns Array of malicious checks
  */
-export function getMaliciousChecks(inv: CyvestInvestigation): Check[] {
+export function findMaliciousChecks(inv: CyvestInvestigation): Check[] {
   return findChecksByLevel(inv, "MALICIOUS");
 }
 
 /**
- * Get all suspicious checks (convenience function).
+ * Find all suspicious checks (convenience function).
  *
  * @param inv - The investigation to search
  * @returns Array of suspicious checks
  */
-export function getSuspiciousChecks(inv: CyvestInvestigation): Check[] {
+export function findSuspiciousChecks(inv: CyvestInvestigation): Check[] {
   return findChecksByLevel(inv, "SUSPICIOUS");
 }
 
 /**
- * Get all scopes that have checks.
+ * Get all check keys in the investigation.
  *
  * @param inv - The investigation
- * @returns Array of scope names
+ * @returns Array of check keys
  */
-export function getAllScopes(inv: CyvestInvestigation): string[] {
+export function getAllCheckKeys(inv: CyvestInvestigation): string[] {
   return Object.keys(inv.checks);
 }