@panguard-ai/core 0.1.0

package/dist/rules/sigma-parser.js

@@ -0,0 +1,180 @@
+/**
+ * Sigma YAML rule parser
+ * Sigma YAML 規則解析器
+ *
+ * Parses Sigma rules from YAML format into typed SigmaRule objects.
+ * Validates required fields and logs warnings for missing optional fields.
+ * 將 Sigma 規則從 YAML 格式解析為型別化的 SigmaRule 物件。
+ * 驗證必要欄位並對缺少的可選欄位記錄警告。
+ *
+ * @module @panguard-ai/core/rules/sigma-parser
+ */
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('sigma-parser');
+/** Valid Sigma rule status values / 有效的 Sigma 規則狀態值 */
+const VALID_STATUSES = new Set(['experimental', 'test', 'stable']);
+/** Valid severity levels / 有效的嚴重等級 */
+const VALID_LEVELS = new Set(['info', 'low', 'medium', 'high', 'critical']);
+/**
+ * Parse a Sigma rule from a YAML string
+ * 從 YAML 字串解析 Sigma 規則
+ *
+ * Validates required fields (title, detection, level) and normalizes
+ * optional fields with sensible defaults.
+ * 驗證必要欄位（title、detection、level）並以合理預設值標準化可選欄位。
+ *
+ * @param yamlContent - Raw YAML string content / 原始 YAML 字串內容
+ * @returns Parsed SigmaRule or null if validation fails / 解析後的 SigmaRule，驗證失敗則回傳 null
+ */
+export function parseSigmaYaml(yamlContent) {
+    let parsed;
+    try {
+        parsed = yaml.load(yamlContent);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error('Failed to parse YAML content / 解析 YAML 內容失敗', { error: message });
+        return null;
+    }
+    if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
+        logger.error('YAML content is not an object / YAML 內容不是物件');
+        return null;
+    }
+    const doc = parsed;
+    // --- Validate required fields / 驗證必要欄位 ---
+    if (typeof doc['title'] !== 'string' || doc['title'].trim() === '') {
+        logger.error('Missing or invalid required field: title / 缺少或無效的必要欄位: title');
+        return null;
+    }
+    if (doc['detection'] === undefined ||
+        doc['detection'] === null ||
+        typeof doc['detection'] !== 'object') {
+        logger.error('Missing or invalid required field: detection / 缺少或無效的必要欄位: detection');
+        return null;
+    }
+    const rawDetection = doc['detection'];
+    if (typeof rawDetection['condition'] !== 'string') {
+        logger.error('Missing or invalid required field: detection.condition / 缺少或無效的必要欄位: detection.condition');
+        return null;
+    }
+    const levelStr = typeof doc['level'] === 'string' ? doc['level'].toLowerCase() : '';
+    if (!VALID_LEVELS.has(levelStr)) {
+        logger.error(`Invalid or missing level: "${String(doc['level'])}" / 無效或缺少嚴重等級: "${String(doc['level'])}"`, {
+            validLevels: [...VALID_LEVELS],
+        });
+        return null;
+    }
+    // --- Parse optional fields with warnings / 解析可選欄位並記錄警告 ---
+    if (doc['id'] === undefined) {
+        logger.warn('Missing optional field: id - a unique identifier is recommended / 缺少可選欄位: id - 建議提供唯一識別碼');
+    }
+    if (doc['author'] === undefined) {
+        logger.warn('Missing optional field: author / 缺少可選欄位: author');
+    }
+    if (doc['date'] === undefined) {
+        logger.warn('Missing optional field: date / 缺少可選欄位: date');
+    }
+    if (doc['tags'] === undefined) {
+        logger.warn('Missing optional field: tags / 缺少可選欄位: tags');
+    }
+    if (doc['falsepositives'] === undefined) {
+        logger.warn('Missing optional field: falsepositives / 缺少可選欄位: falsepositives');
+    }
+    if (doc['references'] === undefined) {
+        logger.warn('Missing optional field: references / 缺少可選欄位: references');
+    }
+    // --- Build logsource / 建立日誌來源 ---
+    const rawLogSource = typeof doc['logsource'] === 'object' && doc['logsource'] !== null
+        ? doc['logsource']
+        : {};
+    const logsource = {};
+    if (typeof rawLogSource['category'] === 'string')
+        logsource.category = rawLogSource['category'];
+    if (typeof rawLogSource['product'] === 'string')
+        logsource.product = rawLogSource['product'];
+    if (typeof rawLogSource['service'] === 'string')
+        logsource.service = rawLogSource['service'];
+    // --- Build detection / 建立偵測區塊 ---
+    const detection = {
+        condition: rawDetection['condition'],
+    };
+    for (const [key, value] of Object.entries(rawDetection)) {
+        if (key === 'condition')
+            continue;
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const selectionMap = {};
+            for (const [fieldName, fieldValue] of Object.entries(value)) {
+                if (typeof fieldValue === 'string') {
+                    selectionMap[fieldName] = fieldValue;
+                }
+                else if (Array.isArray(fieldValue)) {
+                    selectionMap[fieldName] = fieldValue.map(String);
+                }
+                else {
+                    selectionMap[fieldName] = String(fieldValue);
+                }
+            }
+            detection[key] = selectionMap;
+        }
+    }
+    // --- Normalize status / 標準化狀態 ---
+    const statusStr = typeof doc['status'] === 'string' ? doc['status'].toLowerCase() : 'experimental';
+    const status = VALID_STATUSES.has(statusStr)
+        ? statusStr
+        : 'experimental';
+    if (!VALID_STATUSES.has(typeof doc['status'] === 'string' ? doc['status'].toLowerCase() : '')) {
+        logger.warn(`Invalid or missing status "${String(doc['status'])}", defaulting to "experimental" / 無效或缺少狀態，預設為 "experimental"`);
+    }
+    // --- Build tags and falsepositives arrays / 建立標籤和誤報陣列 ---
+    const tags = Array.isArray(doc['tags']) ? doc['tags'].map(String) : undefined;
+    const falsepositives = Array.isArray(doc['falsepositives'])
+        ? doc['falsepositives'].map(String)
+        : undefined;
+    const references = Array.isArray(doc['references']) ? doc['references'].map(String) : undefined;
+    const rule = {
+        id: typeof doc['id'] === 'string' ? doc['id'] : `auto-${Date.now()}`,
+        title: doc['title'],
+        status,
+        description: typeof doc['description'] === 'string' ? doc['description'] : '',
+        logsource,
+        detection,
+        level: levelStr,
+        ...(typeof doc['author'] === 'string' ? { author: doc['author'] } : {}),
+        ...(doc['date'] !== undefined ? { date: String(doc['date']) } : {}),
+        ...(tags !== undefined ? { tags } : {}),
+        ...(falsepositives !== undefined ? { falsepositives } : {}),
+        ...(references !== undefined ? { references } : {}),
+    };
+    logger.info(`Successfully parsed Sigma rule: "${rule.title}" (${rule.id}) / 成功解析 Sigma 規則: "${rule.title}" (${rule.id})`);
+    return rule;
+}
+/**
+ * Parse a Sigma rule from a YAML file on disk
+ * 從磁碟上的 YAML 檔案解析 Sigma 規則
+ *
+ * Reads the file contents and delegates to parseSigmaYaml.
+ * 讀取檔案內容並委派給 parseSigmaYaml。
+ *
+ * @param filePath - Absolute or relative path to the YAML file / YAML 檔案的絕對或相對路徑
+ * @returns Parsed SigmaRule or null if file read or parsing fails / 解析後的 SigmaRule，讀取或解析失敗則回傳 null
+ */
+export function parseSigmaFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const rule = parseSigmaYaml(content);
+        if (rule === null) {
+            logger.error(`Failed to parse Sigma file: ${filePath} / 解析 Sigma 檔案失敗: ${filePath}`);
+        }
+        return rule;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Failed to read Sigma file: ${filePath} / 讀取 Sigma 檔案失敗: ${filePath}`, {
+            error: message,
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=sigma-parser.js.map

package/dist/rules/sigma-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigma-parser.js","sourceRoot":"","sources":["../../src/rules/sigma-parser.ts"],"names":[],"mappings":"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"}

package/dist/rules/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Sigma rules engine type definitions
+ * Sigma 規則引擎型別定義
+ *
+ * Defines all types used by the Sigma rule parser, matcher, and engine.
+ * 定義 Sigma 規則解析器、比對器和引擎使用的所有型別。
+ *
+ * @module @panguard-ai/core/rules/types
+ */
+import type { Severity, SecurityEvent } from '../types.js';
+/**
+ * Sigma log source definition
+ * Sigma 日誌來源定義
+ *
+ * Describes where a rule's log data originates from.
+ * 描述規則的日誌資料來源。
+ */
+export interface SigmaLogSource {
+    /** Log category (e.g., 'authentication', 'process_creation') / 日誌分類 */
+    category?: string;
+    /** Product name (e.g., 'windows', 'linux', 'any') / 產品名稱 */
+    product?: string;
+    /** Service name (e.g., 'sshd', 'sysmon') / 服務名稱 */
+    service?: string;
+}
+/**
+ * Sigma detection block
+ * Sigma 偵測區塊
+ *
+ * Contains named selections and a condition expression that combines them.
+ * Each selection maps field names to expected values (string or string[]).
+ * Field names may include modifiers like '|contains', '|endswith', '|startswith'.
+ * 包含命名選擇項和組合它們的條件表達式。
+ * 每個選擇項將欄位名稱映射到預期值（字串或字串陣列）。
+ * 欄位名稱可包含修飾符如 '|contains'、'|endswith'、'|startswith'。
+ */
+export interface SigmaDetection {
+    /** Named selections mapping field names to expected values / 命名選擇項，將欄位名映射到預期值 */
+    [selectionName: string]: Record<string, string | string[]> | string;
+    /** Condition expression combining selections (e.g., 'selection1 AND selection2') / 組合選擇項的條件表達式 */
+    condition: string;
+}
+/**
+ * Sigma rule definition
+ * Sigma 規則定義
+ *
+ * A complete Sigma rule that can be parsed from YAML and matched against events.
+ * 可從 YAML 解析並與事件比對的完整 Sigma 規則。
+ */
+export interface SigmaRule {
+    /** Unique rule identifier / 唯一規則識別碼 */
+    id: string;
+    /** Rule title / 規則標題 */
+    title: string;
+    /** Rule maturity status / 規則成熟度狀態 */
+    status: 'experimental' | 'test' | 'stable';
+    /** Rule description / 規則描述 */
+    description: string;
+    /** Rule author / 規則作者 */
+    author?: string;
+    /** Rule creation or last modification date / 規則建立或最後修改日期 */
+    date?: string;
+    /** Log source specification / 日誌來源規格 */
+    logsource: SigmaLogSource;
+    /** Detection logic with selections and condition / 偵測邏輯，包含選擇項和條件 */
+    detection: SigmaDetection;
+    /** Alert severity level / 警報嚴重等級 */
+    level: Severity;
+    /** Tags (e.g., MITRE ATT&CK references) / 標籤（如 MITRE ATT&CK 參考） */
+    tags?: string[];
+    /** Known false positive scenarios / 已知誤報情境 */
+    falsepositives?: string[];
+    /** External reference URLs / 外部參考連結 */
+    references?: string[];
+    /** Rule source: custom (Panguard original) or community (SigmaHQ etc.) / 規則來源 */
+    source?: 'custom' | 'community';
+}
+/**
+ * Result of matching an event against a Sigma rule
+ * 安全事件與 Sigma 規則比對的結果
+ *
+ * Produced when an event matches a rule's detection logic.
+ * 當事件符合規則的偵測邏輯時產生。
+ */
+export interface RuleMatch {
+    /** The matched Sigma rule / 比對到的 Sigma 規則 */
+    rule: SigmaRule;
+    /** The event that triggered the match / 觸發比對的事件 */
+    event: SecurityEvent;
+    /** Field names that matched in the detection / 偵測中比對到的欄位名稱 */
+    matchedFields: string[];
+    /** ISO timestamp when the match was detected / 偵測到比對的 ISO 時間戳 */
+    timestamp: string;
+}
+/**
+ * Configuration for the rule engine
+ * 規則引擎配置
+ *
+ * Controls how the rule engine loads and manages rules.
+ * 控制規則引擎如何載入和管理規則。
+ */
+export interface RuleEngineConfig {
+    /** Directory containing custom Sigma rule YAML files / 包含自訂 Sigma 規則 YAML 檔案的目錄 */
+    rulesDir?: string;
+    /** Directory containing community Sigma rules (e.g., SigmaHQ) / 包含社群 Sigma 規則的目錄 */
+    communityRulesDir?: string;
+    /** Enable hot-reloading of rules when files change / 啟用檔案變更時的規則熱載入 */
+    hotReload?: boolean;
+    /** Pre-loaded custom rules / 預載入的自訂規則 */
+    customRules?: SigmaRule[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rules/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IACpE,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3C,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,SAAS,EAAE,cAAc,CAAC;IAC1B,oEAAoE;IACpE,SAAS,EAAE,cAAc,CAAC;IAC1B,oCAAoC;IACpC,KAAK,EAAE,QAAQ,CAAC;IAChB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iFAAiF;IACjF,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,IAAI,EAAE,SAAS,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,aAAa,CAAC;IACrB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;CAC3B"}

package/dist/rules/types.js

@@ -0,0 +1,11 @@
+/**
+ * Sigma rules engine type definitions
+ * Sigma 規則引擎型別定義
+ *
+ * Defines all types used by the Sigma rule parser, matcher, and engine.
+ * 定義 Sigma 規則解析器、比對器和引擎使用的所有型別。
+ *
+ * @module @panguard-ai/core/rules/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rules/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rules/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/rules/yara-scanner.d.ts

@@ -0,0 +1,103 @@
+/**
+ * YARA Scanner - File scanning using YARA rules
+ * YARA 掃描器 - 使用 YARA 規則掃描檔案
+ *
+ * Provides an abstraction over YARA scanning that:
+ * - Loads .yar rule files from a directory
+ * - Scans individual files or entire directories
+ * - Converts results to SecurityEvent format for unified pipeline
+ * - Gracefully degrades when YARA native bindings are not available
+ *
+ * @module @panguard-ai/core/rules/yara-scanner
+ */
+import type { SecurityEvent } from '../types.js';
+/** YARA match result / YARA 比對結果 */
+export interface YaraMatch {
+    rule: string;
+    namespace: string;
+    tags: string[];
+    meta: Record<string, string>;
+    strings: Array<{
+        identifier: string;
+        offset: number;
+        data: string;
+    }>;
+}
+/** YARA scan result for a single file / 單一檔案的 YARA 掃描結果 */
+export interface YaraScanResult {
+    filePath: string;
+    fileSize: number;
+    sha256: string;
+    matches: YaraMatch[];
+    scannedAt: string;
+    durationMs: number;
+}
+/**
+ * YARA-based file scanner
+ * 基於 YARA 的檔案掃描器
+ *
+ * Supports two modes:
+ * 1. Native YARA via @automattic/yara (requires native bindings)
+ * 2. Pattern-based fallback using regex matching on file content
+ */
+export declare class YaraScanner {
+    private ruleFiles;
+    private compiledPatterns;
+    private yaraAvailable;
+    /** Load YARA rules from a directory (non-recursive) / 從目錄載入 YARA 規則（非遞迴） */
+    loadRules(rulesDir: string): Promise<number>;
+    /**
+     * Recursively load YARA rules from a directory tree
+     * 從目錄樹遞迴載入 YARA 規則
+     *
+     * @param rulesDir - Root directory to scan / 要掃描的根目錄
+     * @param source - Source tag for loaded rules / 載入規則的來源標記
+     * @returns Number of rule files loaded / 載入的規則檔數量
+     */
+    loadRulesRecursive(rulesDir: string, source?: 'custom' | 'community'): Promise<number>;
+    /**
+     * Load rules from both custom and community directories
+     * 從自訂和社群目錄載入規則
+     *
+     * @param customDir - Custom rules directory / 自訂規則目錄
+     * @param communityDir - Optional community rules directory / 可選的社群規則目錄
+     * @returns Total number of rule files loaded / 載入的規則檔總數
+     */
+    loadAllRules(customDir: string, communityDir?: string): Promise<number>;
+    /** Recursively collect .yar/.yara files and append to this.ruleFiles */
+    private loadFromDirRecursive;
+    /** Get number of loaded rule files / 取得已載入的規則檔數量 */
+    getRuleCount(): number;
+    /** Check if native YARA is available / 檢查原生 YARA 是否可用 */
+    isNativeAvailable(): boolean;
+    /**
+     * Scan a single file / 掃描單一檔案
+     */
+    scanFile(filePath: string): Promise<YaraScanResult>;
+    /**
+     * Scan a directory recursively / 遞迴掃描目錄
+     */
+    scanDirectory(dirPath: string, options?: {
+        maxDepth?: number;
+        extensions?: string[];
+    }): Promise<YaraScanResult[]>;
+    /**
+     * Convert YARA scan result to SecurityEvent / 轉換 YARA 掃描結果為 SecurityEvent
+     */
+    toSecurityEvent(result: YaraScanResult): SecurityEvent | null;
+    private checkNativeYara;
+    private scanWithNativeYara;
+    /**
+     * Fallback pattern-based scanning / 退路：基於模式的掃描
+     * Extracts string patterns from YARA rules and matches against file content
+     */
+    private scanWithPatterns;
+    /**
+     * Parse YARA rule files into compiled patterns for fallback matching
+     * 解析 YARA 規則檔為編譯的模式（退路比對用）
+     */
+    private compilePatterns;
+    private inferSeverity;
+    private walkDir;
+}
+//# sourceMappingURL=yara-scanner.d.ts.map

package/dist/rules/yara-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yara-scanner.d.ts","sourceRoot":"","sources":["../../src/rules/yara-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,aAAa,CAAS;IAE9B,4EAA4E;IACtE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiClD;;;;;;;OAOG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA0C5F;;;;;;;OAOG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB7E,wEAAwE;YAC1D,oBAAoB;IAoClC,oDAAoD;IACpD,YAAY,IAAI,MAAM;IAItB,yDAAyD;IACzD,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAyBzD;;OAEG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GACzD,OAAO,CAAC,cAAc,EAAE,CAAC;IAS5B;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI;YAkC/C,eAAe;YASf,kBAAkB;IAsChC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAkCxB;;;OAGG;IACH,OAAO,CAAC,eAAe;IA6DvB,OAAO,CAAC,aAAa;YAeP,OAAO;CAkCtB"}