@cyvest/cyvest-js 3.2.0 → 4.1.0

package/dist/index.d.mts

@@ -1,3 +1,7 @@
+/**
+ * Optional human-readable investigation name.
+ */
+type InvestigationName = string | null;
 /**
  * Security level classification for checks, observables, and threat intelligence.
  *
@@ -9,6 +13,15 @@ type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 type Whitelists = InvestigationWhitelist[];
+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.
@@ -16,14 +29,14 @@ type ThreatIntels = string[];
 type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
 type Relationships = Relationship[];
 /**
- * Checks that generated this observable.
+ * Checks that currently link to this observable (navigation-only).
  */
-type GeneratedByChecks = string[];
-type Observables1 = string[];
+type CheckLinks = string[];
 /**
- * Controls how a check reacts to linked observables.
+ * Controls how a Check↔Observable link propagates across merged investigations.
  */
-type CheckScorePolicy = "auto" | "manual";
+type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
+type ObservableLinks = ObservableLink[];
 type Taxonomies = {
     [k: string]: unknown;
 }[];
@@ -31,7 +44,7 @@ type Checks1 = string[];
 /**
  * Root observable type used during data extraction.
  */
-type RootType = string | null;
+type RootType = ("file" | "artifact") | null;
 /**
  * Score calculation mode for observables.
  */
