@cyvest/cyvest-js 3.1.0 → 4.0.0

package/dist/index.d.mts

@@ -1,84 +1,46 @@
 /**
- * Investigation start time (UTC).
+ * Optional human-readable investigation name.
  */
-type StartedAt = string;
-/**
- * Global investigation score.
- */
-type Score = number;
+type InvestigationName = string | null;
 /**
  * Security level classification for checks, observables, and threat intelligence.
  *
  * Levels are ordered from lowest (NONE) to highest (MALICIOUS) severity.
  */
 type Level = "NONE" | "TRUSTED" | "INFO" | "SAFE" | "NOTABLE" | "SUSPICIOUS" | "MALICIOUS";
-/**
- * Whether the investigation is whitelisted.
- */
-type Whitelisted = boolean;
-type Identifier = string;
-type Name = string;
 type Justification = string | null;
 /**
  * List of whitelist entries applied to this investigation.
  */
 type Whitelists = InvestigationWhitelist[];
-type Type = string;
-type Value = string;
-type Internal = boolean;
-type Whitelisted1 = boolean;
-type Comment = string;
-type Score1 = number;
+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[];
-type TargetKey = string;
-type RelationshipType = string;
 /**
  * Direction of a relationship between observables.
  */
 type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
 type Relationships = Relationship[];
-type Key = string;
-/**
- * Checks that generated this observable.
- */
-type GeneratedByChecks = string[];
-type CheckId = string;
-type Scope = string;
-type Description = string;
-type Comment1 = string;
-type Score2 = number;
-type Observables1 = string[];
-/**
- * Controls how a check reacts to linked observables.
- */
-type CheckScorePolicy = "auto" | "manual";
-type Key1 = string;
-type Source = string;
-type ObservableKey = string;
-type Comment2 = string;
-type Score3 = number;
+/**
+ * Checks that currently link to this observable (navigation-only).
+ */
+type CheckLinks = string[];
+/**
+ * Controls how a Check↔Observable link propagates across merged investigations.
+ */
+type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
+type ObservableLinks = ObservableLink[];
 type Taxonomies = {
     [k: string]: unknown;
 }[];
-type Key2 = string;
-type Name1 = string;
-type Context = string;
-type Key3 = string;
-type Path = string;
-type Description1 = string;
 type Checks1 = string[];
-type Key4 = string;
-type AggregatedScore = number;
-type TotalObservables = number;
-type InternalObservables = number;
-type ExternalObservables = number;
-type WhitelistedObservables = number;
-type TotalChecks = number;
-type AppliedChecks = number;
-type TotalThreatIntel = number;
-type TotalContainers = number;
-type Checks2 = number;
-type Applied = number;
 /**
  * Root observable type used during data extraction.
  */
