repins267/exa-tools

# exa-tools      Python 自动化工具包，专为 Exabeam New-Scale Analytics (NSA) / SIEM 打造。专为需要快速处理检测工程、合规性和内容管理而无需频繁操作 UI 的安全工程师设计。 **检测规则转换** 通过共享的 `SPL → Sigma → EQL` 流水线处理 Splunk SPL 搜索和 SigmaHQ 社区规则，该流水线由 **Field Oracle** 提供支持——这是一个包含 4,258 个 raw→CIM2 字段映射的本地索引，从 Exabeam 自身的解析器定义中提取。每个转换后的字段都会获得一个置信度评级（Oracle / Schema / Passthrough），让您在部署前准确了解哪些内容已验证。 **一步式部署** 通过 API 将转换后的规则直接推送到您的租户。多租户支持允许您使用 `--tenant` 定位任何已注册的环境。 **Threat Center 集成** 为分析师提供了用于案件和警报的完整 CLI 工作流——搜索、分类、更新和鉴定。`exa case qualify` 会拉取触发关联规则、实体历史、上下文表成员资格和分数趋势，然后发出结构化裁定（SUSPECTED_INCIDENT / LIKELY_FP / LEARNING_PHASE_NOISE / NEEDS_INVESTIGATION）以帮助分析师更快地做出决定。 **结果追踪与校准** 记录每次鉴定并追踪分析师随时间做出的决策。`exa case baseline` 使用租户许可的 LTS 保留窗口拉取历史已结案件，计算每个规则和每个实体的误报率，并将该校准结果自动反馈到未来的裁定中。 **检测管理** 可跨租户导出、导入和比对分析规则——支持规则备份、迁移和跨环境差距分析。 **合规审计** 跨 11 个框架运行自动化证据收集——NIST CSF v2.0、CMMC L2/L3、PCI DSS、HIPAA、FedRAMP Moderate、CIS Controls v8、ISO 27001、CJIS、GDPR 和 SOX——并生成包含执行摘要和差距分析的 HTML 和 PDF 报告。查询是使用 **Field Oracle 概念解析** 针对每个租户动态构建的，以确保控制措施与每个环境中实际存在的 `activity_type` 值相匹配。 **上下文表管理** 处理支持 2万条记录批量的 CRUD 操作，包括为 AI/LLM 威胁检测参考表预构建的同步。 一切皆可通过命令行完成。  ## 前置条件 - Python 3.12+ - [uv](https://docs.astral.sh/uv/) - git (`exa update` 需要) - Windows 凭据管理器 / Keychain (macOS) / Secret Service (Linux) ## 安装 ``` git clone exa-tools cd exa-tools uv sync ``` ## 首次设置 ``` uv tool install -e . # install exa globally from local source exa configure # set up tenant credentials (stored in keyring) exa update # clone CIM2 + SigmaHQ repos and build Field Oracle ``` ## 快速开始 ``` exa configure # set up tenant + credentials exa update # download reference data + build oracle exa sigma convert --rule proc_creation_powershell_encoded.yml exa splunk one 'index=ad CommandLine="*mimikatz*"' --title "Mimikatz Detection" ``` ## 命令 每个命令都支持 `--help` 以获取完整的用法和标志描述： ``` exa --help # list all commands exa sigma convert --help # flags for a specific command exa splunk deploy --help ``` ### `exa configure` 交互式设置：输入您的租户 FQDN、客户端 ID 和客户端密钥。测试连接，将凭据保存到密钥环，并可选地下载 CIM2/SigmaHQ 参考数据。 ### `exa update` ``` exa update # sync CIM2 + SigmaHQ repos, build Field Oracle exa update self # git pull main + uv sync on exa-tools itself exa update --check # show current SHAs without pulling ``` 下载 [Content-Library-CIM2](https://github.com/ExabeamLabs/Content-Library-CIM2)、[new-scale-content-hub](https://github.com/ExabeamLabs/new-scale-content-hub) 和 [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma)，然后从 8,278 个解析器定义文件构建 Field Oracle。 ### `exa config` ``` exa config set sigma.rules-dir "E:\SigmaHQ\rules\windows" exa config set default-tenant sademodev22 exa config get sigma.rules-dir exa config show ``` 配置存储在 `~/.exa/config.json`。密钥永远不会写入此文件。 ### `exa tables` ``` exa tables list [--name FILTER] [--tenant TENANT] [--json] exa tables create NAME [--type TYPE] [--key COLNAME] [--columns a,b,c] [--csv PATH] [--replace] [--tenant TENANT] --type Context type: Other (default), User, TI_ips, TI_domains, Device, Domain, IP --key Key column name (default: "key", or first CSV column) --columns Extra column names (comma-separated; ignored if --csv given) --csv CSV file — headers become columns, rows uploaded immediately --replace Use replace semantics when uploading CSV (default: append) exa tables delete TABLE [--yes] [--purge-attributes] [--tenant TENANT] TABLE Table ID or display name exa tables records list TABLE [--limit N] [--offset N] [--csv PATH] [--json] [--tenant TENANT] exa tables records upload TABLE CSV_PATH [--replace] [--key COLNAME] [--tenant TENANT] --replace Overwrite entire table (default: append) exa tables records export TABLE OUTPUT_PATH [--tenant TENANT] ``` ### `exa hotkey` 诊断并修复由粗粒度 Network Zones 上下文表条目引起的 Apache Beam/Dataflow 热键风险。已确认可修复 Dataflow worker 不平衡问题（已知客户，作业 cv06f9，运行时间 47 分钟，出现 96 条 HotKeyLogger 警告）。 ``` exa hotkey analyze [--ip-field COL] [--name-field COL] [--json] [--csv] [--tenant TENANT] Classify Network Zones table entries by Dataflow hot key risk. COARSE = /8 or /16 (high risk). MEDIUM = /24 (acceptable). FINE = /32. exa hotkey scan [--lookback N] [--threshold N] [--limit N] [--ip-field COL] [--name-field COL] [--json] [--csv] [--tenant TENANT] Scan recent events for active source IPs per zone. Flags zones with >N distinct IPs as HOT_KEY_RISK (default threshold: 500). exa hotkey expand [--zone ZONE] [--lookback N] [--enumerate] [--dry-run] [--limit N] [--ip-field COL] [--name-field COL] [--tenant TENANT] Expand COARSE zone(s) from /8 or /16 to /24-granularity entries. Writes a rollback manifest to ~/.exa/hotkey-rollback/ before any change. --zone Target a single zone by name (default: all COARSE zones) --enumerate Create all /24 subnets in range (default: observed IPs only) --dry-run Print planned changes without writing anything exa hotkey autofix [--lookback N] [--threshold N] [--max-zones N] [--enumerate] [--dry-run] [--json] [--tenant TENANT] Full automated pipeline: analyze → scan → expand in one command. --max-zones Safety cap (default 10). Refuses to expand more zones than this in a single run. Safe to schedule — non-interactive, exits non-zero on any failure. exa hotkey rollback [--manifest PATH] [--confirm] [--tenant TENANT] Restore Network Zones table from the most recent rollback manifest. Use --manifest to specify an older manifest by path. Requires --confirm to apply (shows diff first without it). ``` ### `exa sigma convert` ``` exa sigma convert --rule proc_creation_powershell_encoded.yml exa sigma convert --dir ./rules/windows/ exa sigma convert --dir ./rules/ --deploy exa sigma convert --dir ./rules/ --deploy --tenant sademodev22 ``` 将 Sigma YAML 规则转换为 Exabeam EQL 关联规则。Field Oracle 为每个字段映射提供置信度评级。使用 `--deploy` 时，会通过 API 在租户上创建关联规则。 短别名：`exa sc` ### `exa sigma deploy` ``` exa sigma deploy --rule proc_creation_powershell_encoded.yml --tenant sademodev22 ``` 一步完成转换单个 Sigma 规则并部署。短别名：`exa sd` ### `exa sigma browse` ``` exa sigma browse --category process_creation --level high exa sigma browse --tag t1059 --product windows exa sigma browse --search "powershell" ``` 从本地索引浏览 SigmaHQ 社区规则。按类别、产品、级别、ATT&CK 标签或关键字进行过滤。 ### `exa splunk convert` ``` # 批量转换包含 'title' 和 'search' 列的 Excel 文件 exa splunk convert searches.xlsx # 显示所有包含字段置信度的逐规则警告 exa splunk convert searches.xlsx --verbose # 自定义输出文件 exa splunk convert searches.xlsx --output rules.json # 跳过 RGXi 自动压缩（见下文） exa splunk convert searches.xlsx --no-compress ``` 输出一个丰富的表格，显示每个规则的索引、活动类型、EQL 预览、警告数量和部署状态。保存所有 API 就绪的 JSON 负载文件。 #### EQL 溢出自动压缩 Exabeam 的关联规则 API 强制执行 **1024 字符的 EQL 限制**。带有大型通配符值列表的 SPL 搜索（例如 40 个 `file-name=UBR*.py` 条件）通常会超出此限制。转换器不会将这些规则静默标记为 `EQL too long`，而是会自动压缩它们： - **通配符列表** (`file-name=Foo*`, `file-path=*bar*`)：折叠为每个字段一个 `RGXi("a|b|c")` 交替项。每个 sigma 修饰符都会被保留——`startswith` → `^prefix`，`endswith` → `suffix$`，`contains` → 内部片段，middle-glob → `^foo.*bar$`。 - **精确值列表**（无通配符）：记录为上下文表候选，并写入 `

