@cyvest/cyvest-js 3.1.0 → 4.0.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,
@@ -140,6 +139,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,20 +261,25 @@ 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"
+        },
+        score_display: {
+          readOnly: true,
+          title: "Score Display",
+          type: "string"
         }
       },
       required: [
@@ -195,21 +290,14 @@ var cyvest_schema_default = {
         "extra",
         "score",
         "level",
-        "observables",
-        "key"
+        "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.",
@@ -419,14 +507,19 @@ 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: {
+          readOnly: true,
+          title: "Score Display",
+          type: "string"
         }
       },
       required: [
@@ -441,11 +534,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: {
@@ -665,6 +787,11 @@ var cyvest_schema_default = {
         key: {
           title: "Key",
           type: "string"
+        },
+        score_display: {
+          readOnly: true,
+          title: "Score Display",
+          type: "string"
         }
       },
       required: [
@@ -675,7 +802,8 @@ var cyvest_schema_default = {
         "score",
         "level",
         "taxonomies",
-        "key"
+        "key",
+        "score_display"
       ],
       title: "ThreatIntel",
       type: "object"
@@ -686,6 +814,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",
@@ -714,6 +860,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"
@@ -779,9 +933,16 @@ var cyvest_schema_default = {
     data_extraction: {
       $ref: "#/$defs/DataExtractionSchema",
       description: "Data extraction metadata."
+    },
+    score_display: {
+      description: "Global investigation score formatted as fixed-point x.xx.",
+      readOnly: true,
+      title: "Score Display",
+      type: "string"
     }
   },
   required: [
+    "investigation_id",
     "started_at",
     "score",
     "level",
@@ -795,7 +956,8 @@ var cyvest_schema_default = {
     "containers",
     "stats",
     "stats_checks",
-    "data_extraction"
+    "data_extraction",
+    "score_display"
   ],
   title: "Cyvest Investigation",
   type: "object"
@@ -1275,17 +1437,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(
@@ -1328,13 +1479,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) {
@@ -1350,7 +1520,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);
       }
     }
   }
@@ -1723,7 +1897,6 @@ function getRelationshipsForObservable(inv, observableKey) {
   findExternalObservables,
   findInternalObservables,
   findLeafObservables,
-  findManuallyScored,
   findObservablesAtLeast,
   findObservablesByLevel,
   findObservablesByType,