@cyvest/cyvest-js 2.0.1 → 3.0.1

package/dist/index.d.ts

@@ -1,167 +1,324 @@
 /**
- * Security level classification from NONE (lowest) to MALICIOUS (highest).
+ * Global investigation score.
+ */
+type Score = number;
+/**
+ * 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";
 /**
- * Direction of a relationship between observables.
+ * Whether the investigation is whitelisted.
  */
-type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
+type Whitelisted = boolean;
+type Identifier = string;
+type Name = string;
+type Justification = string | null;
 /**
- * Score computation policy: 'auto' calculates from level, 'manual' uses explicit score.
+ * List of whitelist entries applied to this investigation.
  */
-type ScorePolicy = "auto" | "manual";
+type Whitelists = InvestigationWhitelist[];
+type Type = string;
+type Value = string;
+type Internal = boolean;
+type Whitelisted1 = boolean;
+type Comment = string;
+type Score1 = number;
+type ThreatIntels = string[];
+type TargetKey = string;
+type RelationshipType = string;
 /**
- * Score aggregation mode: 'max' takes highest score, 'sum' adds all scores.
+ * 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;
+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.
+ */
+type RootType = string | null;
+/**
+ * Score calculation mode for observables.
  */
 type ScoreMode = "max" | "sum";
+/**
+ * Schema for a complete serialized investigation.
+ *
+ * This model describes the output of `serialize_investigation()` from
+ * `cyvest.io_serialization`. It is the top-level schema for exported investigations.
+ *
+ * Entity types reference the runtime models directly. When generating schemas with
+ * `mode='serialization'`, Pydantic respects field_serializer decorators and produces
+ * schemas matching the actual model_dump() output.
+ */
 interface CyvestInvestigation {
-    score: number;
+    score: Score;
     level: Level;
-    whitelisted: boolean;
-    whitelists: Whitelist[];
-    observables: {
-        [k: string]: Observable;
-    };
-    checks: {
-        [k: string]: Check[];
-    };
-    checks_by_level: {
-        [k: string]: string[];
-    };
-    threat_intels: {
-        [k: string]: ThreatIntel;
-    };
-    enrichments: {
-        [k: string]: Enrichment;
-    };
-    containers: {
-        [k: string]: Container;
-    };
-    stats: Statistics;
-    stats_checks: StatsChecks;
-    data_extraction: DataExtraction;
+    whitelisted: Whitelisted;
+    whitelists: Whitelists;
+    observables: Observables;
+    checks: Checks;
+    checks_by_level: ChecksByLevel;
+    threat_intels: ThreatIntels1;
+    enrichments: Enrichments;
+    containers: Containers;
+    stats: StatisticsSchema;
+    stats_checks: StatsChecksSchema;
+    data_extraction: DataExtractionSchema;
+}
+/**
+ * Represents a whitelist entry on an investigation.
+ */
+interface InvestigationWhitelist {
+    identifier: Identifier;
+    name: Name;
+    justification?: Justification;
+    [k: string]: unknown;
 }
