@cyvest/cyvest-js 2.0.1

package/tests/graph.test.ts

@@ -0,0 +1,398 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import type { CyvestInvestigation } from "../src";
+import {
+  getRelatedObservables,
+  getObservableChildren,
+  getObservableParents,
+  getRelatedObservablesByType,
+  getObservableGraph,
+  findRootObservables,
+  findOrphanObservables,
+  findLeafObservables,
+  areConnected,
+  findPath,
+  getReachableObservables,
+  getAllRelationshipTypes,
+  countRelationshipsByType,
+  getRelationshipsForObservable,
+} from "../src";
+
+// Test fixture with relationships
+function createGraphTestInvestigation(): CyvestInvestigation {
+  return {
+    score: 5,
+    level: "MALICIOUS",
+    whitelisted: false,
+    whitelists: [],
+    observables: {
+      "obs:email-message:msg1": {
+        key: "obs:email-message:msg1",
+        type: "email-message",
+        value: "msg1",
+        internal: false,
+        whitelisted: false,
+        comment: "",
+        extra: null,
+        score: 0,
+        level: "INFO",
+        relationships: [
+          {
+            target_key: "obs:email-addr:sender@example.com",
+            relationship_type: "from",
+            direction: "outbound",
+          },
+          {
+            target_key: "obs:ipv4-addr:192.168.1.1",
+            relationship_type: "originated-from",
+            direction: "outbound",
+          },
+        ],
+        threat_intels: [],
+        generated_by_checks: [],
+      },
+      "obs:email-addr:sender@example.com": {
+        key: "obs:email-addr:sender@example.com",
+        type: "email-addr",
+        value: "sender@example.com",
+        internal: false,
+        whitelisted: false,
+        comment: "",
+        extra: null,
+        score: 0,
+        level: "INFO",
+        relationships: [
+          {
+            target_key: "obs:domain-name:example.com",
+            relationship_type: "related-to",
+            direction: "outbound",
+          },
+        ],
+        threat_intels: [],
+        generated_by_checks: [],
+      },
+      "obs:ipv4-addr:192.168.1.1": {
+        key: "obs:ipv4-addr:192.168.1.1",
+        type: "ipv4-addr",
+        value: "192.168.1.1",
+        internal: true,
+        whitelisted: false,
+        comment: "",
+        extra: null,
+        score: 0,
+        level: "INFO",
+        relationships: [],
+        threat_intels: [],
+        generated_by_checks: [],
+      },
+      "obs:domain-name:example.com": {
+        key: "obs:domain-name:example.com",
+        type: "domain-name",
+        value: "example.com",
+        internal: false,
+        whitelisted: false,
+        comment: "",
+        extra: null,
+        score: 5,
+        level: "MALICIOUS",
+        relationships: [],
+        threat_intels: [],
+        generated_by_checks: [],
+      },
+      "obs:file-hash:abc123": {
+        key: "obs:file-hash:abc123",
+        type: "file-hash",
+        value: "abc123",
+        internal: false,
+        whitelisted: false,
+        comment: "",
+        extra: null,
+        score: 3,
+        level: "SUSPICIOUS",
+        relationships: [],
+        threat_intels: [],
+        generated_by_checks: [],
+      },
+    },
+    checks: {},
+    checks_by_level: {},
+    threat_intels: {},
+    enrichments: {},
+    containers: {},
+    stats: {
+      total_observables: 5,
+      internal_observables: 1,
+      external_observables: 4,
+      whitelisted_observables: 0,
+      observables_by_type: {},
+      observables_by_level: {},
+      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: {},
+      threat_intel_by_level: {},
+      total_containers: 0,
+    },
+    stats_checks: {
+      checks: 0,
+      applied: 0,
+    },
+    data_extraction: {
+      root_type: "email-message",
+      score_mode: "max",
+    },
+  };
+}
+
+describe("Graph Traversal", () => {
+  let inv: CyvestInvestigation;
+
+  beforeEach(() => {
+    inv = createGraphTestInvestigation();
+  });
+
+  describe("getRelatedObservables", () => {
+    it("returns all directly connected observables", () => {
+      const related = getRelatedObservables(inv, "obs:email-message:msg1");
+      expect(related).toHaveLength(2);
+      const values = related.map((o) => o.value);
+      expect(values).toContain("sender@example.com");
+      expect(values).toContain("192.168.1.1");
+    });
+
+    it("returns empty array for non-existent observable", () => {
+      expect(getRelatedObservables(inv, "obs:missing:key")).toEqual([]);
+    });
+
+    it("includes inbound relationships", () => {
+      const related = getRelatedObservables(
+        inv,
+        "obs:email-addr:sender@example.com"
+      );
+      // Has outbound to domain and inbound from email message
+      expect(related.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe("getObservableChildren", () => {
+    it("returns outbound related observables", () => {
+      const children = getObservableChildren(inv, "obs:email-message:msg1");
+      expect(children).toHaveLength(2);
+    });
+
+    it("returns empty for leaf nodes", () => {
+      const children = getObservableChildren(inv, "obs:ipv4-addr:192.168.1.1");
+      expect(children).toHaveLength(0);
+    });
+  });
+
+  describe("getObservableParents", () => {
+    it("returns observables pointing to this one", () => {
+      const parents = getObservableParents(
+        inv,
+        "obs:email-addr:sender@example.com"
+      );
+      expect(parents).toHaveLength(1);
+      expect(parents[0].value).toBe("msg1");
+    });
+
+    it("returns empty for root nodes", () => {
+      const parents = getObservableParents(inv, "obs:email-message:msg1");
+      expect(parents).toHaveLength(0);
+    });
+  });
+
+  describe("getRelatedObservablesByType", () => {
+    it("filters by relationship type", () => {
+      const fromRelated = getRelatedObservablesByType(
+        inv,
+        "obs:email-message:msg1",
+        "from"
+      );
+      expect(fromRelated).toHaveLength(1);
+      expect(fromRelated[0].value).toBe("sender@example.com");
+    });
+  });
+
+  describe("getObservableGraph", () => {
+    it("returns correct node count", () => {
+      const graph = getObservableGraph(inv);
+      expect(graph.nodes).toHaveLength(5);
+    });
+
+    it("returns correct edge count", () => {
+      const graph = getObservableGraph(inv);
+      expect(graph.edges).toHaveLength(3);
+    });
+
+    it("nodes have correct structure", () => {
+      const graph = getObservableGraph(inv);
+      const emailNode = graph.nodes.find(
+        (n) => n.id === "obs:email-message:msg1"
+      );
+      expect(emailNode).toBeDefined();
+      expect(emailNode?.type).toBe("email-message");
+      expect(emailNode?.value).toBe("msg1");
+      expect(emailNode?.level).toBe("INFO");
+    });
+
+    it("edges have correct structure", () => {
+      const graph = getObservableGraph(inv);
+      const fromEdge = graph.edges.find((e) => e.type === "from");
+      expect(fromEdge).toBeDefined();
+      expect(fromEdge?.source).toBe("obs:email-message:msg1");
+      expect(fromEdge?.target).toBe("obs:email-addr:sender@example.com");
+    });
+  });
+
+  describe("findRootObservables", () => {
+    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);
+      expect(values).toContain("msg1");
+      expect(values).toContain("abc123");
+    });
+  });
+
+  describe("findOrphanObservables", () => {
+    it("finds observables with no relationships", () => {
+      const orphans = findOrphanObservables(inv);
+      // file-hash has no relationships
+      expect(orphans).toHaveLength(1);
+      expect(orphans[0].value).toBe("abc123");
+    });
+  });
+
+  describe("findLeafObservables", () => {
+    it("finds observables that are targets but have no outbound", () => {
+      const leaves = findLeafObservables(inv);
+      const values = leaves.map((o) => o.value);
+      expect(values).toContain("192.168.1.1");
+      expect(values).toContain("example.com");
+    });
+  });
+
+  describe("areConnected", () => {
+    it("returns true for directly connected", () => {
+      expect(
+        areConnected(inv, "obs:email-message:msg1", "obs:ipv4-addr:192.168.1.1")
+      ).toBe(true);
+    });
+
+    it("returns true for transitively connected", () => {
+      expect(
+        areConnected(
+          inv,
+          "obs:email-message:msg1",
+          "obs:domain-name:example.com"
+        )
+      ).toBe(true);
+    });
+
+    it("returns false for disconnected", () => {
+      expect(
+        areConnected(inv, "obs:file-hash:abc123", "obs:email-message:msg1")
+      ).toBe(false);
+    });
+
+    it("returns true for same node", () => {
+      expect(
+        areConnected(inv, "obs:email-message:msg1", "obs:email-message:msg1")
+      ).toBe(true);
+    });
+  });
+
+  describe("findPath", () => {
+    it("finds direct path", () => {
+      const path = findPath(
+        inv,
+        "obs:email-message:msg1",
+        "obs:ipv4-addr:192.168.1.1"
+      );
+      expect(path).toEqual([
+        "obs:email-message:msg1",
+        "obs:ipv4-addr:192.168.1.1",
+      ]);
+    });
+
+    it("finds transitive path", () => {
+      const path = findPath(
+        inv,
+        "obs:email-message:msg1",
+        "obs:domain-name:example.com"
+      );
+      expect(path).not.toBeNull();
+      expect(path?.length).toBe(3);
+      expect(path?.[0]).toBe("obs:email-message:msg1");
+      expect(path?.[path.length - 1]).toBe("obs:domain-name:example.com");
+    });
+
+    it("returns null for no path", () => {
+      const path = findPath(
+        inv,
+        "obs:file-hash:abc123",
+        "obs:email-message:msg1"
+      );
+      expect(path).toBeNull();
+    });
+
+    it("returns single node for same source/target", () => {
+      const path = findPath(
+        inv,
+        "obs:email-message:msg1",
+        "obs:email-message:msg1"
+      );
+      expect(path).toEqual(["obs:email-message:msg1"]);
+    });
+  });
+
+  describe("getReachableObservables", () => {
+    it("returns all reachable from start", () => {
+      const reachable = getReachableObservables(inv, "obs:email-message:msg1");
+      expect(reachable).toHaveLength(4); // msg1 + sender + ip + domain
+    });
+
+    it("respects max depth", () => {
+      const reachable = getReachableObservables(
+        inv,
+        "obs:email-message:msg1",
+        1
+      );
+      expect(reachable).toHaveLength(3); // msg1 + sender + ip (depth 1)
+    });
+  });
+
+  describe("getAllRelationshipTypes", () => {
+    it("returns unique relationship types", () => {
+      const types = getAllRelationshipTypes(inv);
+      expect(types).toContain("from");
+      expect(types).toContain("originated-from");
+      expect(types).toContain("related-to");
+    });
+  });
+
+  describe("countRelationshipsByType", () => {
+    it("counts relationships by type", () => {
+      const counts = countRelationshipsByType(inv);
+      expect(counts["from"]).toBe(1);
+      expect(counts["originated-from"]).toBe(1);
+      expect(counts["related-to"]).toBe(1);
+    });
+  });
+
+  describe("getRelationshipsForObservable", () => {
+    it("returns outbound and inbound relationships", () => {
+      const rels = getRelationshipsForObservable(
+        inv,
+        "obs:email-addr:sender@example.com"
+      );
+      expect(rels.outbound).toHaveLength(1);
+      expect(rels.inbound).toHaveLength(1);
+      expect(rels.all.length).toBe(2);
+    });
+  });
+});

package/tests/keys-levels.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect } from "vitest";
+import {
+  // Keys
+  generateObservableKey,
+  generateCheckKey,
+  generateThreatIntelKey,
+  generateEnrichmentKey,
+  generateContainerKey,
+  parseKeyType,
+  validateKey,
+  parseObservableKey,
+  parseCheckKey,
+  parseThreatIntelKey,
+  // Levels
+  normalizeLevel,
+  isValidLevel,
+  getLevelFromScore,
+  compareLevels,
+  isLevelHigherThan,
+  isLevelAtLeast,
+  maxLevel,
+  minLevel,
+  LEVEL_ORDER,
+  LEVEL_VALUES,
+} from "../src";
+
+describe("Key Generation", () => {
+  describe("generateObservableKey", () => {
+    it("generates correct observable key", () => {
+      expect(generateObservableKey("ipv4-addr", "192.168.1.1")).toBe(
+        "obs:ipv4-addr:192.168.1.1"
+      );
+    });
+
+    it("normalizes to lowercase", () => {
+      expect(generateObservableKey("IPV4-ADDR", "192.168.1.1")).toBe(
+        "obs:ipv4-addr:192.168.1.1"
+      );
+    });
+
+    it("trims whitespace", () => {
+      expect(generateObservableKey("  ipv4-addr  ", "  192.168.1.1  ")).toBe(
+        "obs:ipv4-addr:192.168.1.1"
+      );
+    });
+  });
+
+  describe("generateCheckKey", () => {
+    it("generates correct check key", () => {
+      expect(generateCheckKey("sender_verification", "email_headers")).toBe(
+        "chk:sender_verification:email_headers"
+      );
+    });
+  });
+
+  describe("generateThreatIntelKey", () => {
+    it("generates correct threat intel key", () => {
+      expect(
+        generateThreatIntelKey("virustotal", "obs:ipv4-addr:192.168.1.1")
+      ).toBe("ti:virustotal:obs:ipv4-addr:192.168.1.1");
+    });
+  });
+
+  describe("generateEnrichmentKey", () => {
+    it("generates key without context", () => {
+      expect(generateEnrichmentKey("whois_data")).toBe("enr:whois_data");
+    });
+
+    it("generates key with context hash", () => {
+      const key = generateEnrichmentKey("whois_data", "example.com");
+      expect(key).toMatch(/^enr:whois_data:[a-f0-9]+$/);
+    });
+  });
+
+  describe("generateContainerKey", () => {
+    it("generates correct container key", () => {
+      expect(generateContainerKey("email/headers")).toBe("ctr:email/headers");
+    });
+
+    it("normalizes path separators", () => {
+      expect(generateContainerKey("email\\headers")).toBe("ctr:email/headers");
+    });
+
+    it("strips leading/trailing slashes", () => {
+      expect(generateContainerKey("/email/headers/")).toBe("ctr:email/headers");
+    });
+  });
+
+  describe("parseKeyType", () => {
+    it("parses observable key type", () => {
+      expect(parseKeyType("obs:ipv4-addr:192.168.1.1")).toBe("obs");
+    });
+
+    it("parses check key type", () => {
+      expect(parseKeyType("chk:sender:email")).toBe("chk");
+    });
+
+    it("parses threat intel key type", () => {
+      expect(parseKeyType("ti:vt:obs:ip:1.1.1.1")).toBe("ti");
+    });
+
+    it("parses enrichment key type", () => {
+      expect(parseKeyType("enr:whois")).toBe("enr");
+    });
+
+    it("parses container key type", () => {
+      expect(parseKeyType("ctr:email/body")).toBe("ctr");
+    });
+
+    it("returns null for invalid key", () => {
+      expect(parseKeyType("invalid")).toBeNull();
+      expect(parseKeyType("foo:bar")).toBeNull();
+    });
+  });
+
+  describe("validateKey", () => {
+    it("validates correct keys", () => {
+      expect(validateKey("obs:ipv4-addr:192.168.1.1")).toBe(true);
+      expect(validateKey("chk:sender:email")).toBe(true);
+    });
+
+    it("validates key type", () => {
+      expect(validateKey("obs:ipv4-addr:192.168.1.1", "obs")).toBe(true);
+      expect(validateKey("obs:ipv4-addr:192.168.1.1", "chk")).toBe(false);
+    });
+
+    it("rejects invalid keys", () => {
+      expect(validateKey("")).toBe(false);
+      expect(validateKey("invalid")).toBe(false);
+      expect(validateKey("foo:bar")).toBe(false);
+    });
+  });
+
+  describe("parseObservableKey", () => {
+    it("parses observable key components", () => {
+      expect(parseObservableKey("obs:ipv4-addr:192.168.1.1")).toEqual({
+        type: "ipv4-addr",
+        value: "192.168.1.1",
+      });
+    });
+
+    it("handles values with colons", () => {
+      expect(parseObservableKey("obs:url:http://example.com:8080")).toEqual({
+        type: "url",
+        value: "http://example.com:8080",
+      });
+    });
+
+    it("returns null for invalid key", () => {
+      expect(parseObservableKey("chk:sender:email")).toBeNull();
+    });
+  });
+
+  describe("parseCheckKey", () => {
+    it("parses check key components", () => {
+      expect(parseCheckKey("chk:sender_verification:email_headers")).toEqual({
+        checkId: "sender_verification",
+        scope: "email_headers",
+      });
+    });
+  });
+
+  describe("parseThreatIntelKey", () => {
+    it("parses threat intel key components", () => {
+      expect(
+        parseThreatIntelKey("ti:virustotal:obs:ipv4-addr:192.168.1.1")
+      ).toEqual({
+        source: "virustotal",
+        observableKey: "obs:ipv4-addr:192.168.1.1",
+      });
+    });
+  });
+});
+
+describe("Levels", () => {
+  describe("LEVEL_ORDER", () => {
+    it("has correct order", () => {
+      expect(LEVEL_ORDER).toEqual([
+        "NONE",
+        "TRUSTED",
+        "INFO",
+        "SAFE",
+        "NOTABLE",
+        "SUSPICIOUS",
+        "MALICIOUS",
+      ]);
+    });
+  });
+
+  describe("normalizeLevel", () => {
+    it("normalizes lowercase input", () => {
+      expect(normalizeLevel("malicious")).toBe("MALICIOUS");
+      expect(normalizeLevel("info")).toBe("INFO");
+    });
+
+    it("accepts uppercase input", () => {
+      expect(normalizeLevel("MALICIOUS")).toBe("MALICIOUS");
+    });
+
+    it("throws on invalid input", () => {
+      expect(() => normalizeLevel("invalid")).toThrow("Invalid level name");
+    });
+  });
+
+  describe("isValidLevel", () => {
+    it("returns true for valid levels", () => {
+      expect(isValidLevel("MALICIOUS")).toBe(true);
+      expect(isValidLevel("info")).toBe(true);
+    });
+
+    it("returns false for invalid levels", () => {
+      expect(isValidLevel("invalid")).toBe(false);
+    });
+  });
+
+  describe("getLevelFromScore", () => {
+    it("returns TRUSTED for negative scores", () => {
+      expect(getLevelFromScore(-1)).toBe("TRUSTED");
+      expect(getLevelFromScore(-0.5)).toBe("TRUSTED");
+    });
+
+    it("returns INFO for zero", () => {
+      expect(getLevelFromScore(0)).toBe("INFO");
+    });
+
+    it("returns NOTABLE for scores < 3", () => {
+      expect(getLevelFromScore(0.1)).toBe("NOTABLE");
+      expect(getLevelFromScore(2.9)).toBe("NOTABLE");
+    });
+
+    it("returns SUSPICIOUS for scores < 5", () => {
+      expect(getLevelFromScore(3)).toBe("SUSPICIOUS");
+      expect(getLevelFromScore(4.9)).toBe("SUSPICIOUS");
+    });
+
+    it("returns MALICIOUS for scores >= 5", () => {
+      expect(getLevelFromScore(5)).toBe("MALICIOUS");
+      expect(getLevelFromScore(10)).toBe("MALICIOUS");
+    });
+  });
+
+  describe("compareLevels", () => {
+    it("returns -1 when a < b", () => {
+      expect(compareLevels("INFO", "MALICIOUS")).toBe(-1);
+    });
+
+    it("returns 1 when a > b", () => {
+      expect(compareLevels("MALICIOUS", "INFO")).toBe(1);
+    });
+
+    it("returns 0 when a === b", () => {
+      expect(compareLevels("INFO", "INFO")).toBe(0);
+    });
+  });
+
+  describe("isLevelHigherThan", () => {
+    it("returns true when a is more severe", () => {
+      expect(isLevelHigherThan("MALICIOUS", "SUSPICIOUS")).toBe(true);
+      expect(isLevelHigherThan("SUSPICIOUS", "INFO")).toBe(true);
+    });
+
+    it("returns false when a is less severe or equal", () => {
+      expect(isLevelHigherThan("INFO", "MALICIOUS")).toBe(false);
+      expect(isLevelHigherThan("INFO", "INFO")).toBe(false);
+    });
+  });
+
+  describe("isLevelAtLeast", () => {
+    it("returns true when a >= minLevel", () => {
+      expect(isLevelAtLeast("MALICIOUS", "SUSPICIOUS")).toBe(true);
+      expect(isLevelAtLeast("SUSPICIOUS", "SUSPICIOUS")).toBe(true);
+    });
+
+    it("returns false when a < minLevel", () => {
+      expect(isLevelAtLeast("INFO", "SUSPICIOUS")).toBe(false);
+    });
+  });
+
+  describe("maxLevel", () => {
+    it("returns most severe level", () => {
+      expect(maxLevel(["INFO", "MALICIOUS", "SUSPICIOUS"])).toBe("MALICIOUS");
+    });
+
+    it("returns NONE for empty array", () => {
+      expect(maxLevel([])).toBe("NONE");
+    });
+  });
+
+  describe("minLevel", () => {
+    it("returns least severe level", () => {
+      expect(minLevel(["INFO", "MALICIOUS", "SUSPICIOUS"])).toBe("INFO");
+    });
+
+    it("returns MALICIOUS for empty array", () => {
+      expect(minLevel([])).toBe("MALICIOUS");
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"]
+}