@@ -98,11 +60,26 @@ type ScoreMode = "max" | "sum";
  * schemas matching the actual model_dump() output.
  */
 interface CyvestInvestigation {
-    started_at: StartedAt;
-    score: Score;
+    /**
+     * Stable investigation identity (ULID).
+     */
+    investigation_id: string;
+    investigation_name?: InvestigationName;
+    /**
+     * Investigation start time (UTC).
+     */
+    started_at: string;
+    /**
+     * Global investigation score.
+     */
+    score: number;
     level: Level;
-    whitelisted: Whitelisted;
+    /**
+     * Whether the investigation is whitelisted.
+     */
+    whitelisted: boolean;
     whitelists: Whitelists;
+    event_log?: EventLog;
     observables: Observables;
     checks: Checks;
     checks_by_level: ChecksByLevel;
@@ -112,16 +89,38 @@ interface CyvestInvestigation {
     stats: StatisticsSchema;
     stats_checks: StatsChecksSchema;
     data_extraction: DataExtractionSchema;
+    /**
+     * Global investigation score formatted as fixed-point x.xx.
+     */
+    score_display: string;
 }
 /**
  * Represents a whitelist entry on an investigation.
  */
 interface InvestigationWhitelist {
-    identifier: Identifier;
-    name: Name;
+    identifier: string;
+    name: string;
     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.
  */
@@ -135,18 +134,19 @@ interface Observables {
  * through relationships.
  */
 interface Observable {
-    type: Type;
-    value: Value;
-    internal: Internal;
-    whitelisted: Whitelisted1;
-    comment: Comment;
+    type: string;
+    value: string;
+    internal: boolean;
+    whitelisted: boolean;
+    comment: string;
     extra: Extra;
-    score: Score1;
+    score: number;
     level: Level;
     threat_intels: ThreatIntels;
     relationships: Relationships;
-    key: Key;
-    generated_by_checks: GeneratedByChecks;
+    key: string;
+    check_links: CheckLinks;
+    score_display: string;
     [k: string]: unknown;
 }
 interface Extra {
@@ -156,8 +156,8 @@ interface Extra {
  * Represents a relationship between observables.
  */
 interface Relationship {
-    target_key: TargetKey;
-    relationship_type: RelationshipType;
+    target_key: string;
+    relationship_type: string;
     direction: RelationshipDirection;
     [k: string]: unknown;
 }
@@ -174,21 +174,29 @@ interface Checks {
  * and contributes to the overall investigation score.
  */
 interface Check {
-    check_id: CheckId;
-    scope: Scope;
-    description: Description;
-    comment: Comment1;
+    check_id: string;
+    scope: string;
+    description: string;
+    comment: string;
     extra: Extra1;
-    score: Score2;
+    score: number;
     level: Level;
-    observables: Observables1;
-    score_policy?: CheckScorePolicy;
-    key: Key1;
+    origin_investigation_id: string;
+    observable_links: ObservableLinks;
+    key: string;
+    score_display: string;
     [k: string]: unknown;
 }
 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.
  */
@@ -208,14 +216,15 @@ interface ThreatIntels1 {
  * like VirusTotal, URLScan.io, etc.
  */
 interface ThreatIntel {
-    source: Source;
-    observable_key: ObservableKey;
-    comment: Comment2;
+    source: string;
+    observable_key: string;
+    comment: string;
     extra: Extra2;
-    score: Score3;
+    score: number;
     level: Level;
     taxonomies: Taxonomies;
-    key: Key2;
+    key: string;
+    score_display: string;
     [k: string]: unknown;
 }
 interface Extra2 {
@@ -234,10 +243,10 @@ interface Enrichments {
  * context but doesn't directly contribute to scoring.
  */
 interface Enrichment {
-    name: Name1;
+    name: string;
     data: Data;
-    context: Context;
-    key: Key3;
+    context: string;
+    key: string;
     [k: string]: unknown;
 }
 interface Data {
@@ -256,12 +265,12 @@ interface Containers {
  * with aggregated scores and levels.
  */
 interface Container {
-    path: Path;
-    description?: Description1;
+    path: string;
+    description?: string;
     checks: Checks1;
     sub_containers: SubContainers;
-    key: Key4;
-    aggregated_score: AggregatedScore;
+    key: string;
+    aggregated_score: number;
     aggregated_level: Level;
 }
 interface SubContainers {
@@ -273,21 +282,21 @@ interface SubContainers {
  * Mirrors the output of `InvestigationStats.get_summary()`.
  */
 interface StatisticsSchema {
-    total_observables: TotalObservables;
-    internal_observables: InternalObservables;
-    external_observables: ExternalObservables;
-    whitelisted_observables: WhitelistedObservables;
+    total_observables: number;
+    internal_observables: number;
+    external_observables: number;
+    whitelisted_observables: number;
     observables_by_type?: ObservablesByType;
     observables_by_level?: ObservablesByLevel;
     observables_by_type_and_level?: ObservablesByTypeAndLevel;
-    total_checks: TotalChecks;
-    applied_checks: AppliedChecks;
+    total_checks: number;
+    applied_checks: number;
     checks_by_scope?: ChecksByScope;
     checks_by_level?: ChecksByLevel1;
-    total_threat_intel: TotalThreatIntel;
+    total_threat_intel: number;
     threat_intel_by_source?: ThreatIntelBySource;
     threat_intel_by_level?: ThreatIntelByLevel;
-    total_containers: TotalContainers;
+    total_containers: number;
 }
 interface ObservablesByType {
     [k: string]: number;
@@ -316,8 +325,8 @@ interface ThreatIntelByLevel {
  * Schema for check statistics summary.
  */
 interface StatsChecksSchema {
-    checks: Checks2;
-    applied: Applied;
+    checks: number;
+    applied: number;
 }
 /**
  * Schema for data extraction metadata.
@@ -989,13 +998,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.
  *
@@ -1369,4 +1371,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type AggregatedScore, type Applied, type AppliedChecks, type Check, type CheckId, type CheckScorePolicy, type Checks, type Checks1, type Checks2, type ChecksByLevel, type ChecksByLevel1, type ChecksByScope, type Comment, type Comment1, type Comment2, type Container, type Containers, type Context, type CyvestInvestigation, type Data, type DataExtractionSchema, type Description, type Description1, type Enrichment, type Enrichments, type ExternalObservables, type Extra, type Extra1, type Extra2, type GeneratedByChecks, type GraphEdge, type GraphNode, type Identifier, type Internal, type InternalObservables, type InvestigationCounts, type InvestigationGraph, type InvestigationWhitelist, type Justification, type Key, type Key1, type Key2, type Key3, type Key4, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type Name, type Name1, type Observable, type ObservableKey, type Observables, type Observables1, type ObservablesByLevel, type ObservablesByType, type ObservablesByTypeAndLevel, type Path, type Relationship, type RelationshipDirection, type RelationshipType, type Relationships, type RootType, type Scope, type Score, type Score1, type Score2, type Score3, type ScoreMode, type Source, type StartedAt, type StatisticsSchema, type StatsChecksSchema, type SubContainers, type TargetKey, type Taxonomies, type ThreatIntel, type ThreatIntelByLevel, type ThreatIntelBySource, type ThreatIntels, type ThreatIntels1, type TotalChecks, type TotalContainers, type TotalObservables, type TotalThreatIntel, type Type, type Value, type Whitelisted, type Whitelisted1, type WhitelistedObservables, 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 StatsChecksSchema, 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, 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 };