@cyvest/cyvest-js 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,1210 @@
+/**
+ * Security level classification from NONE (lowest) to MALICIOUS (highest).
+ */
+type Level = "NONE" | "TRUSTED" | "INFO" | "SAFE" | "NOTABLE" | "SUSPICIOUS" | "MALICIOUS";
+/**
+ * Direction of a relationship between observables.
+ */
+type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
+/**
+ * Score computation policy: 'auto' calculates from level, 'manual' uses explicit score.
+ */
+type ScorePolicy = "auto" | "manual";
+/**
+ * Score aggregation mode: 'max' takes highest score, 'sum' adds all scores.
+ */
+type ScoreMode = "max" | "sum";
+interface CyvestInvestigation {
+    score: number;
+    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;
+}
+interface Whitelist {
+    identifier: string;
+    name: string;
+    justification?: string | null;
+}
+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;
+    level: Level;
+    relationships: Relationship[];
+    threat_intels: string[];
+    generated_by_checks: string[];
+}
+interface Relationship {
+    target_key: string;
+    /**
+     * Relationship label; defaults to related-to.
+     */
+    relationship_type: string;
+    direction: RelationshipDirection;
+}
+interface Check {
+    key: string;
+    check_id: string;
+    scope: string;
+    description: string;
+    comment: string;
+    extra: {
+        [k: string]: unknown;
+    } | null;
+    score: number;
+    level: Level;
+    score_policy: ScorePolicy;
+    observables: string[];
+}
+interface ThreatIntel {
+    key: string;
+    source: string;
+    observable_key: string;
+    comment: string;
+    extra: {
+        [k: string]: unknown;
+    } | null;
+    score: number;
+    level: Level;
+    taxonomies: {
+        [k: string]: unknown;
+    }[];
+}
+interface Enrichment {
+    key: string;
+    name: string;
+    data: {
+        [k: string]: unknown;
+    };
+    context: string;
+}
+interface Container {
+    key: string;
+    path: string;
+    description: string;
+    checks: string[];
+    sub_containers: {
+        [k: string]: Container;
+    };
+    aggregated_score: number;
+    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: {
+        [k: string]: number;
+    };
+    total_containers: number;
+}
+interface StatsChecks {
+    checks: number;
+    applied: number;
+}
+interface DataExtraction {
+    /**
+     * Root observable type used during data extraction.
+     */
+    root_type: string | null;
+    score_mode: ScoreMode;
+}
+
+declare function parseCyvest(json: unknown): CyvestInvestigation;
+declare function isCyvest(json: unknown): json is CyvestInvestigation;
+
+/**
+ * Key generation utilities for Cyvest objects.
+ *
+ * Provides deterministic, unique key generation for all object types.
+ * Keys are used for object identification, retrieval, and merging.
+ */
+/**
+ * Key type prefixes used in Cyvest.
+ */
+type KeyType = "obs" | "chk" | "ti" | "enr" | "ctr";
+/**
+ * Generate a unique key for an observable.
+ *
+ * Format: obs:{type}:{normalized_value}
+ *
+ * @param obsType - Type of observable (ip, url, domain, hash, etc.)
+ * @param value - Value of the observable
+ * @returns Unique observable key
+ *
+ * @example
+ * ```ts
+ * generateObservableKey("ipv4-addr", "192.168.1.1")
+ * // => "obs:ipv4-addr:192.168.1.1"
+ * ```
+ */
+declare function generateObservableKey(obsType: string, value: string): string;
+/**
+ * Generate a unique key for a check.
+ *
+ * Format: chk:{check_id}:{scope}
+ *
+ * @param checkId - Identifier of the check
+ * @param scope - Scope of the check
+ * @returns Unique check key
+ *
+ * @example
+ * ```ts
+ * generateCheckKey("sender_verification", "email_headers")
+ * // => "chk:sender_verification:email_headers"
+ * ```
+ */
+declare function generateCheckKey(checkId: string, scope: string): string;
+/**
+ * Generate a unique key for threat intelligence.
+ *
+ * Format: ti:{normalized_source}:{observable_key}
+ *
+ * @param source - Name of the threat intel source
+ * @param observableKey - Key of the related observable
+ * @returns Unique threat intel key
+ *
+ * @example
+ * ```ts
+ * generateThreatIntelKey("virustotal", "obs:ipv4-addr:192.168.1.1")
+ * // => "ti:virustotal:obs:ipv4-addr:192.168.1.1"
+ * ```
+ */
+declare function generateThreatIntelKey(source: string, observableKey: string): string;
+/**
+ * Generate a unique key for an enrichment.
+ *
+ * Format: enr:{name} or enr:{name}:{context_hash}
+ *
+ * @param name - Name of the enrichment
+ * @param context - Optional context string for disambiguation
+ * @returns Unique enrichment key
+ *
+ * @example
+ * ```ts
+ * generateEnrichmentKey("whois_data")
+ * // => "enr:whois_data"
+ *
+ * generateEnrichmentKey("whois_data", "domain:example.com")
+ * // => "enr:whois_data:a1b2c3d4"
+ * ```
+ */
+declare function generateEnrichmentKey(name: string, context?: string): string;
+/**
+ * Generate a unique key for a container.
+ *
+ * Format: ctr:{normalized_path}
+ *
+ * @param path - Path of the container (can use / or . as separator)
+ * @returns Unique container key
+ *
+ * @example
+ * ```ts
+ * generateContainerKey("email/headers")
+ * // => "ctr:email/headers"
+ * ```
+ */
+declare function generateContainerKey(path: string): string;
+/**
+ * Extract the type prefix from a key.
+ *
+ * @param key - The key to parse
+ * @returns Type prefix (obs, chk, ti, enr, ctr) or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseKeyType("obs:ipv4-addr:192.168.1.1") // => "obs"
+ * parseKeyType("invalid") // => null
+ * ```
+ */
+declare function parseKeyType(key: string): KeyType | null;
+/**
+ * Validate a key format and optionally check its type.
+ *
+ * @param key - The key to validate
+ * @param expectedType - Optional expected type prefix
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * validateKey("obs:ipv4-addr:192.168.1.1") // => true
+ * validateKey("obs:ipv4-addr:192.168.1.1", "obs") // => true
+ * validateKey("obs:ipv4-addr:192.168.1.1", "chk") // => false
+ * validateKey("invalid") // => false
+ * ```
+ */
+declare function validateKey(key: string, expectedType?: KeyType): boolean;
+/**
+ * Extract components from an observable key.
+ *
+ * @param key - Observable key to parse
+ * @returns Object with type and value, or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseObservableKey("obs:ipv4-addr:192.168.1.1")
+ * // => { type: "ipv4-addr", value: "192.168.1.1" }
+ * ```
+ */
+declare function parseObservableKey(key: string): {
+    type: string;
+    value: string;
+} | null;
+/**
+ * Extract components from a check key.
+ *
+ * @param key - Check key to parse
+ * @returns Object with checkId and scope, or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseCheckKey("chk:sender_verification:email_headers")
+ * // => { checkId: "sender_verification", scope: "email_headers" }
+ * ```
+ */
+declare function parseCheckKey(key: string): {
+    checkId: string;
+    scope: string;
+} | null;
+/**
+ * Extract components from a threat intel key.
+ *
+ * @param key - Threat intel key to parse
+ * @returns Object with source and observableKey, or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseThreatIntelKey("ti:virustotal:obs:ipv4-addr:192.168.1.1")
+ * // => { source: "virustotal", observableKey: "obs:ipv4-addr:192.168.1.1" }
+ * ```
+ */
+declare function parseThreatIntelKey(key: string): {
+    source: string;
+    observableKey: string;
+} | null;
+
+/**
+ * Level enumeration and scoring logic for Cyvest.
+ *
+ * This module defines the security level classification system and the algorithm
+ * for determining levels from scores.
+ */
+
+/**
+ * Ordered array of levels from lowest to highest severity.
+ */
+declare const LEVEL_ORDER: readonly Level[];
+/**
+ * Numeric values for each level (for comparison purposes).
+ */
+declare const LEVEL_VALUES: Record<Level, number>;
+/**
+ * Color mapping for display purposes.
+ */
+declare const LEVEL_COLORS: Record<Level, string>;
+/**
+ * Normalize a level input to the Level type.
+ *
+ * Accepts a case-insensitive string and returns the normalized Level.
+ *
+ * @param level - Level string (e.g., "malicious", "MALICIOUS")
+ * @returns The normalized Level
+ * @throws Error if the string does not match a valid Level
+ *
+ * @example
+ * ```ts
+ * normalizeLevel("malicious") // => "MALICIOUS"
+ * normalizeLevel("TRUSTED") // => "TRUSTED"
+ * ```
+ */
+declare function normalizeLevel(level: string): Level;
+/**
+ * Check if a string is a valid Level.
+ *
+ * @param level - String to check
+ * @returns True if valid Level
+ */
+declare function isValidLevel(level: string): level is Level;
+/**
+ * Calculate the security level from a numeric score.
+ *
+ * Algorithm:
+ * - score < 0.0  -> TRUSTED
+ * - score === 0.0 -> INFO
+ * - score < 3.0  -> NOTABLE
+ * - score < 5.0  -> SUSPICIOUS
+ * - score >= 5.0 -> MALICIOUS
+ *
+ * @param score - The numeric score to evaluate
+ * @returns The appropriate Level based on the score
+ *
+ * @example
+ * ```ts
+ * getLevelFromScore(-1) // => "TRUSTED"
+ * getLevelFromScore(0) // => "INFO"
+ * getLevelFromScore(2.5) // => "NOTABLE"
+ * getLevelFromScore(4) // => "SUSPICIOUS"
+ * getLevelFromScore(5) // => "MALICIOUS"
+ * ```
+ */
+declare function getLevelFromScore(score: number): Level;
+/**
+ * Compare two levels.
+ *
+ * @param a - First level
+ * @param b - Second level
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ *
+ * @example
+ * ```ts
+ * compareLevels("INFO", "MALICIOUS") // => -1
+ * compareLevels("MALICIOUS", "INFO") // => 1
+ * compareLevels("INFO", "INFO") // => 0
+ * ```
+ */
+declare function compareLevels(a: Level, b: Level): -1 | 0 | 1;
+/**
+ * Check if level a is higher (more severe) than level b.
+ *
+ * @param a - First level
+ * @param b - Second level
+ * @returns True if a is higher than b
+ *
+ * @example
+ * ```ts
+ * isLevelHigherThan("MALICIOUS", "SUSPICIOUS") // => true
+ * isLevelHigherThan("INFO", "MALICIOUS") // => false
+ * ```
+ */
+declare function isLevelHigherThan(a: Level, b: Level): boolean;
+/**
+ * Check if level a is lower (less severe) than level b.
+ *
+ * @param a - First level
+ * @param b - Second level
+ * @returns True if a is lower than b
+ */
+declare function isLevelLowerThan(a: Level, b: Level): boolean;
+/**
+ * Check if level a is at least as severe as level b.
+ *
+ * @param a - Level to check
+ * @param minLevel - Minimum required level
+ * @returns True if a is at least minLevel
+ *
+ * @example
+ * ```ts
+ * isLevelAtLeast("MALICIOUS", "SUSPICIOUS") // => true
+ * isLevelAtLeast("SUSPICIOUS", "SUSPICIOUS") // => true
+ * isLevelAtLeast("INFO", "SUSPICIOUS") // => false
+ * ```
+ */
+declare function isLevelAtLeast(a: Level, minLevel: Level): boolean;
+/**
+ * Get the maximum (most severe) level from an array of levels.
+ *
+ * @param levels - Array of levels
+ * @returns The most severe level, or "NONE" if array is empty
+ */
+declare function maxLevel(levels: Level[]): Level;
+/**
+ * Get the minimum (least severe) level from an array of levels.
+ *
+ * @param levels - Array of levels
+ * @returns The least severe level, or "MALICIOUS" if array is empty
+ */
+declare function minLevel(levels: Level[]): Level;
+/**
+ * Get the color associated with a level for display purposes.
+ *
+ * @param level - Level to get color for
+ * @returns Hex color string
+ */
+declare function getColorForLevel(level: Level): string;
+/**
+ * Get the color associated with a score for display purposes.
+ *
+ * @param score - Score to get color for
+ * @returns Hex color string
+ */
+declare function getColorForScore(score: number): string;
+/**
+ * Type guard to check if an object has a level property.
+ */
+declare function hasLevel(obj: unknown): obj is {
+    level: Level;
+};
+/**
+ * Extract level from an entity (Observable, Check, ThreatIntel, Container).
+ */
+declare function getEntityLevel(entity: Observable | Check | ThreatIntel | Container): Level;
+
+/**
+ * Get an observable by its key.
+ *
+ * @param inv - The investigation to search
+ * @param key - Observable key (e.g., "obs:ipv4-addr:192.168.1.1")
+ * @returns The observable or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const obs = getObservable(investigation, "obs:ipv4-addr:192.168.1.1");
+ * if (obs) {
+ *   console.log(obs.value, obs.level);
+ * }
+ * ```
+ */
+declare function getObservable(inv: CyvestInvestigation, key: string): Observable | undefined;
+/**
+ * Get an observable by type and value.
+ *
+ * @param inv - The investigation to search
+ * @param type - Observable type (e.g., "ipv4-addr", "url")
+ * @param value - Observable value
+ * @returns The observable or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const obs = getObservableByTypeValue(investigation, "ipv4-addr", "192.168.1.1");
+ * ```
+ */
+declare function getObservableByTypeValue(inv: CyvestInvestigation, type: string, value: string): Observable | undefined;
+/**
+ * Get a check by its key.
+ *
+ * @param inv - The investigation to search
+ * @param key - Check key (e.g., "chk:sender_verification:email_headers")
+ * @returns The check or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const check = getCheck(investigation, "chk:sender_verification:email_headers");
+ * ```
+ */
+declare function getCheck(inv: CyvestInvestigation, key: string): Check | undefined;
+/**
+ * Get a check by its ID and scope.
+ *
+ * @param inv - The investigation to search
+ * @param checkId - Check identifier
+ * @param scope - Check scope
+ * @returns The check or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const check = getCheckByIdScope(investigation, "sender_verification", "email_headers");
+ * ```
+ */
+declare function getCheckByIdScope(inv: CyvestInvestigation, checkId: string, scope: string): Check | undefined;
+/**
+ * Get all checks as a flat array (not grouped by scope).
+ *
+ * @param inv - The investigation
+ * @returns Array of all checks
+ *
+ * @example
+ * ```ts
+ * const allChecks = getAllChecks(investigation);
+ * console.log(`Total checks: ${allChecks.length}`);
+ * ```
+ */
+declare function getAllChecks(inv: CyvestInvestigation): Check[];
+/**
+ * Get a threat intel entry by its key.
+ *
+ * @param inv - The investigation to search
+ * @param key - Threat intel key (e.g., "ti:virustotal:obs:ipv4-addr:192.168.1.1")
+ * @returns The threat intel or undefined if not found
+ */
+declare function getThreatIntel(inv: CyvestInvestigation, key: string): ThreatIntel | undefined;
+/**
+ * Get a threat intel entry by source and observable key.
+ *
+ * @param inv - The investigation to search
+ * @param source - Threat intel source name
+ * @param observableKey - Key of the related observable
+ * @returns The threat intel or undefined if not found
+ */
+declare function getThreatIntelBySourceObservable(inv: CyvestInvestigation, source: string, observableKey: string): ThreatIntel | undefined;
+/**
+ * Get all threat intel entries as an array.
+ *
+ * @param inv - The investigation
+ * @returns Array of all threat intel entries
+ */
+declare function getAllThreatIntels(inv: CyvestInvestigation): ThreatIntel[];
+/**
+ * Get an enrichment by its key.
+ *
+ * @param inv - The investigation to search
+ * @param key - Enrichment key (e.g., "enr:whois_data")
+ * @returns The enrichment or undefined if not found
+ */
+declare function getEnrichment(inv: CyvestInvestigation, key: string): Enrichment | undefined;
+/**
+ * Get an enrichment by name.
+ *
+ * @param inv - The investigation to search
+ * @param name - Enrichment name
+ * @returns The first matching enrichment or undefined if not found
+ */
+declare function getEnrichmentByName(inv: CyvestInvestigation, name: string): Enrichment | undefined;
+/**
+ * Get all enrichments as an array.
+ *
+ * @param inv - The investigation
+ * @returns Array of all enrichments
+ */
+declare function getAllEnrichments(inv: CyvestInvestigation): Enrichment[];
+/**
+ * Get a container by its key.
+ *
+ * @param inv - The investigation to search
+ * @param key - Container key (e.g., "ctr:email/headers")
+ * @returns The container or undefined if not found
+ */
+declare function getContainer(inv: CyvestInvestigation, key: string): Container | undefined;
+/**
+ * Get a container by its path.
+ *
+ * @param inv - The investigation to search
+ * @param path - Container path
+ * @returns The container or undefined if not found
+ */
+declare function getContainerByPath(inv: CyvestInvestigation, path: string): Container | undefined;
+/**
+ * Get all containers as a flat array (including sub-containers).
+ *
+ * @param inv - The investigation
+ * @returns Array of all containers
+ */
+declare function getAllContainers(inv: CyvestInvestigation): Container[];
+/**
+ * Get all observables as an array.
+ *
+ * @param inv - The investigation
+ * @returns Array of all observables
+ */
+declare function getAllObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Get all whitelists from the investigation.
+ *
+ * @param inv - The investigation
+ * @returns Array of all whitelists
+ */
+declare function getWhitelists(inv: CyvestInvestigation): Whitelist[];
+/**
+ * Get the investigation statistics.
+ *
+ * @param inv - The investigation
+ * @returns Statistics object
+ */
+declare function getStats(inv: CyvestInvestigation): Statistics;
+/**
+ * Get the investigation check statistics.
+ *
+ * @param inv - The investigation
+ * @returns Check statistics object
+ */
+declare function getStatsChecks(inv: CyvestInvestigation): StatsChecks;
+/**
+ * Get the data extraction configuration.
+ *
+ * @param inv - The investigation
+ * @returns Data extraction config
+ */
+declare function getDataExtraction(inv: CyvestInvestigation): DataExtraction;
+/**
+ * Count entities in the investigation.
+ */
+interface InvestigationCounts {
+    observables: number;
+    checks: number;
+    threatIntels: number;
+    enrichments: number;
+    containers: number;
+    whitelists: number;
+}
+/**
+ * Get counts of all entities in the investigation.
+ *
+ * @param inv - The investigation
+ * @returns Object with counts for each entity type
+ */
+declare function getCounts(inv: CyvestInvestigation): InvestigationCounts;
+
+/**
+ * Finder utilities for querying and filtering Cyvest Investigation data.
+ *
+ * These functions provide filtering, searching, and cross-referencing
+ * capabilities for observables, checks, and threat intel.
+ */
+
+/**
+ * Find all observables of a specific type.
+ *
+ * @param inv - The investigation to search
+ * @param type - Observable type (e.g., "ipv4-addr", "url", "domain-name")
+ * @returns Array of matching observables
+ *
+ * @example
+ * ```ts
+ * const ips = findObservablesByType(investigation, "ipv4-addr");
+ * const urls = findObservablesByType(investigation, "url");
+ * ```
+ */
+declare function findObservablesByType(inv: CyvestInvestigation, type: string): Observable[];
+/**
+ * Find all observables at a specific level.
+ *
+ * @param inv - The investigation to search
+ * @param level - Security level to filter by
+ * @returns Array of matching observables
+ *
+ * @example
+ * ```ts
+ * const malicious = findObservablesByLevel(investigation, "MALICIOUS");
+ * ```
+ */
+declare function findObservablesByLevel(inv: CyvestInvestigation, level: Level): Observable[];
+/**
+ * Find all observables at or above a minimum level.
+ *
+ * @param inv - The investigation to search
+ * @param minLevel - Minimum security level
+ * @returns Array of matching observables
+ *
+ * @example
+ * ```ts
+ * const suspicious = findObservablesAtLeast(investigation, "SUSPICIOUS");
+ * // Returns SUSPICIOUS and MALICIOUS observables
+ * ```
+ */
+declare function findObservablesAtLeast(inv: CyvestInvestigation, minLevel: Level): Observable[];
+/**
+ * Find observables by exact value match.
+ *
+ * @param inv - The investigation to search
+ * @param value - Value to search for
+ * @param caseSensitive - Whether to perform case-sensitive match (default: false)
+ * @returns Array of matching observables
+ */
+declare function findObservablesByValue(inv: CyvestInvestigation, value: string, caseSensitive?: boolean): Observable[];
+/**
+ * Find observables containing a substring in their value.
+ *
+ * @param inv - The investigation to search
+ * @param substring - Substring to search for
+ * @param caseSensitive - Whether to perform case-sensitive match (default: false)
+ * @returns Array of matching observables
+ */
+declare function findObservablesContaining(inv: CyvestInvestigation, substring: string, caseSensitive?: boolean): Observable[];
+/**
+ * Find observables matching a regular expression.
+ *
+ * @param inv - The investigation to search
+ * @param pattern - Regular expression pattern
+ * @returns Array of matching observables
+ */
+declare function findObservablesMatching(inv: CyvestInvestigation, pattern: RegExp): Observable[];
+/**
+ * Find internal observables.
+ *
+ * @param inv - The investigation to search
+ * @returns Array of internal observables
+ */
+declare function findInternalObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Find external (non-internal) observables.
+ *
+ * @param inv - The investigation to search
+ * @returns Array of external observables
+ */
+declare function findExternalObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Find whitelisted observables.
+ *
+ * @param inv - The investigation to search
+ * @returns Array of whitelisted observables
+ */
+declare function findWhitelistedObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Find observables with threat intelligence data.
+ *
+ * @param inv - The investigation to search
+ * @returns Array of observables that have associated threat intel
+ */
+declare function findObservablesWithThreatIntel(inv: CyvestInvestigation): Observable[];
+/**
+ * Find all checks in a specific scope.
+ *
+ * @param inv - The investigation to search
+ * @param scope - Check scope
+ * @returns Array of checks in the scope
+ *
+ * @example
+ * ```ts
+ * const emailChecks = findChecksByScope(investigation, "email_headers");
+ * ```
+ */
+declare function findChecksByScope(inv: CyvestInvestigation, scope: string): Check[];
+/**
+ * Find all checks at a specific level.
+ *
+ * @param inv - The investigation to search
+ * @param level - Security level to filter by
+ * @returns Array of matching checks
+ */
+declare function findChecksByLevel(inv: CyvestInvestigation, level: Level): Check[];
+/**
+ * Find all checks at or above a minimum level.
+ *
+ * @param inv - The investigation to search
+ * @param minLevel - Minimum security level
+ * @returns Array of matching checks
+ */
+declare function findChecksAtLeast(inv: CyvestInvestigation, minLevel: Level): Check[];
+/**
+ * Find checks by check ID (across all scopes).
+ *
+ * @param inv - The investigation to search
+ * @param checkId - Check identifier to search for
+ * @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.
+ *
+ * @param inv - The investigation to search
+ * @param source - Source name (e.g., "virustotal", "otx")
+ * @returns Array of threat intel from the source
+ */
+declare function findThreatIntelBySource(inv: CyvestInvestigation, source: string): ThreatIntel[];
+/**
+ * Find all threat intel at a specific level.
+ *
+ * @param inv - The investigation to search
+ * @param level - Security level to filter by
+ * @returns Array of matching threat intel
+ */
+declare function findThreatIntelByLevel(inv: CyvestInvestigation, level: Level): ThreatIntel[];
+/**
+ * Find all threat intel at or above a minimum level.
+ *
+ * @param inv - The investigation to search
+ * @param minLevel - Minimum security level
+ * @returns Array of matching threat intel
+ */
+declare function findThreatIntelAtLeast(inv: CyvestInvestigation, minLevel: Level): ThreatIntel[];
+/**
+ * Find containers at a specific aggregated level.
+ *
+ * @param inv - The investigation to search
+ * @param level - Aggregated level to filter by
+ * @returns Array of matching containers
+ */
+declare function findContainersByLevel(inv: CyvestInvestigation, level: Level): Container[];
+/**
+ * Find containers at or above a minimum aggregated level.
+ *
+ * @param inv - The investigation to search
+ * @param minLevel - Minimum aggregated level
+ * @returns Array of matching containers
+ */
+declare function findContainersAtLeast(inv: CyvestInvestigation, minLevel: Level): Container[];
+/**
+ * Get all checks that generated or reference a specific observable.
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the observable
+ * @returns Array of checks that reference this observable
+ *
+ * @example
+ * ```ts
+ * const checks = getChecksForObservable(investigation, "obs:ipv4-addr:192.168.1.1");
+ * ```
+ */
+declare function getChecksForObservable(inv: CyvestInvestigation, observableKey: string): Check[];
+/**
+ * Get all threat intel entries for a specific observable.
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the observable
+ * @returns Array of threat intel for this observable
+ */
+declare function getThreatIntelsForObservable(inv: CyvestInvestigation, observableKey: string): ThreatIntel[];
+/**
+ * Get all observables referenced by a specific check.
+ *
+ * @param inv - The investigation to search
+ * @param checkKey - Key of the check
+ * @returns Array of observables referenced by this check
+ */
+declare function getObservablesForCheck(inv: CyvestInvestigation, checkKey: string): Observable[];
+/**
+ * Get all checks for a specific container.
+ *
+ * @param inv - The investigation to search
+ * @param containerKey - Key of the container
+ * @param recursive - Include checks from sub-containers (default: false)
+ * @returns Array of checks in the container
+ */
+declare function getChecksForContainer(inv: CyvestInvestigation, containerKey: string, recursive?: boolean): Check[];
+/**
+ * Sort observables by score (descending - highest first).
+ *
+ * @param observables - Array of observables to sort
+ * @returns Sorted array (new array, doesn't mutate input)
+ */
+declare function sortObservablesByScore(observables: Observable[]): Observable[];
+/**
+ * Sort checks by score (descending - highest first).
+ *
+ * @param checks - Array of checks to sort
+ * @returns Sorted array (new array, doesn't mutate input)
+ */
+declare function sortChecksByScore(checks: Check[]): Check[];
+/**
+ * Sort observables by level (descending - most severe first).
+ *
+ * @param observables - Array of observables to sort
+ * @returns Sorted array (new array, doesn't mutate input)
+ */
+declare function sortObservablesByLevel(observables: Observable[]): Observable[];
+/**
+ * Sort checks by level (descending - most severe first).
+ *
+ * @param checks - Array of checks to sort
+ * @returns Sorted array (new array, doesn't mutate input)
+ */
+declare function sortChecksByLevel(checks: Check[]): Check[];
+/**
+ * Get the highest scoring observables.
+ *
+ * @param inv - The investigation to search
+ * @param n - Number of results to return (default: 10)
+ * @returns Array of highest scoring observables
+ */
+declare function getHighestScoringObservables(inv: CyvestInvestigation, n?: number): Observable[];
+/**
+ * Get the highest scoring checks.
+ *
+ * @param inv - The investigation to search
+ * @param n - Number of results to return (default: 10)
+ * @returns Array of highest scoring checks
+ */
+declare function getHighestScoringChecks(inv: CyvestInvestigation, n?: number): Check[];
+/**
+ * Get all malicious observables (convenience function).
+ *
+ * @param inv - The investigation to search
+ * @returns Array of malicious observables
+ */
+declare function getMaliciousObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Get all suspicious observables (convenience function).
+ *
+ * @param inv - The investigation to search
+ * @returns Array of suspicious observables
+ */
+declare function getSuspiciousObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Get all malicious checks (convenience function).
+ *
+ * @param inv - The investigation to search
+ * @returns Array of malicious checks
+ */
+declare function getMaliciousChecks(inv: CyvestInvestigation): Check[];
+/**
+ * Get all suspicious checks (convenience function).
+ *
+ * @param inv - The investigation to search
+ * @returns Array of suspicious checks
+ */
+declare function getSuspiciousChecks(inv: CyvestInvestigation): Check[];
+/**
+ * Get all scopes that have checks.
+ *
+ * @param inv - The investigation
+ * @returns Array of scope names
+ */
+declare function getAllScopes(inv: CyvestInvestigation): string[];
+/**
+ * Get all observable types present in the investigation.
+ *
+ * @param inv - The investigation
+ * @returns Array of unique observable types
+ */
+declare function getAllObservableTypes(inv: CyvestInvestigation): string[];
+/**
+ * Get all threat intel sources present in the investigation.
+ *
+ * @param inv - The investigation
+ * @returns Array of unique source names
+ */
+declare function getAllThreatIntelSources(inv: CyvestInvestigation): string[];
+
+/**
+ * Graph and relationship traversal utilities for Cyvest Investigation.
+ *
+ * These functions provide graph-like traversal of observable relationships,
+ * useful for understanding connections and preparing data for visualization.
+ */
+
+/**
+ * Edge representation for graph operations.
+ */
+interface GraphEdge {
+    /** Source observable key */
+    source: string;
+    /** Target observable key */
+    target: string;
+    /** Relationship type label */
+    type: string;
+    /** Relationship direction */
+    direction: RelationshipDirection;
+}
+/**
+ * Graph node representation.
+ */
+interface GraphNode {
+    /** Observable key (unique identifier) */
+    id: string;
+    /** Observable type */
+    type: string;
+    /** Observable value */
+    value: string;
+    /** Security level */
+    level: Level;
+    /** Numeric score */
+    score: number;
+    /** Whether internal */
+    internal: boolean;
+    /** Whether whitelisted */
+    whitelisted: boolean;
+}
+/**
+ * Full graph representation of an investigation.
+ */
+interface InvestigationGraph {
+    /** All nodes (observables) */
+    nodes: GraphNode[];
+    /** All edges (relationships) */
+    edges: GraphEdge[];
+}
+/**
+ * Get all related observables for a given observable.
+ *
+ * Returns observables that are directly connected via any relationship,
+ * regardless of direction.
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the source observable
+ * @returns Array of related observables
+ *
+ * @example
+ * ```ts
+ * const related = getRelatedObservables(investigation, "obs:email-addr:test@example.com");
+ * ```
+ */
+declare function getRelatedObservables(inv: CyvestInvestigation, observableKey: string): Observable[];
+/**
+ * Get observables related by outbound relationships (children).
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the source observable
+ * @returns Array of child observables
+ */
+declare function getObservableChildren(inv: CyvestInvestigation, observableKey: string): Observable[];
+/**
+ * Get observables related by inbound relationships (parents).
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the target observable
+ * @returns Array of parent observables
+ */
+declare function getObservableParents(inv: CyvestInvestigation, observableKey: string): Observable[];
+/**
+ * Get related observables filtered by relationship type.
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the source observable
+ * @param relationshipType - Type of relationship to filter (e.g., "related-to", "uses")
+ * @returns Array of related observables
+ */
+declare function getRelatedObservablesByType(inv: CyvestInvestigation, observableKey: string, relationshipType: string): Observable[];
+/**
+ * Get related observables filtered by direction.
+ *
+ * @param inv - The investigation to search
+ * @param observableKey - Key of the source observable
+ * @param direction - Direction to filter by
+ * @returns Array of related observables
+ */
+declare function getRelatedObservablesByDirection(inv: CyvestInvestigation, observableKey: string, direction: RelationshipDirection): Observable[];
+/**
+ * Build a graph representation of all observables and their relationships.
+ *
+ * Useful for visualization libraries like vis.js, d3, or cytoscape.
+ *
+ * @param inv - The investigation
+ * @returns Graph with nodes and edges
+ *
+ * @example
+ * ```ts
+ * const graph = getObservableGraph(investigation);
+ * console.log(`Nodes: ${graph.nodes.length}, Edges: ${graph.edges.length}`);
+ *
+ * // Use with vis.js:
+ * const network = new vis.Network(container, {
+ *   nodes: graph.nodes.map(n => ({ id: n.id, label: n.value })),
+ *   edges: graph.edges.map(e => ({ from: e.source, to: e.target, label: e.type }))
+ * });
+ * ```
+ */
+declare function getObservableGraph(inv: CyvestInvestigation): InvestigationGraph;
+/**
+ * Find the root observable(s) of the investigation.
+ *
+ * Root observables are those that have no incoming relationships
+ * (nothing points to them as a target).
+ *
+ * @param inv - The investigation
+ * @returns Array of root observables
+ */
+declare function findRootObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Find orphan observables (not connected to any other observable).
+ *
+ * @param inv - The investigation
+ * @returns Array of orphan observables
+ */
+declare function findOrphanObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Find leaf observables (have incoming but no outgoing relationships).
+ *
+ * @param inv - The investigation
+ * @returns Array of leaf observables
+ */
+declare function findLeafObservables(inv: CyvestInvestigation): Observable[];
+/**
+ * Check if two observables are connected (directly or transitively).
+ *
+ * @param inv - The investigation
+ * @param sourceKey - Starting observable key
+ * @param targetKey - Target observable key
+ * @returns True if a path exists from source to target
+ */
+declare function areConnected(inv: CyvestInvestigation, sourceKey: string, targetKey: string): boolean;
+/**
+ * Find the shortest path between two observables.
+ *
+ * @param inv - The investigation
+ * @param sourceKey - Starting observable key
+ * @param targetKey - Target observable key
+ * @returns Array of observable keys representing the path, or null if no path exists
+ */
+declare function findPath(inv: CyvestInvestigation, sourceKey: string, targetKey: string): string[] | null;
+/**
+ * Get all observables reachable from a starting point.
+ *
+ * @param inv - The investigation
+ * @param startKey - Starting observable key
+ * @param maxDepth - Maximum traversal depth (default: Infinity)
+ * @returns Array of reachable observables
+ */
+declare function getReachableObservables(inv: CyvestInvestigation, startKey: string, maxDepth?: number): Observable[];
+/**
+ * Get all unique relationship types used in the investigation.
+ *
+ * @param inv - The investigation
+ * @returns Array of unique relationship type strings
+ */
+declare function getAllRelationshipTypes(inv: CyvestInvestigation): string[];
+/**
+ * Count relationships by type.
+ *
+ * @param inv - The investigation
+ * @returns Object mapping relationship type to count
+ */
+declare function countRelationshipsByType(inv: CyvestInvestigation): Record<string, number>;
+/**
+ * Get all relationships for an observable.
+ *
+ * @param inv - The investigation
+ * @param observableKey - Observable key
+ * @returns Object with outbound, inbound, and all relationships
+ */
+declare function getRelationshipsForObservable(inv: CyvestInvestigation, observableKey: string): {
+    outbound: Relationship[];
+    inbound: Array<Relationship & {
+        source_key: string;
+    }>;
+    all: Array<Relationship & {
+        source_key?: string;
+    }>;
+};
+
+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 };