@cyvest/cyvest-js 4.4.1 → 5.0.0

package/src/types.generated.ts

@@ -81,7 +81,7 @@ export interface CyvestInvestigation {
   checks: Checks;
   threat_intels: ThreatIntels1;
   enrichments: Enrichments;
-  containers: Containers;
+  tags: Tags;
   stats: StatisticsSchema;
   data_extraction: DataExtractionSchema;
   /**
@@ -157,10 +157,10 @@ export interface Relationship {
   [k: string]: unknown;
 }
 /**
- * Checks organized by scope.
+ * Checks keyed by their unique key.
  */
 export interface Checks {
-  [k: string]: Check[];
+  [k: string]: Check;
 }
 /**
  * Represents a verification step in the investigation.
@@ -169,8 +169,7 @@ export interface Checks {
  * and contributes to the overall investigation score.
  */
 export interface Check {
-  check_id: string;
-  scope: string;
+  check_name: string;
   description: string;
   comment: string;
   extra: Extra1;
@@ -250,28 +249,34 @@ export interface Data {
   [k: string]: unknown;
 }
 /**
- * Containers keyed by their unique key.
+ * Tags keyed by their unique key.
  */
-export interface Containers {
-  [k: string]: Container;
+export interface Tags {
+  [k: string]: Tag;
 }
 /**
- * Groups checks and sub-containers for hierarchical organization.
+ * Groups checks for categorical organization.
  *
- * Containers allow structuring the investigation into logical sections
- * with aggregated scores and levels.
+ * Tags allow structuring the investigation into logical sections
+ * with aggregated scores and levels. Hierarchy is automatic based on
+ * the ":" delimiter in tag names (e.g., "header:auth:dkim").
  */
-export interface Container {
-  path: string;
+export interface Tag {
+  name: string;
   description?: string;
   checks: Checks1;
-  sub_containers: SubContainers;
   key: string;
-  aggregated_score: number;
-  aggregated_level: Level;
-}
-export interface SubContainers {
-  [k: string]: Container;
+  /**
+   * Calculate the score from direct checks only (no hierarchy).
+   *
+   * For hierarchical aggregation (including descendant tags), use
+   * Investigation.get_tag_aggregated_score() or TagProxy.get_aggregated_score().
+   *
+   * Returns:
+   *     Total score from direct checks
+   */
+  direct_score: number;
+  direct_level: Level;
 }
 /**
  * Schema for investigation statistics.
@@ -288,12 +293,11 @@ export interface StatisticsSchema {
   observables_by_type_and_level?: ObservablesByTypeAndLevel;
   total_checks: number;
   applied_checks: number;
-  checks_by_scope?: ChecksByScope;
   checks_by_level?: ChecksByLevel;
   total_threat_intel: number;
   threat_intel_by_source?: ThreatIntelBySource;
   threat_intel_by_level?: ThreatIntelByLevel;
-  total_containers: number;
+  total_tags: number;
 }
 export interface ObservablesByType {
   [k: string]: number;
@@ -306,9 +310,6 @@ export interface ObservablesByTypeAndLevel {
     [k: string]: number;
   };
 }
-export interface ChecksByScope {
-  [k: string]: string[];
-}
 export interface ChecksByLevel {
   [k: string]: string[];
 }

package/tests/getters-finders.test.ts

@@ -5,7 +5,7 @@ import {
   getObservable,
   getObservableByTypeValue,
   getCheck,
-  getCheckByIdScope,
+  getCheckByName,
   getAllChecks,
   getThreatIntel,
   getThreatIntelBySourceObservable,
@@ -13,12 +13,16 @@ import {
   getEnrichment,
   getEnrichmentByName,
   getAllEnrichments,
-  getContainer,
-  getContainerByPath,
-  getAllContainers,
+  getTag,
+  getTagByName,
+  getAllTags,
   getAllObservables,
   getCounts,
   getStartedAt,
+  getTagChildren,
+  getTagDescendants,
+  getTagAggregatedScore,
+  getTagAggregatedLevel,
   // Finders
   findObservablesByType,
   findObservablesByLevel,
@@ -26,16 +30,15 @@ import {
   findObservablesByValue,
   findInternalObservables,
   findWhitelistedObservables,
-  findChecksByScope,
   findChecksByLevel,
   findChecksAtLeast,
   findThreatIntelBySource,
-  getChecksForObservable,
-  getThreatIntelsForObservable,
-  getObservablesForCheck,
-  getHighestScoringObservables,
-  getMaliciousObservables,
-  getAllScopes,
+  findChecksForObservable,
+  findThreatIntelsForObservable,
+  findObservablesForCheck,
+  findHighestScoringObservables,
+  findMaliciousObservables,
+  getAllCheckKeys,
   getAllObservableTypes,
 } from "../src";
 
@@ -133,57 +136,50 @@ function createTestInvestigation(): CyvestInvestigation {
       },
     },
     checks: {
-      network: [
-        {
-          key: "chk:ip_check:network",
-          check_id: "ip_check",
-          scope: "network",
-          description: "IP address check",
-          comment: "",
-          extra: {},
-          score: 0,
-          score_display: "0.00",
-          level: "INFO",
-          origin_investigation_id: "01HXYZTESTINVESTIGATION",
-          observable_links: [
-            {
-              observable_key: "obs:ipv4-addr:192.168.1.1",
-            },
-          ],
-        },
-      ],
-      dns: [
-        {
-          key: "chk:domain_check:dns",
-          check_id: "domain_check",
-          scope: "dns",
-          description: "Domain reputation check",
-          comment: "",
-          extra: {},
-          score: 5,
-          score_display: "5.00",
-          level: "MALICIOUS",
-          origin_investigation_id: "01HXYZTESTINVESTIGATION",
-          observable_links: [
-            {
-              observable_key: "obs:domain-name:example.com",
-            },
-          ],
-        },
-        {
-          key: "chk:dns_lookup:dns",
-          check_id: "dns_lookup",
-          scope: "dns",
-          description: "DNS lookup",
-          comment: "",
-          extra: {},
-          score: 0,
-          score_display: "0.00",
-          level: "INFO",
-          origin_investigation_id: "01HXYZTESTINVESTIGATION",
-          observable_links: [],
-        },
-      ],
+      "chk:ip_check": {
+        key: "chk:ip_check",
+        check_name: "ip_check",
+        description: "IP address check",
+        comment: "",
+        extra: {},
+        score: 0,
+        score_display: "0.00",
+        level: "INFO",
+        origin_investigation_id: "01HXYZTESTINVESTIGATION",
+        observable_links: [
+          {
+            observable_key: "obs:ipv4-addr:192.168.1.1",
+          },
+        ],
+      },
+      "chk:domain_check": {
+        key: "chk:domain_check",
+        check_name: "domain_check",
+        description: "Domain reputation check",
+        comment: "",
+        extra: {},
+        score: 5,
+        score_display: "5.00",
+        level: "MALICIOUS",
+        origin_investigation_id: "01HXYZTESTINVESTIGATION",
+        observable_links: [
+          {
+            observable_key: "obs:domain-name:example.com",
+          },
+        ],
+      },
+      "chk:dns_lookup": {
+        key: "chk:dns_lookup",
+        check_name: "dns_lookup",
+        description: "DNS lookup",
+        comment: "",
+        extra: {},
+        score: 0,
+        score_display: "0.00",
+        level: "INFO",
+        origin_investigation_id: "01HXYZTESTINVESTIGATION",
+        observable_links: [],
+      },
     },
     threat_intels: {
       "ti:virustotal:obs:domain-name:example.com": {
@@ -206,25 +202,38 @@ function createTestInvestigation(): CyvestInvestigation {
         context: "example.com",
       },
     },
-    containers: {
-      "ctr:email": {
-        key: "ctr:email",
-        path: "email",
-        description: "Email container",
+    tags: {
+      "tag:email": {
+        key: "tag:email",
+        name: "email",
+        description: "Email tag",
         checks: [],
-        sub_containers: {
-          "ctr:email/headers": {
-            key: "ctr:email/headers",
-            path: "email/headers",
-            description: "Email headers",
-            checks: ["chk:ip_check:network"],
-            sub_containers: {},
-            aggregated_score: 0,
-            aggregated_level: "INFO",
-          },
-        },
-        aggregated_score: 0,
-        aggregated_level: "INFO",
+        direct_score: 1.5,
+        direct_level: "NOTABLE",
+      },
+      "tag:email:headers": {
+        key: "tag:email:headers",
+        name: "email:headers",
+        description: "Email headers",
+        checks: ["chk:ip_check"],
+        direct_score: 2.0,
+        direct_level: "NOTABLE",
+      },
+      "tag:email:headers:auth": {
+        key: "tag:email:headers:auth",
+        name: "email:headers:auth",
+        description: "Auth headers",
+        checks: [],
+        direct_score: 3.5,
+        direct_level: "SUSPICIOUS",
+      },
+      "tag:email:body": {
+        key: "tag:email:body",
+        name: "email:body",
+        description: "Email body",
+        checks: [],
+        direct_score: 1.0,
+        direct_level: "NOTABLE",
       },
     },
     stats: {
@@ -237,12 +246,11 @@ function createTestInvestigation(): CyvestInvestigation {
       observables_by_type_and_level: {},
       total_checks: 3,
       applied_checks: 2,
-      checks_by_scope: { network: ["chk:ip_check:network"], dns: ["chk:domain_check:dns", "chk:dns_lookup:dns"] },
-      checks_by_level: { INFO: ["chk:ip_check:network", "chk:dns_lookup:dns"], MALICIOUS: ["chk:domain_check:dns"] },
+      checks_by_level: { INFO: ["chk:ip_check", "chk:dns_lookup"], MALICIOUS: ["chk:domain_check"] },
       total_threat_intel: 1,
       threat_intel_by_source: { virustotal: 1 },
       threat_intel_by_level: { MALICIOUS: 1 },
-      total_containers: 2,
+      total_tags: 4,
     },
     data_extraction: {
       root_type: "file",
@@ -285,17 +293,17 @@ describe("Getters", () => {
 
   describe("getCheck", () => {
     it("returns check by key", () => {
-      const check = getCheck(inv, "chk:domain_check:dns");
+      const check = getCheck(inv, "chk:domain_check");
       expect(check).toBeDefined();
-      expect(check?.check_id).toBe("domain_check");
+      expect(check?.check_name).toBe("domain_check");
     });
   });
 
-  describe("getCheckByIdScope", () => {
-    it("finds check by id and scope", () => {
-      const check = getCheckByIdScope(inv, "domain_check", "dns");
+  describe("getCheckByName", () => {
+    it("finds check by name", () => {
+      const check = getCheckByName(inv, "domain_check");
       expect(check).toBeDefined();
-      expect(check?.key).toBe("chk:domain_check:dns");
+      expect(check?.key).toBe("chk:domain_check");
     });
   });
 
@@ -317,24 +325,24 @@ describe("Getters", () => {
     });
   });
 
-  describe("getContainer", () => {
-    it("returns top-level container", () => {
-      const container = getContainer(inv, "ctr:email");
-      expect(container).toBeDefined();
-      expect(container?.path).toBe("email");
+  describe("getTag", () => {
+    it("returns tag by key", () => {
+      const tag = getTag(inv, "tag:email");
+      expect(tag).toBeDefined();
+      expect(tag?.name).toBe("email");
     });
 
-    it("returns nested container", () => {
-      const container = getContainer(inv, "ctr:email/headers");
-      expect(container).toBeDefined();
-      expect(container?.path).toBe("email/headers");
+    it("returns nested tag", () => {
+      const tag = getTag(inv, "tag:email:headers");
+      expect(tag).toBeDefined();
+      expect(tag?.name).toBe("email:headers");
     });
   });
 
-  describe("getAllContainers", () => {
-    it("returns all containers including nested", () => {
-      const containers = getAllContainers(inv);
-      expect(containers).toHaveLength(2);
+  describe("getAllTags", () => {
+    it("returns all tags", () => {
+      const tags = getAllTags(inv);
+      expect(tags).toHaveLength(4);
     });
   });
 
@@ -345,7 +353,7 @@ describe("Getters", () => {
       expect(counts.checks).toBe(3);
       expect(counts.threatIntels).toBe(1);
       expect(counts.enrichments).toBe(1);
-      expect(counts.containers).toBe(2);
+      expect(counts.tags).toBe(4);
       expect(counts.whitelists).toBe(1);
     });
   });
@@ -419,13 +427,6 @@ describe("Finders", () => {
     });
   });
 
-  describe("findChecksByScope", () => {
-    it("finds checks in scope", () => {
-      const dnsChecks = findChecksByScope(inv, "dns");
-      expect(dnsChecks).toHaveLength(2);
-    });
-  });
-
   describe("findChecksByLevel", () => {
     it("finds checks at level", () => {
       const malicious = findChecksByLevel(inv, "MALICIOUS");
@@ -440,17 +441,17 @@ describe("Finders", () => {
     });
   });
 
-  describe("getChecksForObservable", () => {
+  describe("findChecksForObservable", () => {
     it("finds checks that reference observable", () => {
-      const checks = getChecksForObservable(inv, "obs:ipv4-addr:192.168.1.1");
+      const checks = findChecksForObservable(inv, "obs:ipv4-addr:192.168.1.1");
       expect(checks).toHaveLength(1);
-      expect(checks[0].check_id).toBe("ip_check");
+      expect(checks[0].check_name).toBe("ip_check");
     });
   });
 
-  describe("getThreatIntelsForObservable", () => {
+  describe("findThreatIntelsForObservable", () => {
     it("finds threat intel for observable", () => {
-      const tis = getThreatIntelsForObservable(
+      const tis = findThreatIntelsForObservable(
         inv,
         "obs:domain-name:example.com"
       );
@@ -459,34 +460,34 @@ describe("Finders", () => {
     });
   });
 
-  describe("getObservablesForCheck", () => {
+  describe("findObservablesForCheck", () => {
     it("finds observables referenced by check", () => {
-      const obs = getObservablesForCheck(inv, "chk:ip_check:network");
+      const obs = findObservablesForCheck(inv, "chk:ip_check");
       expect(obs).toHaveLength(1);
       expect(obs[0].value).toBe("192.168.1.1");
     });
   });
 
-  describe("getHighestScoringObservables", () => {
+  describe("findHighestScoringObservables", () => {
     it("returns top scoring observables", () => {
-      const top = getHighestScoringObservables(inv, 2);
+      const top = findHighestScoringObservables(inv, 2);
       expect(top).toHaveLength(2);
       expect(top[0].score).toBeGreaterThanOrEqual(top[1].score);
     });
   });
 
-  describe("getMaliciousObservables", () => {
+  describe("findMaliciousObservables", () => {
     it("returns malicious observables", () => {
-      const mal = getMaliciousObservables(inv);
+      const mal = findMaliciousObservables(inv);
       expect(mal).toHaveLength(2);
     });
   });
 
-  describe("getAllScopes", () => {
-    it("returns all scopes", () => {
-      const scopes = getAllScopes(inv);
-      expect(scopes).toContain("network");
-      expect(scopes).toContain("dns");
+  describe("getAllCheckKeys", () => {
+    it("returns all check keys", () => {
+      const keys = getAllCheckKeys(inv);
+      expect(keys).toContain("chk:ip_check");
+      expect(keys).toContain("chk:domain_check");
     });
   });
 
@@ -498,4 +499,102 @@ describe("Finders", () => {
       expect(types).toContain("url");
     });
   });
+
+  // Tag Aggregation Tests
+  describe("getTagChildren", () => {
+    it("returns direct children of a tag", () => {
+      const children = getTagChildren(inv, "email");
+      expect(children).toHaveLength(2);
+      const names = children.map((t) => t.name);
+      expect(names).toContain("email:headers");
+      expect(names).toContain("email:body");
+    });
+
+    it("does not return grandchildren", () => {
+      const children = getTagChildren(inv, "email");
+      const names = children.map((t) => t.name);
+      expect(names).not.toContain("email:headers:auth");
+    });
+
+    it("returns empty array for leaf tag", () => {
+      const children = getTagChildren(inv, "email:headers:auth");
+      expect(children).toHaveLength(0);
+    });
+
+    it("returns empty array for non-existent tag", () => {
+      const children = getTagChildren(inv, "nonexistent");
+      expect(children).toHaveLength(0);
+    });
+  });
+
+  describe("getTagDescendants", () => {
+    it("returns all descendants of a tag", () => {
+      const descendants = getTagDescendants(inv, "email");
+      expect(descendants).toHaveLength(3);
+      const names = descendants.map((t) => t.name);
+      expect(names).toContain("email:headers");
+      expect(names).toContain("email:headers:auth");
+      expect(names).toContain("email:body");
+    });
+
+    it("returns children and grandchildren", () => {
+      const descendants = getTagDescendants(inv, "email:headers");
+      expect(descendants).toHaveLength(1);
+      expect(descendants[0].name).toBe("email:headers:auth");
+    });
+
+    it("returns empty array for leaf tag", () => {
+      const descendants = getTagDescendants(inv, "email:headers:auth");
+      expect(descendants).toHaveLength(0);
+    });
+  });
+
+  describe("getTagAggregatedScore", () => {
+    it("returns aggregated score including all descendants", () => {
+      // email (1.5) + email:headers (2.0) + email:headers:auth (3.5) + email:body (1.0) = 8.0
+      const score = getTagAggregatedScore(inv, "email");
+      expect(score).toBe(8.0);
+    });
+
+    it("returns aggregated score for intermediate tag", () => {
+      // email:headers (2.0) + email:headers:auth (3.5) = 5.5
+      const score = getTagAggregatedScore(inv, "email:headers");
+      expect(score).toBe(5.5);
+    });
+
+    it("returns direct score for leaf tag", () => {
+      const score = getTagAggregatedScore(inv, "email:headers:auth");
+      expect(score).toBe(3.5);
+    });
+
+    it("returns 0 for non-existent tag", () => {
+      const score = getTagAggregatedScore(inv, "nonexistent");
+      expect(score).toBe(0);
+    });
+  });
+
+  describe("getTagAggregatedLevel", () => {
+    it("returns level based on aggregated score", () => {
+      // email aggregated score = 8.0 -> MALICIOUS (>= 5)
+      const level = getTagAggregatedLevel(inv, "email");
+      expect(level).toBe("MALICIOUS");
+    });
+
+    it("returns level for intermediate tag", () => {
+      // email:headers aggregated score = 5.5 -> MALICIOUS (>= 5)
+      const level = getTagAggregatedLevel(inv, "email:headers");
+      expect(level).toBe("MALICIOUS");
+    });
+
+    it("returns level for leaf tag", () => {
+      // email:headers:auth direct score = 3.5 -> SUSPICIOUS (3 <= x < 5)
+      const level = getTagAggregatedLevel(inv, "email:headers:auth");
+      expect(level).toBe("SUSPICIOUS");
+    });
+
+    it("returns INFO for non-existent tag (score 0)", () => {
+      const level = getTagAggregatedLevel(inv, "nonexistent");
+      expect(level).toBe("INFO");
+    });
+  });
 });

package/tests/graph.test.ts

@@ -6,7 +6,7 @@ import {
   getObservableParents,
   getRelatedObservablesByType,
   getObservableGraph,
-  findRootObservables,
+  findSourceObservables,
   findOrphanObservables,
   findLeafObservables,
   areConnected,
@@ -144,7 +144,6 @@ function createGraphTestInvestigation(): CyvestInvestigation {
       observables_by_type_and_level: {},
       total_checks: 0,
       applied_checks: 0,
-      checks_by_scope: {},
       checks_by_level: {},
       total_threat_intel: 0,
       threat_intel_by_source: {},
@@ -259,12 +258,12 @@ describe("Graph Traversal", () => {
     });
   });
 
-  describe("findRootObservables", () => {
+  describe("findSourceObservables", () => {
     it("finds observables with no incoming relationships", () => {
-      const roots = findRootObservables(inv);
-      // email-message and file-hash are roots
-      expect(roots.length).toBeGreaterThanOrEqual(2);
-      const values = roots.map((o) => o.value);
+      const sources = findSourceObservables(inv);
+      // email-message and file-hash are sources
+      expect(sources.length).toBeGreaterThanOrEqual(2);
+      const values = sources.map((o) => o.value);
       expect(values).toContain("msg1");
       expect(values).toContain("abc123");
     });