@cyvest/cyvest-js 3.1.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,20 +127,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: [
@@ -60,21 +156,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.",
@@ -284,14 +373,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: [
@@ -306,11 +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: {
@@ -530,6 +653,11 @@ var cyvest_schema_default = {
         key: {
           title: "Key",
           type: "string"
+        },
+        score_display: {
+          readOnly: true,
+          title: "Score Display",
+          type: "string"
         }
       },
       required: [
@@ -540,7 +668,8 @@ var cyvest_schema_default = {
         "score",
         "level",
         "taxonomies",
-        "key"
+        "key",
+        "score_display"
       ],
       title: "ThreatIntel",
       type: "object"
@@ -551,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",
@@ -579,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"
@@ -644,9 +799,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",
@@ -660,7 +822,8 @@ var cyvest_schema_default = {
     "containers",
     "stats",
     "stats_checks",
-    "data_extraction"
+    "data_extraction",
+    "score_display"
   ],
   title: "Cyvest Investigation",
   type: "object"
@@ -1140,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(
@@ -1193,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) {
@@ -1215,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);
       }
     }
   }
@@ -1587,7 +1762,6 @@ export {
   findExternalObservables,
   findInternalObservables,
   findLeafObservables,
-  findManuallyScored,
   findObservablesAtLeast,
   findObservablesByLevel,
   findObservablesByType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "3.1.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);
       }