@cyvest/cyvest-js 3.2.0 → 4.0.0

package/dist/index.mjs

@@ -5,6 +5,97 @@ import addFormats from "ajv-formats";
 // ../../../schema/cyvest.schema.json
 var cyvest_schema_default = {
   $defs: {
+    AuditEvent: {
+      additionalProperties: true,
+      description: "Centralized audit event for investigation-level changes.",
+      properties: {
+        event_id: {
+          title: "Event Id",
+          type: "string"
+        },
+        timestamp: {
+          format: "date-time",
+          title: "Timestamp",
+          type: "string"
+        },
+        event_type: {
+          title: "Event Type",
+          type: "string"
+        },
+        actor: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Actor"
+        },
+        reason: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Reason"
+        },
+        tool: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Tool"
+        },
+        object_type: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Object Type"
+        },
+        object_key: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Object Key"
+        },
+        details: {
+          additionalProperties: true,
+          title: "Details",
+          type: "object"
+        }
+      },
+      required: [
+        "event_id",
+        "timestamp",
+        "event_type"
+      ],
+      title: "AuditEvent",
+      type: "object"
+    },
     Check: {
       description: "Represents a verification step in the investigation.\n\nA check validates a specific aspect of the data under investigation\nand contributes to the overall investigation score.",
       properties: {
@@ -36,17 +127,17 @@ var cyvest_schema_default = {
         level: {
           $ref: "#/$defs/Level"
         },
-        observables: {
+        origin_investigation_id: {
+          title: "Origin Investigation Id",
+          type: "string"
+        },
+        observable_links: {
           items: {
-            type: "string"
+            $ref: "#/$defs/ObservableLink"
           },
-          title: "Observables",
+          title: "Observable Links",
           type: "array"
         },
-        score_policy: {
-          $ref: "#/$defs/CheckScorePolicy",
-          default: "auto"
-        },
         key: {
           title: "Key",
           type: "string"
@@ -65,22 +156,14 @@ var cyvest_schema_default = {
         "extra",
         "score",
         "level",
-        "observables",
+        "origin_investigation_id",
+        "observable_links",
         "key",
         "score_display"
       ],
       title: "Check",
       type: "object"
     },
-    CheckScorePolicy: {
-      description: "Controls how a check reacts to linked observables.",
-      enum: [
-        "auto",
-        "manual"
-      ],
-      title: "CheckScorePolicy",
-      type: "string"
-    },
     Container: {
       additionalProperties: false,
       description: "Groups checks and sub-containers for hierarchical organization.\n\nContainers allow structuring the investigation into logical sections\nwith aggregated scores and levels.",
@@ -290,13 +373,13 @@ var cyvest_schema_default = {
           title: "Key",
           type: "string"
         },
-        generated_by_checks: {
-          description: "Checks that generated this observable.",
+        check_links: {
+          description: "Checks that currently link to this observable (navigation-only).",
           items: {
             type: "string"
           },
           readOnly: true,
-          title: "Generated By Checks",
+          title: "Check Links",
           type: "array"
         },
         score_display: {
@@ -317,12 +400,40 @@ var cyvest_schema_default = {
         "threat_intels",
         "relationships",
         "key",
-        "generated_by_checks",
+        "check_links",
         "score_display"
       ],
       title: "Observable",
       type: "object"
     },
+    ObservableLink: {
+      additionalProperties: false,
+      description: "Edge metadata for a Check\u2194Observable association.",
+      properties: {
+        observable_key: {
+          title: "Observable Key",
+          type: "string"
+        },
+        propagation_mode: {
+          $ref: "#/$defs/PropagationMode",
+          default: "LOCAL_ONLY"
+        }
+      },
+      required: [
+        "observable_key"
+      ],
+      title: "ObservableLink",
+      type: "object"
+    },
+    PropagationMode: {
+      description: "Controls how a Check\u2194Observable link propagates across merged investigations.",
+      enum: [
+        "LOCAL_ONLY",
+        "GLOBAL"
+      ],
+      title: "PropagationMode",
+      type: "string"
+    },
     Relationship: {
       description: "Represents a relationship between observables.",
       properties: {
@@ -569,6 +680,24 @@ var cyvest_schema_default = {
   additionalProperties: false,
   description: "Schema for a complete serialized investigation.\n\nThis model describes the output of `serialize_investigation()` from\n`cyvest.io_serialization`. It is the top-level schema for exported investigations.\n\nEntity types reference the runtime models directly. When generating schemas with\n`mode='serialization'`, Pydantic respects field_serializer decorators and produces\nschemas matching the actual model_dump() output.",
   properties: {
+    investigation_id: {
+      description: "Stable investigation identity (ULID).",
+      title: "Investigation Id",
+      type: "string"
+    },
+    investigation_name: {
+      anyOf: [
+        {
+          type: "string"
+        },
+        {
+          type: "null"
+        }
+      ],
+      default: null,
+      description: "Optional human-readable investigation name.",
+      title: "Investigation Name"
+    },
     started_at: {
       description: "Investigation start time (UTC).",
       format: "date-time",
@@ -597,6 +726,14 @@ var cyvest_schema_default = {
       title: "Whitelists",
       type: "array"
     },
+    event_log: {
+      description: "Append-only investigation audit log.",
+      items: {
+        $ref: "#/$defs/AuditEvent"
+      },
+      title: "Event Log",
+      type: "array"
+    },
     observables: {
       additionalProperties: {
         $ref: "#/$defs/Observable"
@@ -671,6 +808,7 @@ var cyvest_schema_default = {
     }
   },
   required: [
+    "investigation_id",
     "started_at",
     "score",
     "level",
@@ -1165,17 +1303,6 @@ function findChecksByCheckId(inv, checkId) {
   }
   return result;
 }
-function findManuallyScored(inv) {
-  const result = [];
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.score_policy === "manual") {
-        result.push(check);
-      }
-    }
-  }
-  return result;
-}
 function findThreatIntelBySource(inv, source) {
   const normalizedSource = source.trim().toLowerCase();
   return Object.values(inv.threat_intels).filter(
@@ -1218,13 +1345,32 @@ function findContainersAtLeast(inv, minLevel2) {
 }
 function getChecksForObservable(inv, observableKey) {
   const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  const checkLookup = /* @__PURE__ */ new Map();
   for (const checks of Object.values(inv.checks)) {
     for (const check of checks) {
-      if (check.observables.includes(observableKey)) {
+      checkLookup.set(check.key, check);
+    }
+  }
+  const observable = inv.observables[observableKey];
+  if (observable) {
+    for (const checkKey of observable.check_links) {
+      const check = checkLookup.get(checkKey);
+      if (check && !seen.has(check.key)) {
         result.push(check);
+        seen.add(check.key);
       }
     }
   }
+  for (const check of checkLookup.values()) {
+    if (seen.has(check.key)) {
+      continue;
+    }
+    if (check.observable_links.some((link) => link.observable_key === observableKey)) {
+      result.push(check);
+      seen.add(check.key);
+    }
+  }
   return result;
 }
 function getThreatIntelsForObservable(inv, observableKey) {
@@ -1240,7 +1386,11 @@ function getObservablesForCheck(inv, checkKey) {
   for (const checks of Object.values(inv.checks)) {
     for (const check of checks) {
       if (check.key === checkKey) {
-        return check.observables.map((obsKey) => inv.observables[obsKey]).filter((obs) => obs !== void 0);
+        const keys = /* @__PURE__ */ new Set();
+        for (const link of check.observable_links) {
+          keys.add(link.observable_key);
+        }
+        return Array.from(keys).map((obsKey) => inv.observables[obsKey]).filter((obs) => obs !== void 0);
       }
     }
   }
@@ -1612,7 +1762,6 @@ export {
   findExternalObservables,
   findInternalObservables,
   findLeafObservables,
-  findManuallyScored,
   findObservablesAtLeast,
   findObservablesByLevel,
   findObservablesByType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -10,10 +10,10 @@
     "ajv-formats": "^3.0.1"
   },
   "devDependencies": {
-    "json-schema-to-typescript": "^13.1.1",
-    "tsup": "^8.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.0.0"
+    "json-schema-to-typescript": "^15.0.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "engines": {
     "node": ">=20"

package/src/finders.ts

@@ -288,24 +288,6 @@ export function findChecksByCheckId(
   return result;
 }
 
-/**
- * Find checks with score policy set to manual.
- *
- * @param inv - The investigation to search
- * @returns Array of manually scored checks
- */
-export function findManuallyScored(inv: CyvestInvestigation): Check[] {
-  const result: Check[] = [];
-  for (const checks of Object.values(inv.checks)) {
-    for (const check of checks) {
-      if (check.score_policy === "manual") {
-        result.push(check);
-      }
-    }
-  }
-  return result;
-}
-
 // ============================================================================
 // Threat Intel Finders
 // ============================================================================
@@ -434,15 +416,37 @@ export function getChecksForObservable(
   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) {
-      if (check.observables.includes(observableKey)) {
+      checkLookup.set(check.key, check);
+    }
+  }
+
+  const observable = inv.observables[observableKey];
+  if (observable) {
+    for (const checkKey of observable.check_links) {
+      const check = checkLookup.get(checkKey);
+      if (check && !seen.has(check.key)) {
         result.push(check);
+        seen.add(check.key);
       }
     }
   }
 
+  for (const check of checkLookup.values()) {
+    if (seen.has(check.key)) {
+      continue;
+    }
+
+    if (check.observable_links.some((link) => link.observable_key === observableKey)) {
+      result.push(check);
+      seen.add(check.key);
+    }
+  }
+
   return result;
 }
 
@@ -486,7 +490,12 @@ export function getObservablesForCheck(
   for (const checks of Object.values(inv.checks)) {
     for (const check of checks) {
       if (check.key === checkKey) {
-        return check.observables
+        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);
       }

package/src/types.generated.ts

@@ -1,5 +1,9 @@
 // AUTO-GENERATED FROM cyvest.schema.json — DO NOT EDIT
 
+/**
+ * Optional human-readable investigation name.
+ */
+export type InvestigationName = string | null;
 /**
  * Security level classification for checks, observables, and threat intelligence.
  *
@@ -11,6 +15,15 @@ export type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 export type Whitelists = InvestigationWhitelist[];
+export type Actor = string | null;
+export type Reason = string | null;
+export type Tool = string | null;
+export type ObjectType = string | null;
+export type ObjectKey = string | null;
+/**
+ * Append-only investigation audit log.
+ */
+export type EventLog = AuditEvent[];
 export type ThreatIntels = string[];
 /**
  * Direction of a relationship between observables.
@@ -18,14 +31,14 @@ export type ThreatIntels = string[];
 export type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
 export type Relationships = Relationship[];
 /**
- * Checks that generated this observable.
+ * Checks that currently link to this observable (navigation-only).
  */
-export type GeneratedByChecks = string[];
-export type Observables1 = string[];
+export type CheckLinks = string[];
 /**
- * Controls how a check reacts to linked observables.
+ * Controls how a Check↔Observable link propagates across merged investigations.
  */
-export type CheckScorePolicy = "auto" | "manual";
+export type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
+export type ObservableLinks = ObservableLink[];
 export type Taxonomies = {
   [k: string]: unknown;
 }[];
@@ -50,6 +63,11 @@ export type ScoreMode = "max" | "sum";
  * schemas matching the actual model_dump() output.
  */
 export interface CyvestInvestigation {
+  /**
+   * Stable investigation identity (ULID).
+   */
+  investigation_id: string;
+  investigation_name?: InvestigationName;
   /**
    * Investigation start time (UTC).
    */
@@ -64,6 +82,7 @@ export interface CyvestInvestigation {
    */
   whitelisted: boolean;
   whitelists: Whitelists;
+  event_log?: EventLog;
   observables: Observables;
   checks: Checks;
   checks_by_level: ChecksByLevel;
@@ -87,6 +106,24 @@ export interface InvestigationWhitelist {
   justification?: Justification;
   [k: string]: unknown;
 }
+/**
+ * Centralized audit event for investigation-level changes.
+ */
+export interface AuditEvent {
+  event_id: string;
+  timestamp: string;
+  event_type: string;
+  actor?: Actor;
+  reason?: Reason;
+  tool?: Tool;
+  object_type?: ObjectType;
+  object_key?: ObjectKey;
+  details?: Details;
+  [k: string]: unknown;
+}
+export interface Details {
+  [k: string]: unknown;
+}
 /**
  * Observables keyed by their unique key.
  */
@@ -111,7 +148,7 @@ export interface Observable {
   threat_intels: ThreatIntels;
   relationships: Relationships;
   key: string;
-  generated_by_checks: GeneratedByChecks;
+  check_links: CheckLinks;
   score_display: string;
   [k: string]: unknown;
 }
@@ -147,8 +184,8 @@ export interface Check {
   extra: Extra1;
   score: number;
   level: Level;
-  observables: Observables1;
-  score_policy?: CheckScorePolicy;
+  origin_investigation_id: string;
+  observable_links: ObservableLinks;
   key: string;
   score_display: string;
   [k: string]: unknown;
@@ -156,6 +193,13 @@ export interface Check {
 export interface Extra1 {
   [k: string]: unknown;
 }
+/**
+ * Edge metadata for a Check↔Observable association.
+ */
+export interface ObservableLink {
+  observable_key: string;
+  propagation_mode?: PropagationMode;
+}
 /**
  * Check keys organized by level name.
  */

package/tests/getters-finders.test.ts

@@ -41,7 +41,11 @@ import {
 // Test fixture
 function createTestInvestigation(): CyvestInvestigation {
   return {
+    investigation_id: "01HXYZTESTINVESTIGATION",
+    investigation_name: "Test Investigation",
+    started_at: "2024-01-01T00:00:00Z",
     score: 7.5,
+    score_display: "7.50",
     level: "MALICIOUS",
     whitelisted: false,
     whitelists: [
@@ -59,8 +63,9 @@ function createTestInvestigation(): CyvestInvestigation {
         internal: true,
         whitelisted: false,
         comment: "",
-        extra: null,
+        extra: {},
         score: 0,
+        score_display: "0.00",
         level: "INFO",
         relationships: [
           {
@@ -70,7 +75,7 @@ function createTestInvestigation(): CyvestInvestigation {
           },
         ],
         threat_intels: [],
-        generated_by_checks: ["chk:ip_check:network"],
+        check_links: ["chk:ip_check:network"],
       },
       "obs:ipv4-addr:8.8.8.8": {
         key: "obs:ipv4-addr:8.8.8.8",
@@ -79,12 +84,13 @@ function createTestInvestigation(): CyvestInvestigation {
         internal: false,
         whitelisted: true,
         comment: "Google DNS",
-        extra: null,
+        extra: {},
         score: -1,
+        score_display: "-1.00",
         level: "TRUSTED",
         relationships: [],
         threat_intels: [],
-        generated_by_checks: [],
+        check_links: [],
       },
       "obs:domain-name:example.com": {
         key: "obs:domain-name:example.com",
@@ -93,12 +99,13 @@ function createTestInvestigation(): CyvestInvestigation {
         internal: false,
         whitelisted: false,
         comment: "",
-        extra: null,
+        extra: {},
         score: 5,
+        score_display: "5.00",
         level: "MALICIOUS",
         relationships: [],
         threat_intels: ["ti:virustotal:obs:domain-name:example.com"],
-        generated_by_checks: ["chk:domain_check:dns"],
+        check_links: ["chk:domain_check:dns"],
       },
       "obs:url:http://malware.com/bad": {
         key: "obs:url:http://malware.com/bad",
@@ -107,12 +114,13 @@ function createTestInvestigation(): CyvestInvestigation {
         internal: false,
         whitelisted: false,
         comment: "",
-        extra: null,
+        extra: {},
         score: 7.5,
+        score_display: "7.50",
         level: "MALICIOUS",
         relationships: [],
         threat_intels: [],
-        generated_by_checks: [],
+        check_links: [],
       },
     },
     checks: {
@@ -123,11 +131,16 @@ function createTestInvestigation(): CyvestInvestigation {
           scope: "network",
           description: "IP address check",
           comment: "",
-          extra: null,
+          extra: {},
           score: 0,
+          score_display: "0.00",
           level: "INFO",
-          score_policy: "auto",
-          observables: ["obs:ipv4-addr:192.168.1.1"],
+          origin_investigation_id: "01HXYZTESTINVESTIGATION",
+          observable_links: [
+            {
+              observable_key: "obs:ipv4-addr:192.168.1.1",
+            },
+          ],
         },
       ],
       dns: [
@@ -137,11 +150,16 @@ function createTestInvestigation(): CyvestInvestigation {
           scope: "dns",
           description: "Domain reputation check",
           comment: "",
-          extra: null,
+          extra: {},
           score: 5,
+          score_display: "5.00",
           level: "MALICIOUS",
-          score_policy: "auto",
-          observables: ["obs:domain-name:example.com"],
+          origin_investigation_id: "01HXYZTESTINVESTIGATION",
+          observable_links: [
+            {
+              observable_key: "obs:domain-name:example.com",
+            },
+          ],
         },
         {
           key: "chk:dns_lookup:dns",
@@ -149,11 +167,12 @@ function createTestInvestigation(): CyvestInvestigation {
           scope: "dns",
           description: "DNS lookup",
           comment: "",
-          extra: null,
+          extra: {},
           score: 0,
+          score_display: "0.00",
           level: "INFO",
-          score_policy: "manual",
-          observables: [],
+          origin_investigation_id: "01HXYZTESTINVESTIGATION",
+          observable_links: [],
         },
       ],
     },
@@ -167,8 +186,9 @@ function createTestInvestigation(): CyvestInvestigation {
         source: "virustotal",
         observable_key: "obs:domain-name:example.com",
         comment: "",
-        extra: null,
+        extra: {},
         score: 5,
+        score_display: "5.00",
         level: "MALICIOUS",
         taxonomies: [{ verdict: "malicious" }],
       },