@@ -47,6 +60,11 @@ type ScoreMode = "max" | "sum";
  * schemas matching the actual model_dump() output.
  */
 interface CyvestInvestigation {
+    /**
+     * Stable investigation identity (ULID).
+     */
+    investigation_id: string;
+    investigation_name?: InvestigationName;
     /**
      * Investigation start time (UTC).
      */
@@ -61,6 +79,7 @@ interface CyvestInvestigation {
      */
     whitelisted: boolean;
     whitelists: Whitelists;
+    event_log?: EventLog;
     observables: Observables;
     checks: Checks;
     checks_by_level: ChecksByLevel;
@@ -68,7 +87,6 @@ interface CyvestInvestigation {
     enrichments: Enrichments;
     containers: Containers;
     stats: StatisticsSchema;
-    stats_checks: StatsChecksSchema;
     data_extraction: DataExtractionSchema;
     /**
      * Global investigation score formatted as fixed-point x.xx.
@@ -84,6 +102,24 @@ interface InvestigationWhitelist {
     justification?: Justification;
     [k: string]: unknown;
 }
+/**
+ * Centralized audit event for investigation-level changes.
+ */
+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;
+}
+interface Details {
+    [k: string]: unknown;
+}
 /**
  * Observables keyed by their unique key.
  */
@@ -108,7 +144,7 @@ interface Observable {
     threat_intels: ThreatIntels;
     relationships: Relationships;
     key: string;
-    generated_by_checks: GeneratedByChecks;
+    check_links: CheckLinks;
     score_display: string;
     [k: string]: unknown;
 }
@@ -144,8 +180,8 @@ 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;
@@ -153,6 +189,13 @@ interface Check {
 interface Extra1 {
     [k: string]: unknown;
 }
+/**
+ * Edge metadata for a Check↔Observable association.
+ */
+interface ObservableLink {
+    observable_key: string;
+    propagation_mode?: PropagationMode;
+}
 /**
  * Check keys organized by level name.
  */
@@ -277,19 +320,12 @@ interface ThreatIntelBySource {
 interface ThreatIntelByLevel {
     [k: string]: number;
 }
-/**
- * Schema for check statistics summary.
- */
-interface StatsChecksSchema {
-    checks: number;
-    applied: number;
-}
 /**
  * Schema for data extraction metadata.
  */
 interface DataExtractionSchema {
     root_type?: RootType;
-    score_mode: ScoreMode;
+    score_mode_obs: ScoreMode;
 }
 
 declare function parseCyvest(json: unknown): CyvestInvestigation;
@@ -782,13 +818,6 @@ declare function getWhitelists(inv: CyvestInvestigation): Whitelists;
  * @returns Statistics object
  */
 declare function getStats(inv: CyvestInvestigation): StatisticsSchema;
-/**
- * Get the investigation check statistics.
- *
- * @param inv - The investigation
- * @returns Check statistics object
- */
-declare function getStatsChecks(inv: CyvestInvestigation): StatsChecksSchema;
 /**
  * Get the data extraction configuration.
  *
@@ -954,13 +983,6 @@ declare function findChecksAtLeast(inv: CyvestInvestigation, minLevel: Level): C
  * @returns Array of matching checks
  */
 declare function findChecksByCheckId(inv: CyvestInvestigation, checkId: string): Check[];
-/**
- * Find checks with score policy set to manual.
- *
- * @param inv - The investigation to search
- * @returns Array of manually scored checks
- */
-declare function findManuallyScored(inv: CyvestInvestigation): Check[];
 /**
  * Find all threat intel from a specific source.
  *
@@ -1334,4 +1356,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type Check, type CheckScorePolicy, type Checks, type Checks1, type ChecksByLevel, type ChecksByLevel1, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Enrichment, type Enrichments, type Extra, type Extra1, type Extra2, type GeneratedByChecks, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type Observable, type Observables, type Observables1, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type StatsChecksSchema, type SubContainers, type Taxonomies, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findManuallyScored, 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, getStatsChecks, 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 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 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 };

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Optional human-readable investigation name.
+ */
+type InvestigationName = string | null;
 /**
  * Security level classification for checks, observables, and threat intelligence.
  *
@@ -9,6 +13,15 @@ type Justification = string | null;
  * List of whitelist entries applied to this investigation.
  */
 type Whitelists = InvestigationWhitelist[];
+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.
@@ -16,14 +29,14 @@ type ThreatIntels = string[];
 type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
 type Relationships = Relationship[];
 /**
- * Checks that generated this observable.
+ * Checks that currently link to this observable (navigation-only).
  */
-type GeneratedByChecks = string[];
-type Observables1 = string[];
+type CheckLinks = string[];
 /**
- * Controls how a check reacts to linked observables.
+ * Controls how a Check↔Observable link propagates across merged investigations.
  */
-type CheckScorePolicy = "auto" | "manual";
+type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
+type ObservableLinks = ObservableLink[];
 type Taxonomies = {
     [k: string]: unknown;
 }[];
@@ -31,7 +44,7 @@ type Checks1 = string[];
 /**
  * Root observable type used during data extraction.
  */
-type RootType = string | null;
+type RootType = ("file" | "artifact") | null;
 /**
  * Score calculation mode for observables.
  */
@@ -47,6 +60,11 @@ type ScoreMode = "max" | "sum";
  * schemas matching the actual model_dump() output.
  */
 interface CyvestInvestigation {
+    /**
+     * Stable investigation identity (ULID).
+     */
+    investigation_id: string;
+    investigation_name?: InvestigationName;
     /**
      * Investigation start time (UTC).
      */
@@ -61,6 +79,7 @@ interface CyvestInvestigation {
      */
     whitelisted: boolean;
     whitelists: Whitelists;
+    event_log?: EventLog;
     observables: Observables;
     checks: Checks;
     checks_by_level: ChecksByLevel;
@@ -68,7 +87,6 @@ interface CyvestInvestigation {
     enrichments: Enrichments;
     containers: Containers;
     stats: StatisticsSchema;
-    stats_checks: StatsChecksSchema;
     data_extraction: DataExtractionSchema;
     /**
      * Global investigation score formatted as fixed-point x.xx.
@@ -84,6 +102,24 @@ interface InvestigationWhitelist {
     justification?: Justification;
     [k: string]: unknown;
 }
+/**
+ * Centralized audit event for investigation-level changes.
+ */
+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;
+}
+interface Details {
+    [k: string]: unknown;
+}
 /**
  * Observables keyed by their unique key.
  */
@@ -108,7 +144,7 @@ interface Observable {
     threat_intels: ThreatIntels;
     relationships: Relationships;
     key: string;
-    generated_by_checks: GeneratedByChecks;
+    check_links: CheckLinks;
     score_display: string;
     [k: string]: unknown;
 }
@@ -144,8 +180,8 @@ 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;
@@ -153,6 +189,13 @@ interface Check {
 interface Extra1 {
     [k: string]: unknown;
 }
+/**
+ * Edge metadata for a Check↔Observable association.
+ */
+interface ObservableLink {
+    observable_key: string;
+    propagation_mode?: PropagationMode;
+}
 /**
  * Check keys organized by level name.
  */
@@ -277,19 +320,12 @@ interface ThreatIntelBySource {
 interface ThreatIntelByLevel {
     [k: string]: number;
 }
-/**
- * Schema for check statistics summary.
- */
-interface StatsChecksSchema {
-    checks: number;
-    applied: number;
-}
 /**
  * Schema for data extraction metadata.
  */
 interface DataExtractionSchema {
     root_type?: RootType;
-    score_mode: ScoreMode;
+    score_mode_obs: ScoreMode;
 }
 
 declare function parseCyvest(json: unknown): CyvestInvestigation;
@@ -782,13 +818,6 @@ declare function getWhitelists(inv: CyvestInvestigation): Whitelists;
  * @returns Statistics object
  */
 declare function getStats(inv: CyvestInvestigation): StatisticsSchema;
-/**
- * Get the investigation check statistics.
- *
- * @param inv - The investigation
- * @returns Check statistics object
- */
-declare function getStatsChecks(inv: CyvestInvestigation): StatsChecksSchema;
 /**
  * Get the data extraction configuration.
  *
@@ -954,13 +983,6 @@ declare function findChecksAtLeast(inv: CyvestInvestigation, minLevel: Level): C
  * @returns Array of matching checks
  */
 declare function findChecksByCheckId(inv: CyvestInvestigation, checkId: string): Check[];
-/**
- * Find checks with score policy set to manual.
- *
- * @param inv - The investigation to search
- * @returns Array of manually scored checks
- */
-declare function findManuallyScored(inv: CyvestInvestigation): Check[];
 /**
  * Find all threat intel from a specific source.
  *
@@ -1334,4 +1356,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type Check, type CheckScorePolicy, type Checks, type Checks1, type ChecksByLevel, type ChecksByLevel1, type ChecksByScope, type Container, type Containers, type CyvestInvestigation, type Data, type DataExtractionSchema, type Enrichment, type Enrichments, type Extra, type Extra1, type Extra2, type GeneratedByChecks, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type InvestigationWhitelist, type Justification, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type Observable, type Observables, type Observables1, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type Relationship, type RelationshipDirection, type Relationships, type RootType, type ScoreMode, type StatisticsSchema, type StatsChecksSchema, type SubContainers, type Taxonomies, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type Whitelists, areConnected, compareLevels, countRelationshipsByType, findChecksAtLeast, findChecksByCheckId, findChecksByLevel, findChecksByScope, findContainersAtLeast, findContainersByLevel, findExternalObservables, findInternalObservables, findLeafObservables, findManuallyScored, 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, getStatsChecks, 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 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 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 };