@cyvest/cyvest-js 4.2.0 → 4.4.0

package/dist/index.d.mts

@@ -13,15 +13,15 @@ type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 type Whitelists = InvestigationWhitelist[];
+/**
+ * Append-only investigation audit log. Null when serialization disabled audit.
+ */
+type AuditLog = AuditEvent[] | null;
 type Actor = string | null;
 type Reason = string | null;
 type Tool = string | null;
 type ObjectType = string | null;
 type ObjectKey = string | null;
-/**
- * Append-only investigation audit log.
- */
-type EventLog = AuditEvent[];
 type ThreatIntels = string[];
 /**
  * Direction of a relationship between observables.
@@ -63,10 +63,6 @@ interface CyvestInvestigation {
      */
     investigation_id: string;
     investigation_name?: InvestigationName;
-    /**
-     * Investigation start time (UTC).
-     */
-    started_at: string;
     /**
      * Global investigation score.
      */
@@ -77,10 +73,9 @@ interface CyvestInvestigation {
      */
     whitelisted: boolean;
     whitelists: Whitelists;
-    event_log?: EventLog;
+    audit_log?: AuditLog;
     observables: Observables;
     checks: Checks;
-    checks_by_level: ChecksByLevel;
     threat_intels: ThreatIntels1;
     enrichments: Enrichments;
     containers: Containers;
@@ -194,12 +189,6 @@ interface ObservableLink {
     observable_key: string;
     propagation_mode?: PropagationMode;
 }
-/**
- * Check keys organized by level name.
- */
-interface ChecksByLevel {
-    [k: string]: string[];
-}
 /**
  * Threat intelligence entries keyed by their unique key.
  */
@@ -297,7 +286,7 @@ interface StatisticsSchema {
     total_checks: number;
     applied_checks: number;
     checks_by_scope?: ChecksByScope;
-    checks_by_level?: ChecksByLevel1;
+    checks_by_level?: ChecksByLevel;
     total_threat_intel: number;
     threat_intel_by_source?: ThreatIntelBySource;
     threat_intel_by_level?: ThreatIntelByLevel;
@@ -315,10 +304,10 @@ interface ObservablesByTypeAndLevel {
     };
 }
 interface ChecksByScope {
-    [k: string]: number;
+    [k: string]: string[];
 }
-interface ChecksByLevel1 {
-    [k: string]: number;
+interface ChecksByLevel {
+    [k: string]: string[];
 }
 interface ThreatIntelBySource {
     [k: string]: number;
@@ -849,6 +838,23 @@ interface InvestigationCounts {
  * @returns Object with counts for each entity type
  */
 declare function getCounts(inv: CyvestInvestigation): InvestigationCounts;
+/**
+ * Get the investigation start time from the event log.
+ *
+ * Looks for the INVESTIGATION_STARTED event and returns its timestamp.
+ *
+ * @param inv - The investigation
+ * @returns The start timestamp string or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const startedAt = getStartedAt(investigation);
+ * if (startedAt) {
+ *   console.log(`Started: ${startedAt}`);
+ * }
+ * ```
+ */
+declare function getStartedAt(inv: CyvestInvestigation): string | undefined;
 
 /**
  * Finder utilities for querying and filtering Cyvest Investigation data.
@@ -1362,4 +1368,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type Actor, type AuditEvent, type Check, type CheckLinks, type Checks, type Checks1, type ChecksByLevel, type ChecksByLevel1, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Details, type Enrichment, type Enrichments, type EventLog, type Extra, type Extra1, type Extra2, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationName, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type ObjectKey, type ObjectType, type Observable, type ObservableLink, type ObservableLinks, type Observables, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type PropagationMode, type Reason, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type SubContainers, type Taxonomies, type Taxonomy, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Tool, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findObservablesAtLeast, findObservablesByLevel, findObservablesByType, findObservablesByValue, findObservablesContaining, findObservablesMatching, findObservablesWithThreatIntel, findOrphanObservables, findPath, findRootObservables, findThreatIntelAtLeast, findThreatIntelByLevel, findThreatIntelBySource, findWhitelistedObservables, generateCheckKey, generateContainerKey, generateEnrichmentKey, generateObservableKey, generateThreatIntelKey, getAllChecks, getAllContainers, getAllEnrichments, getAllObservableTypes, getAllObservables, getAllRelationshipTypes, getAllScopes, getAllThreatIntelSources, getAllThreatIntels, getCheck, getCheckByIdScope, getChecksForContainer, getChecksForObservable, getColorForLevel, getColorForScore, getContainer, getContainerByPath, getCounts, getDataExtraction, getEnrichment, getEnrichmentByName, getEntityLevel, getHighestScoringChecks, getHighestScoringObservables, getLevelFromScore, getMaliciousChecks, getMaliciousObservables, getObservable, getObservableByTypeValue, getObservableChildren, getObservableGraph, getObservableParents, getObservablesForCheck, getReachableObservables, getRelatedObservables, getRelatedObservablesByDirection, getRelatedObservablesByType, getRelationshipsForObservable, getStats, getSuspiciousChecks, getSuspiciousObservables, getThreatIntel, getThreatIntelBySourceObservable, getThreatIntelsForObservable, getWhitelists, hasLevel, isCyvest, isLevelAtLeast, isLevelHigherThan, isLevelLowerThan, isValidLevel, maxLevel, minLevel, normalizeLevel, parseCheckKey, parseCyvest, parseKeyType, parseObservableKey, parseThreatIntelKey, sortChecksByLevel, sortChecksByScore, sortObservablesByLevel, sortObservablesByScore, validateKey };
+export { type Actor, type AuditEvent, type AuditLog, type Check, type CheckLinks, type Checks, type Checks1, type ChecksByLevel, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Details, type Enrichment, type Enrichments, type Extra, type Extra1, type Extra2, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationName, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type ObjectKey, type ObjectType, type Observable, type ObservableLink, type ObservableLinks, type Observables, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type PropagationMode, type Reason, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type SubContainers, type Taxonomies, type Taxonomy, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Tool, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findObservablesAtLeast, findObservablesByLevel, findObservablesByType, findObservablesByValue, findObservablesContaining, findObservablesMatching, findObservablesWithThreatIntel, findOrphanObservables, findPath, findRootObservables, findThreatIntelAtLeast, findThreatIntelByLevel, findThreatIntelBySource, findWhitelistedObservables, generateCheckKey, generateContainerKey, generateEnrichmentKey, generateObservableKey, generateThreatIntelKey, getAllChecks, getAllContainers, getAllEnrichments, getAllObservableTypes, getAllObservables, getAllRelationshipTypes, getAllScopes, getAllThreatIntelSources, getAllThreatIntels, getCheck, getCheckByIdScope, getChecksForContainer, getChecksForObservable, getColorForLevel, getColorForScore, getContainer, getContainerByPath, getCounts, getDataExtraction, getEnrichment, getEnrichmentByName, getEntityLevel, getHighestScoringChecks, getHighestScoringObservables, getLevelFromScore, getMaliciousChecks, getMaliciousObservables, getObservable, getObservableByTypeValue, getObservableChildren, getObservableGraph, getObservableParents, getObservablesForCheck, getReachableObservables, getRelatedObservables, getRelatedObservablesByDirection, getRelatedObservablesByType, getRelationshipsForObservable, getStartedAt, getStats, getSuspiciousChecks, getSuspiciousObservables, getThreatIntel, getThreatIntelBySourceObservable, getThreatIntelsForObservable, getWhitelists, hasLevel, isCyvest, isLevelAtLeast, isLevelHigherThan, isLevelLowerThan, isValidLevel, maxLevel, minLevel, normalizeLevel, parseCheckKey, parseCyvest, parseKeyType, parseObservableKey, parseThreatIntelKey, sortChecksByLevel, sortChecksByScore, sortObservablesByLevel, sortObservablesByScore, validateKey };

package/dist/index.d.ts

@@ -13,15 +13,15 @@ type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 type Whitelists = InvestigationWhitelist[];
+/**
+ * Append-only investigation audit log. Null when serialization disabled audit.
+ */
+type AuditLog = AuditEvent[] | null;
 type Actor = string | null;
 type Reason = string | null;
 type Tool = string | null;
 type ObjectType = string | null;
 type ObjectKey = string | null;
-/**
- * Append-only investigation audit log.
- */
-type EventLog = AuditEvent[];
 type ThreatIntels = string[];
 /**
  * Direction of a relationship between observables.
@@ -63,10 +63,6 @@ interface CyvestInvestigation {
      */
     investigation_id: string;
     investigation_name?: InvestigationName;
-    /**
-     * Investigation start time (UTC).
-     */
-    started_at: string;
     /**
      * Global investigation score.
      */
@@ -77,10 +73,9 @@ interface CyvestInvestigation {
      */
     whitelisted: boolean;
     whitelists: Whitelists;
-    event_log?: EventLog;
+    audit_log?: AuditLog;
     observables: Observables;
     checks: Checks;
-    checks_by_level: ChecksByLevel;
     threat_intels: ThreatIntels1;
     enrichments: Enrichments;
     containers: Containers;
@@ -194,12 +189,6 @@ interface ObservableLink {
     observable_key: string;
     propagation_mode?: PropagationMode;
 }
-/**
- * Check keys organized by level name.
- */
-interface ChecksByLevel {
-    [k: string]: string[];
-}
 /**
  * Threat intelligence entries keyed by their unique key.
  */
@@ -297,7 +286,7 @@ interface StatisticsSchema {
     total_checks: number;
     applied_checks: number;
     checks_by_scope?: ChecksByScope;
-    checks_by_level?: ChecksByLevel1;
+    checks_by_level?: ChecksByLevel;
     total_threat_intel: number;
     threat_intel_by_source?: ThreatIntelBySource;
     threat_intel_by_level?: ThreatIntelByLevel;
@@ -315,10 +304,10 @@ interface ObservablesByTypeAndLevel {
     };
 }
 interface ChecksByScope {
-    [k: string]: number;
+    [k: string]: string[];
 }
-interface ChecksByLevel1 {
-    [k: string]: number;
+interface ChecksByLevel {
+    [k: string]: string[];
 }
 interface ThreatIntelBySource {
     [k: string]: number;
@@ -849,6 +838,23 @@ interface InvestigationCounts {
  * @returns Object with counts for each entity type
  */
 declare function getCounts(inv: CyvestInvestigation): InvestigationCounts;
+/**
+ * Get the investigation start time from the event log.
+ *
+ * Looks for the INVESTIGATION_STARTED event and returns its timestamp.
+ *
+ * @param inv - The investigation
+ * @returns The start timestamp string or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const startedAt = getStartedAt(investigation);
+ * if (startedAt) {
+ *   console.log(`Started: ${startedAt}`);
+ * }
+ * ```
+ */
+declare function getStartedAt(inv: CyvestInvestigation): string | undefined;
 
 /**
  * Finder utilities for querying and filtering Cyvest Investigation data.
@@ -1362,4 +1368,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type Actor, type AuditEvent, type Check, type CheckLinks, type Checks, type Checks1, type ChecksByLevel, type ChecksByLevel1, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Details, type Enrichment, type Enrichments, type EventLog, type Extra, type Extra1, type Extra2, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationName, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type ObjectKey, type ObjectType, type Observable, type ObservableLink, type ObservableLinks, type Observables, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type PropagationMode, type Reason, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type SubContainers, type Taxonomies, type Taxonomy, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Tool, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findObservablesAtLeast, findObservablesByLevel, findObservablesByType, findObservablesByValue, findObservablesContaining, findObservablesMatching, findObservablesWithThreatIntel, findOrphanObservables, findPath, findRootObservables, findThreatIntelAtLeast, findThreatIntelByLevel, findThreatIntelBySource, findWhitelistedObservables, generateCheckKey, generateContainerKey, generateEnrichmentKey, generateObservableKey, generateThreatIntelKey, getAllChecks, getAllContainers, getAllEnrichments, getAllObservableTypes, getAllObservables, getAllRelationshipTypes, getAllScopes, getAllThreatIntelSources, getAllThreatIntels, getCheck, getCheckByIdScope, getChecksForContainer, getChecksForObservable, getColorForLevel, getColorForScore, getContainer, getContainerByPath, getCounts, getDataExtraction, getEnrichment, getEnrichmentByName, getEntityLevel, getHighestScoringChecks, getHighestScoringObservables, getLevelFromScore, getMaliciousChecks, getMaliciousObservables, getObservable, getObservableByTypeValue, getObservableChildren, getObservableGraph, getObservableParents, getObservablesForCheck, getReachableObservables, getRelatedObservables, getRelatedObservablesByDirection, getRelatedObservablesByType, getRelationshipsForObservable, getStats, getSuspiciousChecks, getSuspiciousObservables, getThreatIntel, getThreatIntelBySourceObservable, getThreatIntelsForObservable, getWhitelists, hasLevel, isCyvest, isLevelAtLeast, isLevelHigherThan, isLevelLowerThan, isValidLevel, maxLevel, minLevel, normalizeLevel, parseCheckKey, parseCyvest, parseKeyType, parseObservableKey, parseThreatIntelKey, sortChecksByLevel, sortChecksByScore, sortObservablesByLevel, sortObservablesByScore, validateKey };
+export { type Actor, type AuditEvent, type AuditLog, type Check, type CheckLinks, type Checks, type Checks1, type ChecksByLevel, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Details, type Enrichment, type Enrichments, type Extra, type Extra1, type Extra2, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationName, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type ObjectKey, type ObjectType, type Observable, type ObservableLink, type ObservableLinks, type Observables, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type PropagationMode, type Reason, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type SubContainers, type Taxonomies, type Taxonomy, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Tool, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findObservablesAtLeast, findObservablesByLevel, findObservablesByType, findObservablesByValue, findObservablesContaining, findObservablesMatching, findObservablesWithThreatIntel, findOrphanObservables, findPath, findRootObservables, findThreatIntelAtLeast, findThreatIntelByLevel, findThreatIntelBySource, findWhitelistedObservables, generateCheckKey, generateContainerKey, generateEnrichmentKey, generateObservableKey, generateThreatIntelKey, getAllChecks, getAllContainers, getAllEnrichments, getAllObservableTypes, getAllObservables, getAllRelationshipTypes, getAllScopes, getAllThreatIntelSources, getAllThreatIntels, getCheck, getCheckByIdScope, getChecksForContainer, getChecksForObservable, getColorForLevel, getColorForScore, getContainer, getContainerByPath, getCounts, getDataExtraction, getEnrichment, getEnrichmentByName, getEntityLevel, getHighestScoringChecks, getHighestScoringObservables, getLevelFromScore, getMaliciousChecks, getMaliciousObservables, getObservable, getObservableByTypeValue, getObservableChildren, getObservableGraph, getObservableParents, getObservablesForCheck, getReachableObservables, getRelatedObservables, getRelatedObservablesByDirection, getRelatedObservablesByType, getRelationshipsForObservable, getStartedAt, getStats, getSuspiciousChecks, getSuspiciousObservables, getThreatIntel, getThreatIntelBySourceObservable, getThreatIntelsForObservable, getWhitelists, hasLevel, isCyvest, isLevelAtLeast, isLevelHigherThan, isLevelLowerThan, isValidLevel, maxLevel, minLevel, normalizeLevel, parseCheckKey, parseCyvest, parseKeyType, parseObservableKey, parseThreatIntelKey, sortChecksByLevel, sortChecksByScore, sortObservablesByLevel, sortObservablesByScore, validateKey };

package/dist/index.js

@@ -102,6 +102,7 @@ __export(index_exports, {
   getRelatedObservablesByDirection: () => getRelatedObservablesByDirection,
   getRelatedObservablesByType: () => getRelatedObservablesByType,
   getRelationshipsForObservable: () => getRelationshipsForObservable,
+  getStartedAt: () => getStartedAt,
   getStats: () => getStats,
   getSuspiciousChecks: () => getSuspiciousChecks,
   getSuspiciousObservables: () => getSuspiciousObservables,
@@ -676,16 +677,20 @@ var cyvest_schema_default = {
         },
         checks_by_scope: {
           additionalProperties: {
-            minimum: 0,
-            type: "integer"
+            items: {
+              type: "string"
+            },
+            type: "array"
           },
           title: "Checks By Scope",
           type: "object"
         },
         checks_by_level: {
           additionalProperties: {
-            minimum: 0,
-            type: "integer"
+            items: {
+              type: "string"
+            },
+            type: "array"
           },
           title: "Checks By Level",
           type: "object"
@@ -836,12 +841,6 @@ var cyvest_schema_default = {
       description: "Optional human-readable investigation name.",
       title: "Investigation Name"
     },
-    started_at: {
-      description: "Investigation start time (UTC).",
-      format: "date-time",
-      title: "Started At",
-      type: "string"
-    },
     score: {
       description: "Global investigation score.",
       title: "Score",
@@ -864,13 +863,20 @@ 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"
+    audit_log: {
+      anyOf: [
+        {
+          items: {
+            $ref: "#/$defs/AuditEvent"
+          },
+          type: "array"
+        },
+        {
+          type: "null"
+        }
+      ],
+      description: "Append-only investigation audit log. Null when serialization disabled audit.",
+      title: "Audit Log"
     },
     observables: {
       additionalProperties: {
@@ -891,17 +897,6 @@ var cyvest_schema_default = {
       title: "Checks",
       type: "object"
     },
-    checks_by_level: {
-      additionalProperties: {
-        items: {
-          type: "string"
-        },
-        type: "array"
-      },
-      description: "Check keys organized by level name.",
-      title: "Checks By Level",
-      type: "object"
-    },
     threat_intels: {
       additionalProperties: {
         $ref: "#/$defs/ThreatIntel"
@@ -943,14 +938,12 @@ var cyvest_schema_default = {
   },
   required: [
     "investigation_id",
-    "started_at",
     "score",
     "level",
     "whitelisted",
     "whitelists",
     "observables",
     "checks",
-    "checks_by_level",
     "threat_intels",
     "enrichments",
     "containers",
@@ -1340,6 +1333,12 @@ function getCounts(inv) {
     whitelists: inv.whitelists.length
   };
 }
+function getStartedAt(inv) {
+  const event = inv.audit_log?.find(
+    (e) => e.event_type === "INVESTIGATION_STARTED"
+  );
+  return event?.timestamp;
+}
 
 // src/finders.ts
 function findObservablesByType(inv, type) {
@@ -1950,6 +1949,7 @@ function getRelationshipsForObservable(inv, observableKey) {
   getRelatedObservablesByDirection,
   getRelatedObservablesByType,
   getRelationshipsForObservable,
+  getStartedAt,
   getStats,
   getSuspiciousChecks,
   getSuspiciousObservables,

package/dist/index.mjs

@@ -543,16 +543,20 @@ var cyvest_schema_default = {
         },
         checks_by_scope: {
           additionalProperties: {
-            minimum: 0,
-            type: "integer"
+            items: {
+              type: "string"
+            },
+            type: "array"
           },
           title: "Checks By Scope",
           type: "object"
         },
         checks_by_level: {
           additionalProperties: {
-            minimum: 0,
-            type: "integer"
+            items: {
+              type: "string"
+            },
+            type: "array"
           },
           title: "Checks By Level",
           type: "object"
@@ -703,12 +707,6 @@ var cyvest_schema_default = {
       description: "Optional human-readable investigation name.",
       title: "Investigation Name"
     },
-    started_at: {
-      description: "Investigation start time (UTC).",
-      format: "date-time",
-      title: "Started At",
-      type: "string"
-    },
     score: {
       description: "Global investigation score.",
       title: "Score",
@@ -731,13 +729,20 @@ 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"
+    audit_log: {
+      anyOf: [
+        {
+          items: {
+            $ref: "#/$defs/AuditEvent"
+          },
+          type: "array"
+        },
+        {
+          type: "null"
+        }
+      ],
+      description: "Append-only investigation audit log. Null when serialization disabled audit.",
+      title: "Audit Log"
     },
     observables: {
       additionalProperties: {
@@ -758,17 +763,6 @@ var cyvest_schema_default = {
       title: "Checks",
       type: "object"
     },
-    checks_by_level: {
-      additionalProperties: {
-        items: {
-          type: "string"
-        },
-        type: "array"
-      },
-      description: "Check keys organized by level name.",
-      title: "Checks By Level",
-      type: "object"
-    },
     threat_intels: {
       additionalProperties: {
         $ref: "#/$defs/ThreatIntel"
@@ -810,14 +804,12 @@ var cyvest_schema_default = {
   },
   required: [
     "investigation_id",
-    "started_at",
     "score",
     "level",
     "whitelisted",
     "whitelists",
     "observables",
     "checks",
-    "checks_by_level",
     "threat_intels",
     "enrichments",
     "containers",
@@ -1207,6 +1199,12 @@ function getCounts(inv) {
     whitelists: inv.whitelists.length
   };
 }
+function getStartedAt(inv) {
+  const event = inv.audit_log?.find(
+    (e) => e.event_type === "INVESTIGATION_STARTED"
+  );
+  return event?.timestamp;
+}
 
 // src/finders.ts
 function findObservablesByType(inv, type) {
@@ -1816,6 +1814,7 @@ export {
   getRelatedObservablesByDirection,
   getRelatedObservablesByType,
   getRelationshipsForObservable,
+  getStartedAt,
   getStats,
   getSuspiciousChecks,
   getSuspiciousObservables,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/getters.ts

@@ -397,3 +397,26 @@ export function getCounts(inv: CyvestInvestigation): InvestigationCounts {
     whitelists: inv.whitelists.length,
   };
 }
+
+/**
+ * Get the investigation start time from the event log.
+ *
+ * Looks for the INVESTIGATION_STARTED event and returns its timestamp.
+ *
+ * @param inv - The investigation
+ * @returns The start timestamp string or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const startedAt = getStartedAt(investigation);
+ * if (startedAt) {
+ *   console.log(`Started: ${startedAt}`);
+ * }
+ * ```
+ */
+export function getStartedAt(inv: CyvestInvestigation): string | undefined {
+  const event = inv.audit_log?.find(
+    (e) => e.event_type === "INVESTIGATION_STARTED"
+  );
+  return event?.timestamp;
+}

package/src/types.generated.ts

@@ -15,15 +15,15 @@ export type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 export type Whitelists = InvestigationWhitelist[];
+/**
+ * Append-only investigation audit log. Null when serialization disabled audit.
+ */
+export type AuditLog = AuditEvent[] | null;
 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.
@@ -66,10 +66,6 @@ export interface CyvestInvestigation {
    */
   investigation_id: string;
   investigation_name?: InvestigationName;
-  /**
-   * Investigation start time (UTC).
-   */
-  started_at: string;
   /**
    * Global investigation score.
    */
@@ -80,10 +76,9 @@ export interface CyvestInvestigation {
    */
   whitelisted: boolean;
   whitelists: Whitelists;
-  event_log?: EventLog;
+  audit_log?: AuditLog;
   observables: Observables;
   checks: Checks;
-  checks_by_level: ChecksByLevel;
   threat_intels: ThreatIntels1;
   enrichments: Enrichments;
   containers: Containers;
@@ -197,12 +192,6 @@ export interface ObservableLink {
   observable_key: string;
   propagation_mode?: PropagationMode;
 }
-/**
- * Check keys organized by level name.
- */
-export interface ChecksByLevel {
-  [k: string]: string[];
-}
 /**
  * Threat intelligence entries keyed by their unique key.
  */
@@ -300,7 +289,7 @@ export interface StatisticsSchema {
   total_checks: number;
   applied_checks: number;
   checks_by_scope?: ChecksByScope;
-  checks_by_level?: ChecksByLevel1;
+  checks_by_level?: ChecksByLevel;
   total_threat_intel: number;
   threat_intel_by_source?: ThreatIntelBySource;
   threat_intel_by_level?: ThreatIntelByLevel;
@@ -318,10 +307,10 @@ export interface ObservablesByTypeAndLevel {
   };
 }
 export interface ChecksByScope {
-  [k: string]: number;
+  [k: string]: string[];
 }
-export interface ChecksByLevel1 {
-  [k: string]: number;
+export interface ChecksByLevel {
+  [k: string]: string[];
 }
 export interface ThreatIntelBySource {
   [k: string]: number;

package/tests/getters-finders.test.ts

@@ -18,6 +18,7 @@ import {
   getAllContainers,
   getAllObservables,
   getCounts,
+  getStartedAt,
   // Finders
   findObservablesByType,
   findObservablesByLevel,
@@ -43,11 +44,19 @@ 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,
+    audit_log: [
+      {
+        event_id: "01HXYZTESTEVENT001",
+        timestamp: "2024-01-01T00:00:00Z",
+        event_type: "INVESTIGATION_STARTED",
+        object_type: "investigation",
+        object_key: "01HXYZTESTINVESTIGATION",
+      },
+    ],
     whitelists: [
       {
         identifier: "wl-1",
@@ -176,10 +185,6 @@ function createTestInvestigation(): CyvestInvestigation {
         },
       ],
     },
-    checks_by_level: {
-      INFO: ["chk:ip_check:network", "chk:dns_lookup:dns"],
-      MALICIOUS: ["chk:domain_check:dns"],
-    },
     threat_intels: {
       "ti:virustotal:obs:domain-name:example.com": {
         key: "ti:virustotal:obs:domain-name:example.com",
@@ -232,8 +237,8 @@ function createTestInvestigation(): CyvestInvestigation {
       observables_by_type_and_level: {},
       total_checks: 3,
       applied_checks: 2,
-      checks_by_scope: { network: 1, dns: 2 },
-      checks_by_level: { INFO: 2, MALICIOUS: 1 },
+      checks_by_scope: { network: ["chk:ip_check:network"], dns: ["chk:domain_check:dns", "chk:dns_lookup:dns"] },
+      checks_by_level: { INFO: ["chk:ip_check:network", "chk:dns_lookup:dns"], MALICIOUS: ["chk:domain_check:dns"] },
       total_threat_intel: 1,
       threat_intel_by_source: { virustotal: 1 },
       threat_intel_by_level: { MALICIOUS: 1 },
@@ -344,6 +349,25 @@ describe("Getters", () => {
       expect(counts.whitelists).toBe(1);
     });
   });
+
+  describe("getStartedAt", () => {
+    it("returns timestamp from INVESTIGATION_STARTED event", () => {
+      const startedAt = getStartedAt(inv);
+      expect(startedAt).toBe("2024-01-01T00:00:00Z");
+    });
+
+    it("returns undefined when no audit_log", () => {
+      const invWithoutAuditLog = { ...inv, audit_log: undefined };
+      const startedAt = getStartedAt(invWithoutAuditLog);
+      expect(startedAt).toBeUndefined();
+    });
+
+    it("returns undefined when no INVESTIGATION_STARTED event", () => {
+      const invWithEmptyLog = { ...inv, audit_log: [] };
+      const startedAt = getStartedAt(invWithEmptyLog);
+      expect(startedAt).toBeUndefined();
+    });
+  });
 });
 
 describe("Finders", () => {

package/tests/graph.test.ts

@@ -22,11 +22,19 @@ function createGraphTestInvestigation(): CyvestInvestigation {
   return {
     investigation_id: "01HXYZGRAPHINVESTIGATION",
     investigation_name: "Graph Test Investigation",
-    started_at: "2024-01-01T00:00:00Z",
     score: 5,
     score_display: "5.00",
     level: "MALICIOUS",
     whitelisted: false,
+    audit_log: [
+      {
+        event_id: "01HXYZTESTEVENT001",
+        timestamp: "2024-01-01T00:00:00Z",
+        event_type: "INVESTIGATION_STARTED",
+        object_type: "investigation",
+        object_key: "01HXYZGRAPHINVESTIGATION",
+      },
+    ],
     whitelists: [],
     observables: {
       "obs:email-message:msg1": {
@@ -123,7 +131,6 @@ function createGraphTestInvestigation(): CyvestInvestigation {
       },
     },
     checks: {},
-    checks_by_level: {},
     threat_intels: {},
     enrichments: {},
     containers: {},