.tables.json` 随主 JSON 一起以供将来部署。 如果压缩后 EQL 降至 1024 字符以下，该规则将被提升为 `Needs review`，并附带警告，例如 `Compressed field 'file_name' wildcard list → RGXi to fit API limit`。如果压缩后的 EQL 仍然超出限制（包含数百个值的病态情况），则规则仍保持 `EQL too long` 状态。 使用 `--no-compress` 跳过压缩并查看原始未修改的 EQL。 ### `exa splunk one` 内联转换单个 SPL 搜索——无需 Excel 文件。 ``` exa splunk one 'index=c42 severity="High"' --title "Code42 High Severity Alert" exa splunk one 'index=o365 Operation=Send' --title "O365 Outbound Email" exa splunk one 'index=ad CommandLine="*mimikatz*"' --json exa splunk one 'index=fireamp_stream severity="High"' --title "AMP Alert" -o rule.json ``` ### `exa splunk deploy` ``` exa splunk deploy rules.json --dry-run --tenant sademodev22 # preview exa splunk deploy rules.json --tenant sademodev22 # deploy (disabled by default) ``` 所有规则默认创建为**禁用**状态。在启用之前，请在 Exabeam UI 中验证 EQL。 ### `exa compliance audit` 针对您的 Exabeam 租户运行差距分析合规性审计。使用实时事件数据查询每个可进行 SIEM 测试的控制措施，并生成包含证据数量的通过/失败结果。 ``` # 基础审计（默认启用 tenant-aware 模式） exa compliance audit --framework "NIST CSF v2.0" --lookback 30 # 指定 tenant exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --lookback 30 # 保存 HTML 报告（自动命名为 reports/--.html） exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --output-html # 将 HTML 保存至显式路径 exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --output-html C:\reports\audit.html # 保存 PDF 报告（自动命名，通过 Microsoft Edge headless 渲染） exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --output-pdf # 将 PDF 保存至显式路径 exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --pdf-path C:\reports\audit.pdf # Tenant-aware 模式（默认） — 通过 Field Oracle 发现活跃的 activity_types exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --tenant-aware # 静态模式 — 仅使用 JSON 中的硬编码过滤器，跳过 tenant 发现 exa compliance audit --framework "NIST CSF v2.0" --tenant lvcva --no-tenant-aware ``` **输出标志：** | 标志 | 行为 | |---|---| | `--output-html` | 自动将 HTML 保存到 `reports/` | | `--output-html ` | 将 HTML 保存到指定路径 | | `--output-pdf` | 通过 Edge headless 自动将 PDF 保存到 `reports/` | | `--pdf-path ` | 将 PDF 保存到指定路径 | | `--tenant-aware` | 通过 Field Oracle 概念解析动态生成 EQL（默认：开启） | | `--no-tenant-aware` | 使用来自 ControlQueries JSON 的静态过滤器 | HTML 报告保存在 `reports/` 中，包含执行摘要、系列覆盖范围细分和差距分析。PDF 报告通过无头 Microsoft Edge (`msedge.exe --headless --print-to-pdf`) 从 HTML 渲染——Windows 上无需额外软件。 **支持的框架：** | 框架 | 可进行 SIEM 测试的控制措施 | 状态 | |---|---|---| | NIST CSF v2.0 | 60 | 完整查询 + 概念注释 | | CIS Controls v8 | ~110 | 完整查询 + 概念注释 | | HIPAA | ~67 | 完整查询 + 概念注释 | | PCI DSS | ~153 | 完整查询 + 概念注释 | | FedRAMP Moderate | ~145 | 完整查询 + 概念注释 | | ISO 27001:2022 | ~58 | 完整查询 + 概念注释 | | CJIS | ~55 | 完整查询 + 概念注释 | | CMMC Level 2 | ~55 | 存根（查询待定） | | CMMC Level 3 | ~20 | 存根（查询待定） | | GDPR | ~30 | 存根（查询待定） | | SOX | ~15 | 存根（查询待定） | ### `exa cases` / `exa alerts` 搜索并管理 Threat Center 案件和警报。 ``` exa cases list # all open cases, last 30 days exa cases list --filter 'NOT stage:"CLOSED"' --limit 20 exa cases list --json # raw JSON for pipeline use exa cases get exa cases get --json exa cases update --stage CLOSED --closed-reason "False Positive" exa cases update --priority CRITICAL --assignee analyst@corp.com exa cases update --tags "reviewed,escalated" exa alerts list --filter 'priority:"HIGH"' --lookback 7 exa alerts get exa alerts update --priority LOW --tags "noise" ``` ### `exa case qualify` 针对单个案件的结构化分析师分类。拉取触发关联规则定义、实体案件历史、上下文表成员资格、分数趋势和外部 IP 注释——然后发出裁定。 ``` exa case qualify C-1042 exa case qualify C-1042 --window 30 # ±30 min event context window exa case qualify C-1042 --json # machine-readable QualificationReport ``` **裁定结果：** | 裁定 | 含义 | |---|---| | `SUSPECTED_INCIDENT` | 单事件规则，新实体，首次出现或分数持续攀升——立即调查 | | `LIKELY_FP` | 实体位于合规上下文表中，非新高点，或规则具有 >75% 的历史 FP 率 | | `LEARNING_PHASE_NOISE` | 阈值规则，分数稳定，3个以上先例案件——规则可能需要调整 | | `NEEDS_INVESTIGATION` | 分数激增或持续攀升且无缓解上下文 | ### `exa case outcome` 追踪并记录分析师对已鉴定案件的决定。每次 `qualify` 运行都会自动记录。 ``` exa case outcome list # all logged qualifications + current outcome exa case outcome sync # auto-fill outcomes for closed cases from API exa case outcome resolve C-1042 --outcome fp # manually record: tp | fp | noise | duplicate ``` ### `exa case baseline` 拉取历史已结案件，计算每个规则和每个实体的误报率，并写入校准缓存以改进未来的 `qualify` 裁定。 ``` exa case baseline # default 90-day lookback, LTS-capped exa case baseline --lookback 60 exa case baseline --report # show calibration table: rule | TP | FP | FP rate exa case baseline --json ``` 回溯期会自动限制在租户许可的 LTS 保留窗口（`GET /health-consumption/v1/consumption/lts`）内——无硬编码限制。 ### `exa detection` 导出、导入和管理分析 (UEBA) 规则。适用于备份、跨租户迁移以及审计启用/禁用状态。 ``` # 列表 — 表格视图 exa detection list # first 100 rules exa detection list --status enabled # enabled only exa detection list --status enabled --limit 0 # all enabled rules exa detection list --name "Brute Force" # name substring filter # 列表 — 导出格式 exa detection list --status enabled --limit 0 --csv # CSV to stdout exa detection list --status enabled --limit 0 --csv --output enabled.csv # CSV to file exa detection list --status enabled --limit 0 --json # JSON to stdout exa detection list --limit 0 --json --output all_rules.json # JSON to file # 单条规则 exa detection get # 启用 / 禁用 exa detection enable exa detection disable # 导出 / 导入 / 对比 bundles exa detection export # all rules → stdout (pipeable) exa detection export --out rules-backup.json exa detection import rules-backup.json exa detection import rules-backup.json --overwrite exa detection diff bundle-a.json bundle-b.json ``` 当 API 返回时，`list` 表会自动显示 **Type** 和 **Families** 列，并打印找到的不同规则类型的摘要。`--csv` 输出包含所有可用字段：`id, name, isEnabled, severity, type, families, author, createdAt, updatedAt, description`。 ### `exa search` ``` exa search 'activity_type:"authentication"' --lookback 7 --limit 500 exa search 'user:"admin"' --tenant sademodev22 ``` ### `exa frameworks` ``` exa frameworks # list all available compliance frameworks with testable control counts ``` ## 工作原理 ### SPL → Sigma → EQL 流水线 Splunk SPL 和 Exabeam EQL 是截然不同的语言。exa-tools 并未采用有损的直接转换，而是通过 [Sigma](https://github.com/SigmaHQ/sigma) 作为结构化中间格式进行路由： ``` Splunk SPL search ↓ exa/splunk/parser.py — extract index, fields, pipeline stages ↓ exa/splunk/to_sigma.py — build Sigma rule dict with logsource + detection ↓ exa/sigma/converter.py — map Sigma fields → CIM2, build EQL query ↓ Exabeam EQL correlation rule → deploy via API ``` 这意味着字段映射可以复用社区维护的 Sigma 字段词汇表，通配符值会变为适当的 Sigma 修饰符（`|contains`, `|endswith`, `|startswith`），而否定操作会变为适当的 `filter` 块。无法在 EQL 中表示的流水线阶段（`stats`、`eval`、`lookup` 等）会被作为警告记录，而不是被静默丢弃。 ### Field Oracle Field Oracle 是转换器核心的翻译引擎。它不依赖手工维护的字段映射或不完整的文档，而是直接读取 Exabeam 自身的解析器定义。 `exa update` 会遍历 `Content-Library-CIM2/DS/` 目录下 269 个供应商的 **8,278 个解析器文件**，并构建一个本地索引： - 从解析器正则表达式捕获组和 JSON 路径定义中提取的 **4,258 个 raw → CIM2 字段映射** - **25 个活动类型** 及其已确认字段集已被索引 - **269 个供应商** —— Code42、Digital Guardian、Microsoft O365、Cisco 以及数百个其他供应商 转换器解析的每个字段都会被分配一个置信度级别： | 置信度 | 含义 | |---|---| | `oracle` | 字段已在 DS/ 解器定义中针对该 vendor/activity_type 得到确认——无警告 | | `schema` | 字段存在于 CIM2_FIELD_MAP 中，但未在该特定来源的 DS/ 中得到确认 | | `passthrough` | 未找到映射——该字段不在该供应商的 CIM2 中 | 每次运行 `exa update` 时，Oracle 都会自动刷新。当 Exabeam 添加新的解析器字段时，转换器会在下次更新时自动识别它们——无需更改代码。 ### Field Oracle 概念解析（合规性） Field Oracle 还支持**租户感知的合规性审计**。每个合规性控制措施都标注了一个或多个语义**概念**（例如 `GROUP_MANAGEMENT`、`PERMISSION_CHANGE`），这些概念映射到特定的 `activity_type` 值。在审计时，**ConceptResolver** 会查询租户在回溯窗口内出现的所有活动类型，然后仅使用在该环境中确认存在的类型动态构建 EQL 过滤器。 ``` Control concepts → ConceptResolver (filters to tenant-active types) → ComplianceQueryBuilder (builds EQL filter string) → search_events (live query against tenant) ``` 这意味着合规性查询会自动适应每个客户的日志源，而无需针对每个租户进行手动调整。如果未连接日志源（例如物理访问控制），则控制措施会失败并显示明显的差距——而不是因为错误查询导致的假阴性。 ## 功能特性 - **Dataflow 热键检测和修复** (`exa hotkey`) —— 分析 Network Zones 上下文表中导致 Dataflow worker 不平衡的粗粒度 IP 分组；扫描实际流量以确认活跃的热键；将粗粒度区域条目扩展为 /24 粒度，并提供自动回滚支持 - **自更新** (`exa update self`) —— 一条命令完成 `git pull` + `uv sync`；使本地安装保持最新，而无需离开终端 - **上下文表完整 CRUD** (`exa tables`) —— 使用自动推导的 Schema 从 CSV 创建表；删除表；列出、上传（追加或替换）和导出记录；全部支持 2万条记录批量处理 - **Sigma 规则转换** —— 将 SigmaHQ YAML 规则转换为带有 CIM2 字段映射的 Exabeam EQL 关联规则 - **Splunk SPL 转换** —— SPL→Sigma→EQL 流水线；从 Excel 批量处理或通过 `exa splunk one` 内联一次性处理 - **一步式部署** —— 在单个命令中将 Sigma 或 Splunk 规则转换并部署到您的租户 - **Field Oracle** —— 来自 8,278 个解析器文件的 4,258 个 raw→CIM2 映射；用于规则和合规性的基于置信度的字段解析 - **CIM2 参考数据** —— 本地同步 Content-Library-CIM2 和 SigmaHQ 仓库 - **Threat Center — cases** —— 使用 EQL 过滤和富表格输出进行搜索、获取、更新和创建案件 - **Threat Center — alerts** —— 搜索、获取和更新警报；优先级颜色编码；支持 `--json` 用于管道操作 - **案件分类** (`exa case qualify`) —— 结构化分析师分类：规则定义、实体历史、上下文表成员资格、分数趋势、IP 注释以及四种结果的裁定 - **结果追踪** —— 每次运行 `qualify` 都会被记录；`exa case outcome sync` 从已结案件中回填分析师的决定 - **历史校准** (`exa case baseline`) —— 受 LTS 约束的回溯期限制为许可的保留期；每个规则和实体的 FP 率反馈到未来的裁定中 - **检测管理** —— 跨租户导出、导入和比对分析 (UEBA) 规则 - **AI/LLM 领域同步** —— 同步 6 个用于 AI/LLM 威胁检测的参考表 - **合规审计** —— 跨 11 个框架的自动化证据收集，支持租户感知查询解析，HTML + PDF 报告输出 - **事件搜索** —— 带时间范围和结果限制的 EQL 查询界面 - **凭据管理** —— 租户配置文件通过 keyring 存储在 Windows 凭据管理器中 ## Splunk 转换器 SPL→Sigma→EQL 流水线已在上文的[工作原理](#how-it-works)中介绍。操作说明如下： - 中间的 Sigma YAML 会被保存在输出文件中以供审计和复查 - 所有转换后的规则均为 `deploy_ready: Needs review` 状态——SPL→EQL 本质上是有损转换，在启用前需要人工审核批准 - EQL 超过 1024 个字符的规则会在被标记为 `EQL too long` 之前通过 RGXi 交替**自动压缩**——请参阅 [EQL 溢出自动压缩](#eql-overflow-auto-compression) ### 支持的索引 | Splunk Index | 数据源 | 默认 activity_type | |---|---|---| | `c42` | Code42 / Incydr DLP | `file-write` | | `c42` + `c42-alerts` | Code42 risk alerts | `rule-trigger` | | `c42` + `c42-file-exposure` | Code42 file exposure | `file-write` | | `ips` | Cisco Firepower IPS | `rule-trigger` | | `o365` | Microsoft O365 | `app-activity` | | `fireamp_stream` | Cisco Secure Endpoint | `rule-trigger` | | `dg` | Digital Guardian DLP | `file-write` | | `ad` | Active Directory / Sysmon | `process-create` | | `docexchange` | Document Exchange | `file-write` | | `plminfoexchangelogs` | Agile PLM Info Exchange | `app-activity` | ### 所有转换后的规则 - 命名为 `[Splunk]