@cyvest/cyvest-js 3.2.0 → 4.1.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.",
@@ -141,6 +224,10 @@ var cyvest_schema_default = {
         root_type: {
           anyOf: [
             {
+              enum: [
+                "file",
+                "artifact"
+              ],
               type: "string"
             },
             {
@@ -151,13 +238,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"
@@ -290,13 +377,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 +404,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: {
@@ -482,28 +597,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: {
@@ -569,6 +662,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 +708,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"
@@ -655,10 +774,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."
@@ -671,6 +786,7 @@ var cyvest_schema_default = {
     }
   },
   required: [
+    "investigation_id",
     "started_at",
     "score",
     "level",
@@ -683,7 +799,6 @@ var cyvest_schema_default = {
     "enrichments",
     "containers",
     "stats",
-    "stats_checks",
     "data_extraction",
     "score_display"
   ],
@@ -1056,9 +1171,6 @@ function getWhitelists(inv) {
 function getStats(inv) {
   return inv.stats;
 }
-function getStatsChecks(inv) {
-  return inv.stats_checks;
-}
 function getDataExtraction(inv) {
   return inv.data_extraction;
 }
@@ -1165,17 +1277,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 +1319,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 +1360,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 +1736,6 @@ export {
   findExternalObservables,
   findInternalObservables,
   findLeafObservables,
-  findManuallyScored,
   findObservablesAtLeast,
   findObservablesByLevel,
   findObservablesByType,
@@ -1671,7 +1794,6 @@ export {
   getRelatedObservablesByType,
   getRelationshipsForObservable,
   getStats,
-  getStatsChecks,
   getSuspiciousChecks,
   getSuspiciousObservables,
   getThreatIntel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "3.2.0",
+  "version": "4.1.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/getters.ts

@@ -359,16 +359,6 @@ export function getStats(inv: CyvestInvestigation) {
   return inv.stats;
 }
 
-/**
- * Get the investigation check statistics.
- *
- * @param inv - The investigation
- * @returns Check statistics object
- */
-export function getStatsChecks(inv: CyvestInvestigation) {
-  return inv.stats_checks;
-}
-
 /**
  * Get the data extraction configuration.
  *

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;
 }[];
@@ -33,7 +46,7 @@ export type Checks1 = string[];
 /**
  * Root observable type used during data extraction.
  */
-export type RootType = string | null;
+export type RootType = ("file" | "artifact") | null;
 /**
  * Score calculation mode for observables.
  */
@@ -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;
@@ -71,7 +90,6 @@ export interface CyvestInvestigation {
   enrichments: Enrichments;
   containers: Containers;
   stats: StatisticsSchema;
-  stats_checks: StatsChecksSchema;
   data_extraction: DataExtractionSchema;
   /**
    * Global investigation score formatted as fixed-point x.xx.
@@ -87,6 +105,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 +147,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 +183,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 +192,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.
  */
@@ -280,17 +323,10 @@ export interface ThreatIntelBySource {
 export interface ThreatIntelByLevel {
   [k: string]: number;
 }
-/**
- * Schema for check statistics summary.
- */
-export interface StatsChecksSchema {
-  checks: number;
-  applied: number;
-}
 /**
  * Schema for data extraction metadata.
  */
 export interface DataExtractionSchema {
   root_type?: RootType;
-  score_mode: ScoreMode;
+  score_mode_obs: ScoreMode;
 }