@cyvest/cyvest-js 3.2.0 → 4.1.0

package/dist/index.js

@@ -45,7 +45,6 @@ __export(index_exports, {
   findExternalObservables: () => findExternalObservables,
   findInternalObservables: () => findInternalObservables,
   findLeafObservables: () => findLeafObservables,
-  findManuallyScored: () => findManuallyScored,
   findObservablesAtLeast: () => findObservablesAtLeast,
   findObservablesByLevel: () => findObservablesByLevel,
   findObservablesByType: () => findObservablesByType,
@@ -104,7 +103,6 @@ __export(index_exports, {
   getRelatedObservablesByType: () => getRelatedObservablesByType,
   getRelationshipsForObservable: () => getRelationshipsForObservable,
   getStats: () => getStats,
-  getStatsChecks: () => getStatsChecks,
   getSuspiciousChecks: () => getSuspiciousChecks,
   getSuspiciousObservables: () => getSuspiciousObservables,
   getThreatIntel: () => getThreatIntel,
@@ -140,6 +138,97 @@ var import_ajv_formats = __toESM(require("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: {
@@ -171,17 +260,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"
@@ -200,22 +289,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.",
@@ -276,6 +357,10 @@ var cyvest_schema_default = {
         root_type: {
           anyOf: [
             {
+              enum: [
+                "file",
+                "artifact"
+              ],
               type: "string"
             },
             {
@@ -286,13 +371,13 @@ var cyvest_schema_default = {
           description: "Root observable type used during data extraction.",
           title: "Root Type"
         },
-        score_mode: {
+        score_mode_obs: {
           $ref: "#/$defs/ScoreMode",
-          description: "Score aggregation mode: 'max' takes highest score, 'sum' adds all scores."
+          description: "Observable score aggregation mode: 'max' takes highest score, 'sum' adds all scores."
         }
       },
       required: [
-        "score_mode"
+        "score_mode_obs"
       ],
       title: "DataExtractionSchema",
       type: "object"
@@ -425,13 +510,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: {
@@ -452,12 +537,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: {
@@ -617,28 +730,6 @@ var cyvest_schema_default = {
       title: "StatisticsSchema",
       type: "object"
     },
-    StatsChecksSchema: {
-      additionalProperties: false,
-      description: "Schema for check statistics summary.",
-      properties: {
-        checks: {
-          minimum: 0,
-          title: "Checks",
-          type: "integer"
-        },
-        applied: {
-          minimum: 0,
-          title: "Applied",
-          type: "integer"
-        }
-      },
-      required: [
-        "checks",
-        "applied"
-      ],
-      title: "StatsChecksSchema",
-      type: "object"
-    },
     ThreatIntel: {
       description: "Represents threat intelligence from an external source.\n\nThreat intelligence provides verdicts about observables from sources\nlike VirusTotal, URLScan.io, etc.",
       properties: {
@@ -704,6 +795,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",
@@ -732,6 +841,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"
@@ -790,10 +907,6 @@ var cyvest_schema_default = {
       $ref: "#/$defs/StatisticsSchema",
       description: "Investigation statistics summary."
     },
-    stats_checks: {
-      $ref: "#/$defs/StatsChecksSchema",
-      description: "Check statistics summary."
-    },
     data_extraction: {
       $ref: "#/$defs/DataExtractionSchema",
       description: "Data extraction metadata."
@@ -806,6 +919,7 @@ var cyvest_schema_default = {
     }
   },
   required: [
+    "investigation_id",
     "started_at",
     "score",
     "level",
@@ -818,7 +932,6 @@ var cyvest_schema_default = {
     "enrichments",
     "containers",
     "stats",
-    "stats_checks",
     "data_extraction",
     "score_display"
   ],
@@ -1191,9 +1304,6 @@ function getWhitelists(inv) {
 function getStats(inv) {
   return inv.stats;
 }
-function getStatsChecks(inv) {
-  return inv.stats_checks;
-}
 function getDataExtraction(inv) {
   return inv.data_extraction;
 }
@@ -1300,17 +1410,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(
@@ -1353,13 +1452,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) {
@@ -1375,7 +1493,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);
       }
     }
   }
@@ -1748,7 +1870,6 @@ function getRelationshipsForObservable(inv, observableKey) {
   findExternalObservables,
   findInternalObservables,
   findLeafObservables,
-  findManuallyScored,
   findObservablesAtLeast,
   findObservablesByLevel,
   findObservablesByType,
@@ -1807,7 +1928,6 @@ function getRelationshipsForObservable(inv, observableKey) {
   getRelatedObservablesByType,
   getRelationshipsForObservable,
   getStats,
-  getStatsChecks,
   getSuspiciousChecks,
   getSuspiciousObservables,
   getThreatIntel,