Query-farm/vgi-sigma
GitHub: Query-farm/vgi-sigma
一个基于VGI的DuckDB worker，允许用户在SQL中直接评估Sigma检测规则以实现日志行的安全威胁检测。
Stars: 0 | Forks: 0
一个用于 DuckDB 的 Query.Farm VGI worker。
# vgi-sigma
**针对日志/事件行评估 [Sigma](https://sigmahq.io) 检测规则 —
detection-as-code，直接在 SQL 中实现。**
`vgi-sigma` 是一个 [VGI](https://github.com/Query-farm/vgi-python) worker：一个被 DuckDB 作为 catalog 挂载并像原生 SQL 函数一样调用的 Python 进程。
只需将 Sigma 规则编译**一次**，然后将其与日志表中的每一行进行测试：
```
INSTALL vgi FROM community; LOAD vgi;
ATTACH 'sigma' (TYPE vgi, LOCATION 'uv run sigma_worker.py');
-- The headline: which log rows match a rule?
SELECT *
FROM windows_security_log AS t
WHERE sigma.sigma_match(
to_json(t),
'title: Failed Network Logon
logsource: {product: windows, service: security}
detection:
selection:
EventID: 4625
LogonType: 3
condition: selection');
```
Sigma 是用于 SIEM 检测的开放、供应商中立的签名格式。该 worker 是一款**防御性安全工具**，它完善了 Query Farm 的网络防御矩阵，该矩阵还包括 `vgi-yara`、`vgi-ioc`、`vgi-cve`、`vgi-pe` 和 `vgi-x509`。
## 函数
### 标量函数（按行）
| 函数 | 签名 | 结果 |
|----------|-----------|--------|
| `sigma_match` | `(event_json VARCHAR, rule_yaml VARCHAR) → BOOLEAN` | JSON 事件是否匹配该规则？**核心功能。** |
| `sigma_check` | `(rule_yaml VARCHAR) → BOOLEAN` | 规则能否解析并编译（包含受支持的功能）？ |
标量函数接受**位置**参数。
```
SELECT sigma.sigma_match('{"EventID": 4625, "LogonType": 3}',
'logsource: {service: security}
detection: {sel: {EventID: 4625, LogonType: 3}, condition: sel}'); -- true
SELECT sigma.sigma_check(
'logsource: {service: security}
detection: {sel: {EventID: 1}, condition: sel}'); -- true
SELECT sigma.sigma_check(': not valid yaml :'); -- false
```
### 表函数
| 函数 | 签名 | 行 |
|----------|-----------|------|
| `sigma_rule_info` | `(rule_yaml VARCHAR)` | 单行：`title, id, level, status, description, product, service, tags VARCHAR[]` |
| `sigma_match_fields` | `(rule_yaml VARCHAR)` | 规则引用的每个事件字段对应一行（`field VARCHAR`） |
```
SELECT title, level, status FROM sigma.sigma_rule_info('
');
SELECT UNNEST(tags) AS tag FROM sigma.sigma_rule_info('');
SELECT field FROM sigma.sigma_match_fields(''); -- index / coverage planning
```
## 事件即 JSON 契约
`sigma_match` 将事件作为 **JSON 对象字符串**接收，其键名是规则引用的字段名。实际上，你可以使用 DuckDB 的 `to_json(t)` 针对某一行生成它（或者自行构建）：
```
SELECT sigma.sigma_match(to_json(t), :rule) FROM events AS t;
```
- **字段名必须与规则一致**（`EventID`、`LogonType`、`CommandLine` 等）。
- **嵌套字段**在规则中使用**点号**键进行寻址
（`process.name` → `event["process"]["name"]`）；事件对象中字面意义上的点号键也会被支持。这与 pySigma 自身的点号约定一致。
- **缺失的**字段永远不会满足肯定比较。
- 如果 **任何**元素匹配，则作为 JSON **列表**的事件值匹配成功。
- 格式错误的事件 JSON 会被视为**不匹配**（`false`）——一条损坏的日志行永远不会中止整个列扫描。NULL 事件或 NULL 规则将返回 NULL。
## 支持的 Sigma 特性
评估器会遍历 pySigma 解析后的**条件树**，因此条件逻辑得到了全面处理，同时值匹配涵盖了常见的修饰符集合。
**条件**（全部受支持 — pySigma 会将选择器展开到树中）：
- `and`、`or`、`not` 和括号
- `1 of selection*`、`all of selection*`、`1 of them`、`all of them`
- 关键字（无字段）搜索词 — 与事件中的每个值进行匹配
**字段修饰符**（受支持）：
| 修饰符 | 含义 |
|----------|---------|
| *（无）* | 不区分大小写的相等比较；对 `*`/`?` 通配符执行 glob 匹配 |
| `contains` | 不区分大小写的子串匹配 |
| `startswith` | 不区分大小写的前缀匹配 |
| `endswith` | 不区分大小写的后缀匹配 |
| `re` | 正则表达式（Python `re.search`） |
| `all` | 列出的每个值都必须匹配（而不是默认的 OR） |
| *（列表值）* | OR — 列出的值中任意一个匹配即可 |
数字和布尔值按值进行比较（当事件将它们字符串化时会进行合理的字符串类型强制转换）；`field: null` 可匹配缺失或为 null 的字段。
**不支持**（使用这些特性的规则在 `sigma_check` 中会被编译为 `false`，并在 `sigma_match` 或表函数中引发*明确的*错误——我们绝不会默默地产生错误的评估）：
`base64` / `base64offset`、`cidr`、数值比较 `lt`/`lte`/`gt`/`gte`、`utf16`/`wide`、字段引用（`fieldref`）、`|expand` 占位符以及关联规则。这是一个已记录的有意范围界定：旨在支持常见的 detection-as-code 匹配，而不是完整的 pySigma 后端功能集。
## 性能表现
VGI 会在多次查询期间保持 worker 处于活动状态，而解析和编译规则是极其耗费资源的步骤。`sigma_match` 会将每个不同的规则仅编译**一次**（以规则文本为键的 `lru_cache`），然后对每一行评估开销较小的条件树——因此，将一个常量规则应用于包含一百万行的日志列时，只需支付一次解析开销。
## 开发
```
uv sync --extra dev
uv run pytest -q # unit + integration
make test-sql # end-to-end SQL (haybarn-unittest)
uv run ruff check . && uv run mypy vgi_sigma/
```
`make test-sql` 会将 `VGI_SIGMA_WORKER` 指向作为 uv stdio 子进程运行的 worker（这与 DuckDB 在执行 `ATTACH` 后驱动它的方式完全相同），并运行 `test/sql/` 下的 sqllogictest 文件。使用
`uv tool install haybarn-unittest` 安装一次运行器即可。
## 许可证
`vgi-sigma` 基于 **MIT License** 授权——详见 [LICENSE](LICENSE)。
它依赖于 **[pySigma](https://github.com/SigmaHQ/pySigma)**（官方
`sigma` Python 包），该包基于 **GNU Lesser General Public
License v2.1 (LGPL-2.1)** 授权。pySigma 作为普通的已安装依赖**未被修改**地使用（仅进行导入，从未被更改或静态链接到衍生作品中）。该 worker 自身的源代码保持 MIT 授权；将其与 pySigma 一起重新分发时，必须遵守 pySigma 对该组件的 LGPL-2.1 条款。
## 作者与许可证
由 [Query.Farm](https://query.farm) 编写。
版权所有 2026 Query Farm LLC - https://query.farm标签：DuckDB, Python, Sigma规则, URL发现, 代码示例, 多线程, 安全检测, 数据分析, 无后门, 目标导入, 逆向工具