@cyvest/cyvest-js 2.0.1

package/src/keys.ts

@@ -0,0 +1,286 @@
+/**
+ * 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.
+ */
+export type KeyType = "obs" | "chk" | "ti" | "enr" | "ctr";
+
+/**
+ * Normalize a string value for consistent key generation.
+ */
+function normalizeValue(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+/**
+ * Create a deterministic hash from a string using a simple hash algorithm.
+ * Uses a subset of characters for shorter keys.
+ */
+function hashString(content: string, length: number = 16): string {
+  // Simple hash implementation (similar to Java's hashCode)
+  // For production, consider using crypto.subtle or a library
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = ((hash << 5) - hash + char) | 0;
+  }
+  // Convert to hex and pad/truncate
+  const hex = Math.abs(hash).toString(16).padStart(8, "0");
+  return hex.slice(0, length);
+}
+
+/**
+ * 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"
+ * ```
+ */
+export function generateObservableKey(obsType: string, value: string): string {
+  const normalizedType = normalizeValue(obsType);
+  const normalizedValue = normalizeValue(value);
+  return `obs:${normalizedType}:${normalizedValue}`;
+}
+
+/**
+ * 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"
+ * ```
+ */
+export function generateCheckKey(checkId: string, scope: string): string {
+  const normalizedId = normalizeValue(checkId);
+  const normalizedScope = normalizeValue(scope);
+  return `chk:${normalizedId}:${normalizedScope}`;
+}
+
+/**
+ * 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"
+ * ```
+ */
+export function generateThreatIntelKey(
+  source: string,
+  observableKey: string
+): string {
+  const normalizedSource = normalizeValue(source);
+  return `ti:${normalizedSource}:${observableKey}`;
+}
+
+/**
+ * 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"
+ * ```
+ */
+export function generateEnrichmentKey(name: string, context?: string): string {
+  const normalizedName = normalizeValue(name);
+  if (context) {
+    const contextHash = hashString(context, 8);
+    return `enr:${normalizedName}:${contextHash}`;
+  }
+  return `enr:${normalizedName}`;
+}
+
+/**
+ * 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"
+ * ```
+ */
+export function generateContainerKey(path: string): string {
+  // Normalize path separators
+  let normalizedPath = path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  normalizedPath = normalizeValue(normalizedPath);
+  return `ctr:${normalizedPath}`;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function parseKeyType(key: string): KeyType | null {
+  if (key.includes(":")) {
+    const prefix = key.split(":", 1)[0] as KeyType;
+    if (["obs", "chk", "ti", "enr", "ctr"].includes(prefix)) {
+      return prefix;
+    }
+  }
+  return 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
+ * ```
+ */
+export function validateKey(key: string, expectedType?: KeyType): boolean {
+  if (!key || !key.includes(":")) {
+    return false;
+  }
+
+  const keyType = parseKeyType(key);
+  if (!keyType) {
+    return false;
+  }
+
+  if (expectedType && keyType !== expectedType) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * 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" }
+ * ```
+ */
+export function parseObservableKey(
+  key: string
+): { type: string; value: string } | null {
+  if (!validateKey(key, "obs")) {
+    return null;
+  }
+  const parts = key.split(":");
+  if (parts.length >= 3) {
+    return {
+      type: parts[1],
+      value: parts.slice(2).join(":"), // Handle values with colons
+    };
+  }
+  return 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" }
+ * ```
+ */
+export function parseCheckKey(
+  key: string
+): { checkId: string; scope: string } | null {
+  if (!validateKey(key, "chk")) {
+    return null;
+  }
+  const parts = key.split(":");
+  if (parts.length >= 3) {
+    return {
+      checkId: parts[1],
+      scope: parts.slice(2).join(":"),
+    };
+  }
+  return 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" }
+ * ```
+ */
+export function parseThreatIntelKey(
+  key: string
+): { source: string; observableKey: string } | null {
+  if (!validateKey(key, "ti")) {
+    return null;
+  }
+  const parts = key.split(":");
+  if (parts.length >= 3) {
+    return {
+      source: parts[1],
+      observableKey: parts.slice(2).join(":"),
+    };
+  }
+  return null;
+}

package/src/levels.ts

@@ -0,0 +1,262 @@
+/**
+ * Level enumeration and scoring logic for Cyvest.
+ *
+ * This module defines the security level classification system and the algorithm
+ * for determining levels from scores.
+ */
+
+import type { Observable, Check, ThreatIntel, Container, Level } from "./types.generated";
+
+// Re-export Level type from types.generated for convenience
+export type { Level } from "./types.generated";
+
+/**
+ * Ordered array of levels from lowest to highest severity.
+ */
+export const LEVEL_ORDER: readonly Level[] = [
+  "NONE",
+  "TRUSTED",
+  "INFO",
+  "SAFE",
+  "NOTABLE",
+  "SUSPICIOUS",
+  "MALICIOUS",
+] as const;
+
+/**
+ * Numeric values for each level (for comparison purposes).
+ */
+export const LEVEL_VALUES: Record<Level, number> = {
+  NONE: 0,
+  TRUSTED: 1,
+  INFO: 2,
+  SAFE: 3,
+  NOTABLE: 4,
+  SUSPICIOUS: 5,
+  MALICIOUS: 6,
+};
+
+/**
+ * Color mapping for display purposes.
+ */
+export const LEVEL_COLORS: Record<Level, string> = {
+  NONE: "#808080", // gray
+  TRUSTED: "#22c55e", // green
+  INFO: "#06b6d4", // cyan
+  SAFE: "#4ade80", // bright green
+  NOTABLE: "#eab308", // yellow
+  SUSPICIOUS: "#f97316", // orange
+  MALICIOUS: "#ef4444", // red
+};
+
+/**
+ * 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"
+ * ```
+ */
+export function normalizeLevel(level: string): Level {
+  const upper = level.toUpperCase();
+  if (LEVEL_ORDER.includes(upper as Level)) {
+    return upper as Level;
+  }
+  throw new Error(`Invalid level name: ${level}`);
+}
+
+/**
+ * Check if a string is a valid Level.
+ *
+ * @param level - String to check
+ * @returns True if valid Level
+ */
+export function isValidLevel(level: string): level is Level {
+  return LEVEL_ORDER.includes(level.toUpperCase() as 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"
+ * ```
+ */
+export function getLevelFromScore(score: number): Level {
+  if (score < 0) {
+    return "TRUSTED";
+  }
+  if (score === 0) {
+    return "INFO";
+  }
+  if (score < 3) {
+    return "NOTABLE";
+  }
+  if (score < 5) {
+    return "SUSPICIOUS";
+  }
+  return "MALICIOUS";
+}
+
+/**
+ * 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
+ * ```
+ */
+export function compareLevels(a: Level, b: Level): -1 | 0 | 1 {
+  const valueA = LEVEL_VALUES[a];
+  const valueB = LEVEL_VALUES[b];
+  if (valueA < valueB) return -1;
+  if (valueA > valueB) return 1;
+  return 0;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isLevelHigherThan(a: Level, b: Level): boolean {
+  return LEVEL_VALUES[a] > LEVEL_VALUES[b];
+}
+
+/**
+ * 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
+ */
+export function isLevelLowerThan(a: Level, b: Level): boolean {
+  return LEVEL_VALUES[a] < LEVEL_VALUES[b];
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isLevelAtLeast(a: Level, minLevel: Level): boolean {
+  return LEVEL_VALUES[a] >= LEVEL_VALUES[minLevel];
+}
+
+/**
+ * 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
+ */
+export function maxLevel(levels: Level[]): Level {
+  if (levels.length === 0) return "NONE";
+  return levels.reduce((max, level) =>
+    isLevelHigherThan(level, max) ? level : max
+  );
+}
+
+/**
+ * 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
+ */
+export function minLevel(levels: Level[]): Level {
+  if (levels.length === 0) return "MALICIOUS";
+  return levels.reduce((min, level) =>
+    isLevelLowerThan(level, min) ? level : min
+  );
+}
+
+/**
+ * Get the color associated with a level for display purposes.
+ *
+ * @param level - Level to get color for
+ * @returns Hex color string
+ */
+export function getColorForLevel(level: Level): string {
+  return LEVEL_COLORS[level];
+}
+
+/**
+ * Get the color associated with a score for display purposes.
+ *
+ * @param score - Score to get color for
+ * @returns Hex color string
+ */
+export function getColorForScore(score: number): string {
+  return getColorForLevel(getLevelFromScore(score));
+}
+
+/**
+ * Type guard to check if an object has a level property.
+ */
+export function hasLevel(
+  obj: unknown
+): obj is { level: Level } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "level" in obj &&
+    typeof (obj as { level: unknown }).level === "string" &&
+    isValidLevel((obj as { level: string }).level)
+  );
+}
+
+/**
+ * Extract level from an entity (Observable, Check, ThreatIntel, Container).
+ */
+export function getEntityLevel(
+  entity: Observable | Check | ThreatIntel | Container
+): Level {
+  if ("aggregated_level" in entity) {
+    return entity.aggregated_level;
+  }
+  return entity.level;
+}

package/src/types.generated.ts

@@ -0,0 +1,176 @@
+// AUTO-GENERATED FROM cyvest.schema.json — DO NOT EDIT
+
+/**
+ * Security level classification from NONE (lowest) to MALICIOUS (highest).
+ */
+export type Level =
+  | "NONE"
+  | "TRUSTED"
+  | "INFO"
+  | "SAFE"
+  | "NOTABLE"
+  | "SUSPICIOUS"
+  | "MALICIOUS";
+/**
+ * Direction of a relationship between observables.
+ */
+export type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
+/**
+ * Score computation policy: 'auto' calculates from level, 'manual' uses explicit score.
+ */
+export type ScorePolicy = "auto" | "manual";
+/**
+ * Score aggregation mode: 'max' takes highest score, 'sum' adds all scores.
+ */
+export type ScoreMode = "max" | "sum";
+
+export 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;
+}
+export interface Whitelist {
+  identifier: string;
+  name: string;
+  justification?: string | null;
+}
+export 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[];
+}
+export interface Relationship {
+  target_key: string;
+  /**
+   * Relationship label; defaults to related-to.
+   */
+  relationship_type: string;
+  direction: RelationshipDirection;
+}
+export 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[];
+}
+export interface ThreatIntel {
+  key: string;
+  source: string;
+  observable_key: string;
+  comment: string;
+  extra: {
+    [k: string]: unknown;
+  } | null;
+  score: number;
+  level: Level;
+  taxonomies: {
+    [k: string]: unknown;
+  }[];
+}
+export interface Enrichment {
+  key: string;
+  name: string;
+  data: {
+    [k: string]: unknown;
+  };
+  context: string;
+}
+export interface Container {
+  key: string;
+  path: string;
+  description: string;
+  checks: string[];
+  sub_containers: {
+    [k: string]: Container;
+  };
+  aggregated_score: number;
+  aggregated_level: Level;
+}
+export 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;
+}
+export interface StatsChecks {
+  checks: number;
+  applied: number;
+}
+export interface DataExtraction {
+  /**
+   * Root observable type used during data extraction.
+   */
+  root_type: string | null;
+  score_mode: ScoreMode;
+}