@nano-rs/dac-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,672 @@
+/**
+ * Detection schema types for NanoSIEM
+ * These types match the NanoSIEM API schema defined in nanosiem-web/src/lib/api/types.ts
+ */
+/** Severity levels for detection rules */
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'informational';
+/** Rule lifecycle mode */
+type RuleMode = 'staging' | 'live' | 'alerting' | 'paused';
+/** Detection execution mode */
+type DetectionMode = 'real-time' | 'scheduled';
+/** Alert mode for how matched events map to alerts */
+type AlertMode = 'grouped' | 'per_event';
+/**
+ * AI triage hints help analysts identify false positives vs true positives
+ * These hints are used by the AI triage system and displayed to analysts
+ */
+interface AiTriageHints {
+    /** Conditions indicating benign/expected activity (false positive indicators) */
+    ignore_when: string[];
+    /** Conditions indicating especially suspicious activity (true positive indicators) */
+    suspicious_when: string[];
+    /** Additional context about this detection for the AI and analysts */
+    context?: string;
+}
+/** Case visibility levels for cases created by this rule */
+type CaseVisibility = 'public' | 'group' | 'private';
+/** Auto-tuning mode for detection rules */
+type AutoTuningMode = 'off' | 'proposals' | 'auto_approve';
+/**
+ * Auto-tuning configuration for detection rules
+ * Controls how AI-driven tuning behaves for this rule
+ */
+interface AutoTuningConfig {
+    /** Whether auto-tuning is enabled for this rule (default: true) */
+    enabled?: boolean;
+    /** Minimum AI confidence score required to consider a tuning proposal (0.0-1.0, default: 0.8) */
+    min_confidence?: number;
+    /** If true, prevents auto-tuning regardless of other settings (for critical rules) */
+    critical?: boolean;
+    /** How tuning proposals are handled: 'off', 'proposals' (require approval), or 'auto_approve' */
+    mode?: AutoTuningMode;
+}
+/**
+ * UDM field requirements for a detection rule
+ * Used for coverage analysis and validation
+ */
+interface RequiresConfig {
+    /** UDM fields required for this detection to work */
+    fields: string[];
+    /** Suggested source types that typically provide these fields */
+    source_types?: string[];
+}
+/**
+ * Repository metadata for imported rules
+ * Set automatically during import, not user-authored
+ */
+interface RepositoryMetadata {
+    /** Repository slug (e.g., "sigma-hq/sigma") */
+    source: string;
+    /** Rule path within the repository */
+    rule_id: string;
+    /** Commit SHA when imported/last synced */
+    commit: string;
+    /** Whether this rule stays in sync with upstream changes */
+    linked: boolean;
+}
+/**
+ * YAML frontmatter schema for detection files
+ * This is the format users write in their .yaml detection files
+ */
+interface DetectionFrontmatter {
+    /** Detection name/title (required) */
+    title: string;
+    /** Description of what the detection finds */
+    description?: string;
+    /** Author name or email */
+    author?: string;
+    /** Severity level */
+    severity: Severity;
+    /** Rule lifecycle mode */
+    mode: RuleMode;
+    /** Detection execution mode */
+    detection_mode: DetectionMode;
+    /** Cron schedule for scheduled detections (e.g., every minute: "* 1 * * * *") */
+    schedule?: string;
+    /** Lookback period (e.g., "15m", "1h", "24h") */
+    lookback?: string;
+    /** MITRE ATT&CK tactics (single or array, e.g., "TA0011" or ["TA0011", "TA0001"]) */
+    mitre_tactics?: string | string[];
+    /** MITRE ATT&CK techniques (single or array, e.g., "T1071" or ["T1071", "T1059.001"]) */
+    mitre_techniques?: string | string[];
+    /** Tags for categorization */
+    tags?: string[];
+    /** Reference URL for more information about the threat */
+    reference_url?: string;
+    /** Whether real-time detection is enabled (for real-time mode) */
+    realtime_enabled?: boolean;
+    /** AI triage hints for false positive identification */
+    ai_triage_hints?: AiTriageHints;
+    /** Case visibility for cases created by this rule */
+    case_visibility?: CaseVisibility;
+    /** Group slugs for case permissions (when visibility = 'group') */
+    case_groups?: string[];
+    /** Alert mode: grouped (all matches → 1 alert) or per_event (each match → 1 alert) */
+    alert_mode?: AlertMode;
+    /** Organizational folder (e.g., "identity", "endpoint", "network", "cloud") */
+    folder?: string;
+    /** Auto-tuning configuration */
+    auto_tuning?: AutoTuningConfig;
+    /** UDM field requirements */
+    requires?: RequiresConfig;
+    /**
+     * Playbook auto-attach mode for alerts produced by this rule.
+     *   'none'     — no playbook (default)
+     *   'specific' — attach `playbook_id` at case-creation time
+     *   'adaptive' — let the Shadow Investigator compose on investigation wrap
+     *
+     * Prefer the `playbook:` shorthand below for new rules — this two-field
+     * form is kept so older rules keep parsing.
+     */
+    playbook_selector_mode?: 'none' | 'specific' | 'adaptive';
+    /** Library playbook id (typeid `pb_...`) — required when `playbook_selector_mode` is 'specific' */
+    playbook_id?: string;
+    /**
+     * Shorthand for `playbook_selector_mode` + `playbook_id`. When set, wins
+     * over the two-field form above. Encoded as:
+     *   omitted / "" / "none"  — mode='none'
+     *   "adaptive"             — Shadow Investigator composes on wrap
+     *   "pb_<typeid>"          — attach that specific library playbook
+     */
+    playbook?: string;
+    /** Repository metadata (set by import, not user-authored) */
+    _repository?: RepositoryMetadata;
+}
+/**
+ * Complete parsed detection file
+ * Combines the frontmatter metadata with the query body
+ */
+interface Detection {
+    /** File path relative to detections directory */
+    filePath: string;
+    /** Parsed frontmatter metadata */
+    metadata: DetectionFrontmatter;
+    /** Query body (SPL-like query after frontmatter) */
+    query: string;
+    /** Raw file content (for diffing) */
+    raw: string;
+}
+/**
+ * Detection payload ready to send to NanoSIEM API
+ * Normalized version of Detection for API compatibility
+ */
+interface DetectionApiPayload {
+    /** Detection name (from title) */
+    name: string;
+    /** Description */
+    description?: string;
+    /** SPL-like query */
+    query: string;
+    /** Severity level */
+    severity: Severity;
+    /** Rule lifecycle mode */
+    mode: RuleMode;
+    /** Detection execution mode */
+    detection_mode: DetectionMode;
+    /** Cron schedule expression */
+    schedule_cron?: string;
+    /** Lookback period in minutes */
+    lookback_minutes?: number;
+    /** MITRE ATT&CK tactics (normalized to array) */
+    mitre_tactics: string[];
+    /** MITRE ATT&CK techniques (normalized to array) */
+    mitre_techniques: string[];
+    /** Tags */
+    tags: string[];
+    /** Reference URL */
+    reference_url?: string;
+    /** Author */
+    author?: string;
+    /** Real-time enabled */
+    realtime_enabled?: boolean;
+    /** AI triage hints */
+    ai_triage_hints?: AiTriageHints;
+    /** Case visibility for cases created by this rule */
+    case_visibility?: CaseVisibility;
+    /** Group IDs for case permissions (UUIDs, when case_visibility = 'group') */
+    case_group_ids?: string[];
+    /** Alert mode: grouped (all matches → 1 alert) or per_event (each match → 1 alert) */
+    alert_mode?: AlertMode;
+    /** Organizational folder (e.g., "identity", "endpoint", "network", "cloud") */
+    folder?: string;
+    /** Whether auto-tuning is enabled for this rule */
+    auto_tuning_enabled?: boolean;
+    /** Minimum AI confidence score for tuning proposals (0.0-1.0) */
+    auto_tuning_min_confidence?: number;
+    /** If true, prevents auto-tuning regardless of other settings */
+    auto_tuning_critical?: boolean;
+    /** UDM field requirements (local-only, not sent to API) */
+    requires?: RequiresConfig;
+    /** Repository source (for linked/forked rules) */
+    source_repository_slug?: string;
+    /** Rule path in source repository */
+    source_rule_path?: string;
+    /** Whether the rule is linked to upstream */
+    source_linked?: boolean;
+    /** Playbook auto-attach mode: 'none' | 'specific' | 'adaptive' */
+    playbook_selector_mode?: 'none' | 'specific' | 'adaptive';
+    /** Library playbook id when selector mode is 'specific' */
+    playbook_id?: string | null;
+}
+/**
+ * Detection rule returned from NanoSIEM API
+ * Includes server-generated fields like id, created_at, etc.
+ */
+interface DetectionRule extends DetectionApiPayload {
+    /** Unique rule ID (UUID) */
+    id: string;
+    /** Materialized view name (for real-time detections) */
+    materialized_view_name?: string;
+    /** AI-generated narrative explaining the detection */
+    narrative?: string;
+    /** Whether this rule was AI-generated */
+    ai_generated?: boolean;
+    /** Whether this rule is archived */
+    archived?: boolean;
+    /** Timestamp when rule was created */
+    created_at: string;
+    /** Timestamp when rule was last updated */
+    updated_at: string;
+    /** Timestamp when rule last ran */
+    last_run_at?: string;
+    /** Timestamp when rule last matched */
+    last_match_at?: string;
+    /** Total match count */
+    match_count: number;
+    /** Match count during live/bake-in mode */
+    live_match_count?: number;
+}
+/**
+ * Response from create/update operations that may include warnings
+ */
+interface DetectionResponse extends DetectionRule {
+    /** Warning message from backend (e.g., auto-correction from real-time to scheduled) */
+    warning?: string;
+}
+/**
+ * Daily match count for trend analysis
+ */
+interface DailyMatchCount {
+    date: string;
+    count: number;
+}
+/**
+ * Historical analysis result from testing a detection
+ */
+interface HistoricalAnalysisResult {
+    /** Rule ID (if testing existing rule) */
+    rule_id?: string;
+    /** Rule name */
+    rule_name?: string;
+    /** Time range analyzed */
+    time_range?: {
+        start: string;
+        end: string;
+    };
+    /** Total matches found */
+    total_matches: number;
+    /** Sample events from matches */
+    sample_events: Record<string, unknown>[];
+    /** Matches grouped by day */
+    matches_by_day?: DailyMatchCount[];
+    /** Execution time in milliseconds */
+    execution_time_ms?: number;
+}
+/**
+ * Search result from executing a query
+ */
+interface SearchResult {
+    /** Matching records */
+    results: Record<string, unknown>[];
+    /** Total count of matches */
+    total_count: number;
+    /** Query execution time in milliseconds */
+    execution_time_ms: number;
+    /** Generated SQL (if requested) */
+    generated_sql?: string;
+}
+/**
+ * Response from server-side query validation
+ */
+interface ValidateDetectionResponse {
+    /** Whether the query is valid */
+    valid: boolean;
+    /** The effective detection mode after auto-correction */
+    effective_mode: string;
+    /** Whether a materialized view will be created */
+    creates_materialized_view: boolean;
+    /** Explanation of mode selection */
+    mode_reason: string;
+    /** Warning about auto-correction */
+    warning?: string;
+    /** Validation errors */
+    errors: string[];
+    /** Fields referenced in the query */
+    referenced_fields: string[];
+}
+/**
+ * Response from query formatting
+ */
+interface FormatQueryResponse {
+    formatted_query: string;
+}
+/**
+ * Detection match record from /rules/{id}/matches
+ */
+interface DetectionMatch {
+    id: string;
+    detected_at: string;
+    severity: string;
+    status: string;
+    event_count: number;
+    events: Record<string, unknown>[];
+}
+/**
+ * Paginated detection matches response
+ */
+interface DetectionMatchesResponse {
+    total: number;
+    matches: DetectionMatch[];
+}
+/**
+ * Bulk update rules request
+ */
+interface BulkUpdateRulesRequest {
+    rule_ids: string[];
+    mode: string;
+}
+/**
+ * Bulk update rules response
+ */
+interface BulkUpdateRulesResponse {
+    updated: number;
+    skipped: number;
+    failed: Array<{
+        rule_id: string;
+        error: string;
+    }>;
+}
+/**
+ * Import rules response
+ */
+interface ImportRulesResponse {
+    imported: number;
+    failed: number;
+    errors: string[];
+}
+/**
+ * Grouped test result bucket for alert_mode=grouped
+ * Matches the in-product rule tester's bucketing behavior
+ */
+interface GroupedTestBucket {
+    /** Window start time (ISO 8601) */
+    window_start: string;
+    /** Window end time (ISO 8601) */
+    window_end: string;
+    /** Number of events in this bucket */
+    event_count: number;
+    /** Most frequent entity in this bucket */
+    dominant_entity: {
+        field: string;
+        value: string;
+        others_count: number;
+    } | null;
+    /** Sample events from this bucket */
+    sample_events: Record<string, unknown>[];
+}
+
+/**
+ * YAML frontmatter parser for detection files
+ *
+ * Parses detection files in the format:
+ * ---
+ * title: detection_name
+ * severity: medium
+ * ...
+ * ---
+ * source_type=logs | where status=500
+ */
+
+/** Parse error types */
+type ParseErrorType = 'frontmatter_missing' | 'frontmatter_malformed' | 'yaml_invalid' | 'query_missing';
+/** Parse error with location information */
+interface ParseError {
+    /** Error type */
+    type: ParseErrorType;
+    /** Human-readable error message */
+    message: string;
+    /** Line number where error occurred (1-indexed) */
+    line?: number;
+    /** Column number where error occurred (1-indexed) */
+    column?: number;
+}
+/** Result of parsing a detection file */
+interface ParseResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Parsed detection (if successful) */
+    detection?: Detection;
+    /** Parse errors (if any) */
+    errors: ParseError[];
+}
+/**
+ * Parse a single detection file
+ *
+ * @param content - Raw file content
+ * @param filePath - Path to the file (for error reporting and Detection.filePath)
+ * @returns Parse result with detection or errors
+ */
+declare function parseDetectionFile(content: string, filePath: string): ParseResult;
+/**
+ * Parse multiple detection files
+ *
+ * @param files - Array of file paths and contents
+ * @returns Map of file path to parse result
+ */
+declare function parseMultipleFiles(files: Array<{
+    path: string;
+    content: string;
+}>): Map<string, ParseResult>;
+/**
+ * Serialize a detection back to file format
+ *
+ * @param detection - Detection to serialize
+ * @returns File content as string
+ */
+declare function serializeDetection(detection: Detection): string;
+
+/**
+ * Detection validation logic
+ *
+ * Validates detection metadata and query against schema requirements
+ */
+
+/** Validation error */
+interface ValidationError {
+    /** Field that failed validation */
+    field: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: string;
+}
+/** Validation warning (non-fatal issue) */
+interface ValidationWarning {
+    /** Field with warning */
+    field: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: string;
+}
+/** Result of validating a detection */
+interface ValidationResult {
+    /** Whether the detection is valid (no errors) */
+    valid: boolean;
+    /** Validation errors (fatal issues) */
+    errors: ValidationError[];
+    /** Validation warnings (non-fatal issues) */
+    warnings: ValidationWarning[];
+}
+/**
+ * Validate a parsed detection
+ *
+ * @param detection - Parsed detection to validate
+ * @returns Validation result with errors and warnings
+ */
+declare function validateDetection(detection: Detection): ValidationResult;
+/**
+ * Parse and convert lookback string to minutes
+ *
+ * @param lookback - Lookback string (e.g., "15m", "1h", "7d")
+ * @returns Number of minutes, or undefined if invalid
+ */
+declare function parseLookbackToMinutes(lookback: string): number | undefined;
+
+/**
+ * NanoSIEM API client
+ *
+ * Handles communication with the NanoSIEM detection and search APIs
+ */
+
+/** Client configuration */
+interface NanosiemClientConfig {
+    /** NanoSIEM API base URL (e.g., "https://nanosiem.example.com:3001") */
+    apiUrl: string;
+    /** Search service URL (e.g., "https://nanosiem.example.com:3002") */
+    searchUrl?: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/** API response wrapper */
+interface ApiResponse<T> {
+    /** Whether the request succeeded */
+    success: boolean;
+    /** Response data (if successful) */
+    data?: T;
+    /** Error information (if failed) */
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * NanoSIEM API client
+ */
+declare class NanosiemClient {
+    private apiUrl;
+    private searchUrl;
+    private apiKey;
+    private timeout;
+    constructor(config: NanosiemClientConfig);
+    /**
+     * Make an API request
+     */
+    private request;
+    /**
+     * List all detection rules
+     */
+    listDetections(): Promise<ApiResponse<DetectionRule[]>>;
+    /**
+     * Get a single detection rule by ID
+     */
+    getDetection(id: string): Promise<ApiResponse<DetectionRule>>;
+    /**
+     * Create a new detection rule
+     */
+    createDetection(payload: DetectionApiPayload): Promise<ApiResponse<DetectionResponse>>;
+    /**
+     * Update an existing detection rule
+     */
+    updateDetection(id: string, payload: Partial<DetectionApiPayload>): Promise<ApiResponse<DetectionResponse>>;
+    /**
+     * Delete a detection rule
+     */
+    deleteDetection(id: string): Promise<ApiResponse<{
+        deleted: boolean;
+    }>>;
+    /**
+     * Pause a detection rule (set mode to paused)
+     */
+    pauseDetection(id: string): Promise<ApiResponse<DetectionRule>>;
+    /**
+     * Resume a paused detection rule (set mode back to alerting)
+     */
+    resumeDetection(id: string): Promise<ApiResponse<DetectionRule>>;
+    /**
+     * Test a detection rule against historical data
+     */
+    testDetection(id: string, days?: number): Promise<ApiResponse<HistoricalAnalysisResult>>;
+    /**
+     * Test a query without creating a detection
+     */
+    testQuery(query: string, days?: number): Promise<ApiResponse<HistoricalAnalysisResult>>;
+    /**
+     * Execute a search query
+     */
+    search(query: string, timeRange: {
+        start: string;
+        end: string;
+    }, options?: {
+        limit?: number;
+        includeSQL?: boolean;
+    }): Promise<ApiResponse<SearchResult>>;
+    /**
+     * Check API health
+     */
+    healthCheck(): Promise<ApiResponse<{
+        status: string;
+        version?: string;
+    }>>;
+    /**
+     * Promote a rule (staging -> live -> alerting)
+     */
+    promoteDetection(id: string): Promise<ApiResponse<DetectionRule>>;
+    /**
+     * Demote a rule (alerting -> live)
+     */
+    demoteDetection(id: string): Promise<ApiResponse<DetectionRule>>;
+    /**
+     * Manually trigger a rule to execute now
+     */
+    triggerDetection(id: string): Promise<ApiResponse<{
+        triggered: boolean;
+        rule_id: string;
+    }>>;
+    /**
+     * Validate a query using server-side validation
+     */
+    validateQuery(query: string, detectionMode?: string): Promise<ApiResponse<ValidateDetectionResponse>>;
+    /**
+     * Format a query with pretty-printing
+     */
+    formatQuery(query: string): Promise<ApiResponse<FormatQueryResponse>>;
+    /**
+     * Get detection matches for a rule
+     */
+    getMatches(id: string, params?: {
+        limit?: number;
+        offset?: number;
+        start_time?: string;
+        end_time?: string;
+    }): Promise<ApiResponse<DetectionMatchesResponse>>;
+    /**
+     * Get detection stats (match counts by day)
+     */
+    getStats(days?: number): Promise<ApiResponse<Record<string, unknown>>>;
+    /**
+     * Bulk update rule modes
+     */
+    bulkUpdate(ruleIds: string[], mode: string): Promise<ApiResponse<BulkUpdateRulesResponse>>;
+    /**
+     * Import rules in bulk
+     */
+    importRules(rules: DetectionApiPayload[]): Promise<ApiResponse<ImportRulesResponse>>;
+    /**
+     * Export all rules
+     */
+    exportRules(): Promise<ApiResponse<DetectionRule[]>>;
+}
+/**
+ * Convert a parsed Detection to API payload format
+ */
+declare function detectionToApiPayload(detection: Detection): DetectionApiPayload;
+/**
+ * Convert an API DetectionRule back to Detection format (for diffing)
+ */
+declare function detectionRuleToDetection(rule: DetectionRule, filePath: string): Detection;
+
+/**
+ * Event grouping logic for alert_mode=grouped detection testing
+ *
+ * Matches the in-product rule tester's bucketing behavior:
+ * events are grouped into clock-aligned windows based on lookback_minutes,
+ * and each bucket surfaces the dominant entity.
+ */
+
+/**
+ * Entity fields scanned in priority order for dominant entity detection.
+ * Matches the in-product rule tester's ENTITY_FIELDS list.
+ */
+declare const ENTITY_FIELDS_PRIORITY: readonly ["src_ip", "dest_ip", "user", "src_user", "dest_user", "src_host", "dest_host", "host", "hostname", "process_name", "file_hash", "process_hash"];
+/**
+ * Get the dominant entity from a set of events.
+ * Scans entity fields in priority order, returns the most frequent value
+ * from the first field that has any values.
+ */
+declare function getDominantEntity(events: Record<string, unknown>[]): GroupedTestBucket['dominant_entity'];
+/**
+ * Bucket events into clock-aligned time windows based on lookback minutes.
+ *
+ * Uses the same algorithm as the in-product rule tester:
+ *   windowStart = Math.floor(epochMs / windowMs) * windowMs
+ *
+ * This aligns windows to clock boundaries (e.g., 14:45, 15:00, 15:15 for 15m windows)
+ * matching how the cron scheduler fires in production.
+ */
+declare function bucketEventsByLookback(events: Record<string, unknown>[], lookbackMinutes: number): GroupedTestBucket[];
+
+export { type AiTriageHints, type AlertMode, type ApiResponse, type AutoTuningConfig, type AutoTuningMode, type BulkUpdateRulesRequest, type BulkUpdateRulesResponse, type CaseVisibility, type DailyMatchCount, type Detection, type DetectionApiPayload, type DetectionFrontmatter, type DetectionMatch, type DetectionMatchesResponse, type DetectionMode, type DetectionResponse, type DetectionRule, ENTITY_FIELDS_PRIORITY, type FormatQueryResponse, type GroupedTestBucket, type HistoricalAnalysisResult, type ImportRulesResponse, NanosiemClient, type NanosiemClientConfig, type ParseError, type ParseErrorType, type ParseResult, type RepositoryMetadata, type RequiresConfig, type RuleMode, type SearchResult, type Severity, type ValidateDetectionResponse, type ValidationError, type ValidationResult, type ValidationWarning, bucketEventsByLookback, detectionRuleToDetection, detectionToApiPayload, getDominantEntity, parseDetectionFile, parseLookbackToMinutes, parseMultipleFiles, serializeDetection, validateDetection };