-interface Whitelist {
-    identifier: string;
-    name: string;
-    justification?: string | null;
+/**
+ * Observables keyed by their unique key.
+ */
+interface Observables {
+    [k: string]: Observable;
 }
+/**
+ * Represents a cyber observable (IP, URL, domain, hash, etc.).
+ *
+ * Observables can be linked to threat intelligence, checks, and other observables
+ * through relationships.
+ */
 interface Observable {
-    key: string;
-    /**
-     * Observable type (e.g., ipv4-addr, url). Custom values are allowed.
-     */
-    type: string;
-    value: string;
-    internal: boolean;
-    whitelisted: boolean;
-    comment: string;
-    extra: {
-        [k: string]: unknown;
-    } | null;
-    score: number;
+    type: Type;
+    value: Value;
+    internal: Internal;
+    whitelisted: Whitelisted1;
+    comment: Comment;
+    extra: Extra;
+    score: Score1;
     level: Level;
-    relationships: Relationship[];
-    threat_intels: string[];
-    generated_by_checks: string[];
+    threat_intels: ThreatIntels;
+    relationships: Relationships;
+    key: Key;
+    generated_by_checks: GeneratedByChecks;
+    [k: string]: unknown;
+}
+interface Extra {
+    [k: string]: unknown;
 }
+/**
+ * Represents a relationship between observables.
+ */
 interface Relationship {
-    target_key: string;
-    /**
-     * Relationship label; defaults to related-to.
-     */
-    relationship_type: string;
+    target_key: TargetKey;
+    relationship_type: RelationshipType;
     direction: RelationshipDirection;
+    [k: string]: unknown;
+}
+/**
+ * Checks organized by scope.
+ */
+interface Checks {
+    [k: string]: Check[];
 }
+/**
+ * Represents a verification step in the investigation.
+ *
+ * A check validates a specific aspect of the data under investigation
+ * and contributes to the overall investigation score.
+ */
 interface Check {
-    key: string;
-    check_id: string;
-    scope: string;
-    description: string;
-    comment: string;
-    extra: {
-        [k: string]: unknown;
-    } | null;
-    score: number;
+    check_id: CheckId;
+    scope: Scope;
+    description: Description;
+    comment: Comment1;
+    extra: Extra1;
+    score: Score2;
     level: Level;
-    score_policy: ScorePolicy;
-    observables: string[];
+    observables: Observables1;
+    score_policy?: CheckScorePolicy;
+    key: Key1;
+    [k: string]: unknown;
+}
+interface Extra1 {
+    [k: string]: unknown;
+}
+/**
+ * Check keys organized by level name.
+ */
+interface ChecksByLevel {
+    [k: string]: string[];
 }
+/**
+ * Threat intelligence entries keyed by their unique key.
+ */
+interface ThreatIntels1 {
+    [k: string]: ThreatIntel;
+}
+/**
+ * Represents threat intelligence from an external source.
+ *
+ * Threat intelligence provides verdicts about observables from sources
+ * like VirusTotal, URLScan.io, etc.
+ */
 interface ThreatIntel {
-    key: string;
-    source: string;
-    observable_key: string;
-    comment: string;
-    extra: {
-        [k: string]: unknown;
-    } | null;
-    score: number;
+    source: Source;
+    observable_key: ObservableKey;
+    comment: Comment2;
+    extra: Extra2;
+    score: Score3;
     level: Level;
-    taxonomies: {
-        [k: string]: unknown;
-    }[];
+    taxonomies: Taxonomies;
+    key: Key2;
+    [k: string]: unknown;
+}
+interface Extra2 {
+    [k: string]: unknown;
+}
+/**
+ * Enrichment entries keyed by their unique key.
+ */
+interface Enrichments {
+    [k: string]: Enrichment;
 }
+/**
+ * Represents structured data enrichment for the investigation.
+ *
+ * Enrichments store arbitrary structured data that provides additional
+ * context but doesn't directly contribute to scoring.
+ */
 interface Enrichment {
-    key: string;
-    name: string;
-    data: {
-        [k: string]: unknown;
-    };
-    context: string;
+    name: Name1;
+    data: Data;
+    context: Context;
+    key: Key3;
+    [k: string]: unknown;
+}
+interface Data {
+    [k: string]: unknown;
+}
+/**
+ * Containers keyed by their unique key.
+ */
+interface Containers {
+    [k: string]: Container;
 }
+/**
+ * Groups checks and sub-containers for hierarchical organization.
+ *
+ * Containers allow structuring the investigation into logical sections
+ * with aggregated scores and levels.
+ */
 interface Container {
-    key: string;
-    path: string;
-    description: string;
-    checks: string[];
-    sub_containers: {
-        [k: string]: Container;
-    };
-    aggregated_score: number;
+    path: Path;
+    description?: Description1;
+    checks: Checks1;
+    sub_containers: SubContainers;
+    key: Key4;
+    aggregated_score: AggregatedScore;
     aggregated_level: Level;
 }
-interface Statistics {
-    total_observables: number;
-    internal_observables: number;
-    external_observables: number;
-    whitelisted_observables: number;
-    observables_by_type: {
-        [k: string]: number;
-    };
-    observables_by_level: {
-        [k: string]: number;
-    };
-    observables_by_type_and_level: {
-        [k: string]: {
-            [k: string]: number;
-        };
-    };
-    total_checks: number;
-    applied_checks: number;
-    checks_by_scope: {
-        [k: string]: number;
-    };
-    checks_by_level: {
-        [k: string]: number;
-    };
-    total_threat_intel: number;
-    threat_intel_by_source: {
-        [k: string]: number;
-    };
-    threat_intel_by_level: {
+interface SubContainers {
+    [k: string]: Container;
+}
+/**
+ * Schema for investigation statistics.
+ *
+ * Mirrors the output of `InvestigationStats.get_summary()`.
+ */
+interface StatisticsSchema {
+    total_observables: TotalObservables;
+    internal_observables: InternalObservables;
+    external_observables: ExternalObservables;
+    whitelisted_observables: WhitelistedObservables;
+    observables_by_type?: ObservablesByType;
+    observables_by_level?: ObservablesByLevel;
+    observables_by_type_and_level?: ObservablesByTypeAndLevel;
+    total_checks: TotalChecks;
+    applied_checks: AppliedChecks;
+    checks_by_scope?: ChecksByScope;
+    checks_by_level?: ChecksByLevel1;
+    total_threat_intel: TotalThreatIntel;
+    threat_intel_by_source?: ThreatIntelBySource;
+    threat_intel_by_level?: ThreatIntelByLevel;
+    total_containers: TotalContainers;
+}
+interface ObservablesByType {
+    [k: string]: number;
+}
+interface ObservablesByLevel {
+    [k: string]: number;
+}
+interface ObservablesByTypeAndLevel {
+    [k: string]: {
         [k: string]: number;
     };
-    total_containers: number;
 }
-interface StatsChecks {
-    checks: number;
-    applied: number;
+interface ChecksByScope {
+    [k: string]: number;
+}
+interface ChecksByLevel1 {
+    [k: string]: number;
+}
+interface ThreatIntelBySource {
+    [k: string]: number;
 }
-interface DataExtraction {
-    /**
-     * Root observable type used during data extraction.
-     */
-    root_type: string | null;
+interface ThreatIntelByLevel {
+    [k: string]: number;
+}
+/**
+ * Schema for check statistics summary.
+ */
+interface StatsChecksSchema {
+    checks: Checks2;
+    applied: Applied;
+}
+/**
+ * Schema for data extraction metadata.
+ */
+interface DataExtractionSchema {
+    root_type?: RootType;
     score_mode: ScoreMode;
 }
 
@@ -647,28 +804,28 @@ declare function getAllObservables(inv: CyvestInvestigation): Observable[];
  * @param inv - The investigation
  * @returns Array of all whitelists
  */
-declare function getWhitelists(inv: CyvestInvestigation): Whitelist[];
+declare function getWhitelists(inv: CyvestInvestigation): Whitelists;
 /**
  * Get the investigation statistics.
  *
  * @param inv - The investigation
  * @returns Statistics object
  */
-declare function getStats(inv: CyvestInvestigation): Statistics;
+declare function getStats(inv: CyvestInvestigation): StatisticsSchema;
 /**
  * Get the investigation check statistics.
  *
  * @param inv - The investigation
  * @returns Check statistics object
  */
-declare function getStatsChecks(inv: CyvestInvestigation): StatsChecks;
+declare function getStatsChecks(inv: CyvestInvestigation): StatsChecksSchema;
 /**
  * Get the data extraction configuration.
  *
  * @param inv - The investigation
  * @returns Data extraction config
  */
-declare function getDataExtraction(inv: CyvestInvestigation): DataExtraction;
+declare function getDataExtraction(inv: CyvestInvestigation): DataExtractionSchema;
 /**
  * Count entities in the investigation.
  */
@@ -1207,4 +1364,4 @@ declare function getRelationshipsForObservable(inv: CyvestInvestigation, observa
     }>;
 };
 
-export { type Check, type Container, type CyvestInvestigation, type DataExtraction, type Enrichment, type GraphEdge, type GraphNode, type InvestigationCounts, type InvestigationGraph, type KeyType, LEVEL_COLORS, LEVEL_ORDER, LEVEL_VALUES, type Level, type Observable, type Relationship, type RelationshipDirection, type ScoreMode, type ScorePolicy, type Statistics, type StatsChecks, type ThreatIntel, type Whitelist, 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 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 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 };