gfwleak/tango-maat
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2025-09-14. You can view files and clone it, but cannot push or open issues or pull requests.
Files
75e23c7d270b398c05dda19e9850850e7d25e8cc
tango-maat/docs/table_schema.md

288 lines
21 KiB
Markdown
Raw Normal View History

Using markdown files to replace MAAT网络流处理配置统一描述框架.docx
2023-05-04 06:16:42 +00:00
# Table Schema
自Maat 4.0，Item ID、Group ID、Compile ID的取值范围为0～2^63，即C语言long long类型。
## Item Table Schema
每个Item表必须包含
- Item ID，唯一标识一个Item。在一个Maat实例中，不同表的Item ID不得重复。
- Group ID，表明该Item所属的Group，一个Item属于且仅属于一个Group。
- 有效标志字段，1表示生效，在增量更新中表示添加；0表示失效，在增量更新中表示删除。
不同类型的表还根据各自需要定义了不同的字段。
### 字符串类域配置（含扩展后的）
用以描述针对字符串的匹配规则，匹配类型由expr_type字段描述，包括：
- 非表达式匹配方式，分为0：子串匹配；1：右匹配；2：左匹配；3：完全匹配
- 与表达式，最多支持8个子串或正则的与。
- 正则表达式
- 带偏移量的子串匹配，即规定某个字符串出现在某个位置的规则
- 偏移量从0开始计算，为[offset_start, offset_end]的闭区间。
- 多个带偏移量的子串可以与
Maat4.0后，仅支持UTF-8，不再进行编码转换。对于二进制格式的配置，其关键字格式为十六进制字符串，例如“欢乐”表示成“bbb6c0d6”，字母不区分大小写。关键字的内容不能包含空格、tab、回车等不可见字符，即不能包含ASCII范围0x00至0x1F及0x7F，如需要包含这些字符，需要进行转义，参见“关键字转义表”。该表以外使用反斜线引导的符号按普通字符串处理，如’\t’将按照字符串”\t”处理。
&符号在是MAAT中与表达式的连接运算符号，关键字中出现的&符号，必须使用’\&’进行转义。
表 2关键字转义表
| **字符名称** | ANSII码 | 转义后的符号 |
| ------------ | ------- | ------------ |
| 反斜线，’\’ | 0x5c | \\ |
| & | 0x26 | \& |
| 空格 | 0x20 | \b |
长度约束：
- 单个子串不小于3字节；
- 与表达式中的单个子串不小于3字节；
- 与表达式最多支持8个子串进行与运算，即7个&；
- 与表达式整体不超过1024字节，包括&；
表 3字符串类表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| --------------------------------------------- | ------------ | -------------- | -------- | ------------------------------------------------------------ |
| **配置****ID** | region_id | INT | N | 由同一config_id的不同域拆分而成，**主键**，各表不重复，以下各表中region_id/group_id/compile_id取值均为0～2^31。 |
| **分组ID** | group_id | INT | N | 分组关系表中的group_id |
| **关键字** | keywords | VARCHAR2(1024) | N | expr_type:1,2,3时， keywords中’&’为与运算操作符,子表达式中的’&’符号用’\&’转义。 expr_type:3时，格式为 offset_s1-offset_e1:keyword1& offset_s2-offset_e2:keyword2 expr_type:4时，格式为 <offset_s1,offset_e1><,>:keyword1&<offset_s2,offset_e2><distance,within>:keyword2 |
| **表达式类型** | expr_type | INT | N | 0:无表达式,1:表示为与表达式,2:正则表达式,3:带偏移量的子串匹配,4:带偏移量和相对位置的子串匹配(暂未支持) |
| **匹配方式** | match_method | INT | N | expr_type:0时有意义，其它情况必须置0。 0：子串匹配；1：右匹配；2：左匹配；3：完全匹配 |
| **是否****HEX****格式二进制，大小写敏感匹配** | is_hexbin | INT | N | 默认为0:大小写不敏感，且非HEX 1:HEX格式二进制，大小写敏感 2:大小写敏感，且非HEX 二进制格式是一种特殊的编码，受table_info.conf文件中do_merge控制 |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
### IP类域配置（含扩展后的）
用以描述IP地址的匹配规则，地址和端口都用字符串表示，其中IPv4为点分十进制，IPv6为冒号分隔的16进制。
表 4 IP类表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| ------------------ | ------------- | ------------ | -------- | ------------------------------------------------------------ |
| **域配置****ID** | region_id | INT | N | 由配置汇总表中统一id的不同域拆分而成，**主键**，各表不重复 |
| **分组ID** | group_id | INT | N | 分组关系表中的group_id |
| **地址类型** | addr_type | INT | N | Ipv4=4,ipv6=6 |
| **源IP****地址** | src_ip | VARCHAR2(40) | N | 0.0.0.0值表示任意 |
| **源IP****掩码** | mask_src_ip | VARCHAR2(40) | N | IPv4:255.255.255.255和0.0.0.0表示无掩码，即精确IP匹配； IPv6：ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff 和::（两个半角冒号）表示无掩码，即精确匹配。非0掩码值必须是2的指数幂，下同 |
| **源端口** | src_port | VARCHAR2(6) | N | 0值表示任意 |
| **源端口掩码** | mask_src_port | VARCHAR2(6) | N | 65535表示无掩码，即精确端口匹配，0表示任意 |
| **目的IP** | dst_ip | VARCHAR2(40) | N | 0.0.0.0值表示任意 |
| **目的IP****掩码** | mask_dst_ip | VARCHAR2(40) | N | 同源IP掩码 |
| **目的端口** | dst_port | VARCHAR2(6) | N | 0值表示任意 |
| **目的端口掩码** | mask_dst_port | VARCHAR2(6) | N | 同源端口掩码 |
| **协议(tcp/udp)** | protocol | INT | N | 6表示TCP，17表示UDP，无限制默认为0。可自解释，取值范围为0~65535。 对于多层嵌套地址的匹配需求，如第二层为UDP协议的某个IPv4地址，可以用protocol的高8位表示嵌套层数，低八位表示协议类型. |
| **方向** | direction | INT | N | 0无方向（双向），1有方向（单向） |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
### 数值类域配置
用以判断数值是否位于某个区间。
表 6数值类表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| ---------------- | ------------ | -------- | -------- | ---------------------------------------------------------- |
| **域配置****ID** | region_id | INT | N | 由配置汇总表中统一id的不同域拆分而成，**主键**，各表不重复 |
| **分组ID** | group_id | INT | N | 分组关系表中的group_id |
| **数值下界** | low_boundary | INT | N | 数据区间的下界，包含lb，取值范围0~2^32-1 lb<=ub |
| **数值上界** | up_boundary | INT | N | 数据区间的上界，包含ub，取值范围0~2^32-1 |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
### 文件摘要类域配置（Todo）
用以描述需要使用摘要进行比对的规则。摘要生成digest_gen工具参见xx节。
表 8摘要类表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| ---------------- | ------------ | ------------- | -------- | ---------------------------------------------------------- |
| **域配置****ID** | region_id | INT | N | 由配置汇总表中统一id的不同域拆分而成，**主键**，各表不重复 |
| **分组ID** | group_id | INT | N | 分组关系表中的group_id |
| **原始长度** | raw_len | NUMBER | N | 生成摘要的原始文件长度 |
| **文件摘要** | digest | VARCHAR(4000) | N | 使用专用工具生成的摘要字符串 |
| **匹配置信度** | cfds_level | INT | N | 匹配置信度，1～10 |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
### Group To Group Relation 分组关系表
描述分组与分组间的关系。
表 12分组关系表格式
| 名称 | 字段名称 | 类型 | 空值 | **约束** |
| ---------- | ----------------- | ----- | ---- | ------------------------------ |
| 分组ID | group_id | INT64 | N | 引用自各域配置表的group_id字段 |
| 上级分组ID | superior_group_id | INT64 | N | |
| 排除标志位 | is_exlude | Bool | N | |
| 有效标志 | is_valid | Bool | N | 0无效，1有效 |
## Compile Group Relation 分组编译表
描述分组与编译之间的关系。
Maat 2.8后不再兼容无分组模式。
\0. 表 13配置分组表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| ------------------ | ------------- | ------------- | -------- | ------------------------------------------------------------ |
| **分组****ID** | group_id | INT | N | 引用自各域配置表的group_id字段 |
| **编译配置ID** | compile_id | INT | N | 编译配置ID |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
| **非运算标志位** | not_flag | INT | N | “非关系”分组标识，0：否，1：是。当parent是编译配置（parent_id=0）时有效。 |
| **分组所属虚拟表** | virtual_table | VARCHAR2(256) | N | 默认为”null”。 |
| **子句序号** | Nth_clause | INT | N | group所属的合取范式（编译配置）中子句的编号，从0到7，相同子句ID的group在分组中是“或”关系。 |
注意：若该表中某group_id不包含有效的域配置时，必须标记为无效，否则会导致包含该分组的编译配置无法命中。
析取与合取：[https://baike.baidu.com/item/%E6%9E%90%E5%8F%96](https://baike.baidu.com/item/析取)
## Compile 配置编译
描述每一条具体策略的业务信息，一个Maat示例下可以有多个不同名称的编译配置表。
表 14配置编译表格式
| **名称** | **字段名称** | **类型** | **空值** | **约束** |
| ----------------------------- | ---------------- | -------------------- | -------- | ------------------------------------------------------------ |
| **编译配置****ID** | compile_id | INT | N | 通常有数据库中的SEQ类型生成，主键，本表不重复，被配置分组表引用 |
| **业务****ID** | service | INT | N | 如URL关键字业务，User Agent业务等 |
| **动作** | action | VARCHAR(1) | N | 推荐定义:0:阻断，1：监测，2：白名单 应用可自解释 |
| **是否黑名单** | do_blacklist | VARCHAR(1) | N | 0:不需要，1:需要 应用可自解释 |
| **是否生成日志** | do_log | VARCHAR(1) | N | 0:不需要，1:需要，默认为1 应用可自解释 |
| **生效范围****/****配置标签** | tags | VARCHAR2(1024) | N | 默认值为0，表示无标签；分区域下发参见本文档“配置生效标签”一节。 |
| **用户自定义域** | user_region | VARCHAR2(8192) | N | 默认值为0 应用可自解释 |
| **有效标志** | is_valid | INT | N | 0无效，1有效 |
| **包含子句数量** | clause_num | INT | N | 包含不超过8个子句，用以克服多个表中域配置或分组配置不能原子下发的问题 |
| **执行顺序** | evaluation_order | DOUBLE[[1\]](#_ftn1) | N | 默认值为0，执行顺序在最后；非0时，执行顺序号越大，执行顺序越靠后；详见6.7 |
[[1\]](#_ftnref1) 使用双精度浮点数而不是整数表示执行顺序，可以保证一条编译配置执行顺序的修改不会影响其它配置。例如：有顺序执行的4条编译配置a、b、c、d，将d的执行顺序调整到b之前，修改d.exec_seq = (a.exec_seq + b.exec_seq) /2。配置生成侧可以周期性的重置exec_seq为顺序整数，以减少小数点位数。
## Plugin 回调类配置
这类配置没有固定格式，由业务自己定义，用于非扫描类配置或不需要做统一扫描的配置。注册回调函数后，配置更新时Maat负责在会将表ID和表行作为参数回调，注册的方式有两种：
1. 回调表注册函数Maat_table_callback_register，支持注册最多8组回调函数，出于节省内存的考虑，只有第一个注册的回调函数能够得到全量配置，后继注册函数无法得到第一次注册到本次注册之间更新的内容。
2. 回调表Extra Data注册函数Maat_plugin_EX_register，仅支持注册1组回调函数。
### Plain Plugin
使用字符串做为Key的简单KV更新、查询。
### IP Plugin
类似回调类配置，其Key为IP范围。
### FQDN Plugin
按照域名层级“.”扫描输入的字符串。
返回结果顺序：
1、按照命中规则的长度递减排序；
2、相同长度的规则（即重复的规则），后插入的规则先返回（因为实现时后插入的规则放在在哈希桶的前面）；
例如，对于如下4条规则（假设均为后缀匹配）：
1. example.com.cn
2. com.cn
3. example.com.cn
4. cn
5. ample.com.cn
如果输入example.com.cn，则返回结果顺序为：3，1，2，4。规则5中的ample不是域名层级的一部分，不返回。
### Boolean Expression Plugin
按照布尔表达式扫描输入的整数数组，如[100,1000,2,3]。
布尔表达式规则为“&”分隔的数字，例如“1&2&1000”。
## Foreign Files 内容外键
回调类配置中，特定字段可以指向一个外部内容，目前支持指向Redis中的一个key。
回调表的外键列，必须具备”redis://”前缀。存放在Redis中的外键内容，其Key必须具备”__FILE_”前缀。当Key为“null”时，表示该文件为空。
例如，原始文件为./testdata/mesa_logo.jpg，计算其MD5值后，得到redis的外键__FILE_795700c2e31f7de71a01e8350cf18525，写入回调表后的格式如下：
```
14 ./testdata/digest_test.data redis://__FILE_795700c2e31f7de71a01e8350cf18525 1
```
​ 回调表中的一行最多允许8个外键，外键内容可以通过Maat_cmd_set_file函数设置。
​ Maat在通知回调表前会将外键拉取到本地文件，并将外键列替换为本地文件路径。
​ 内容外键的声明方法，参见本文档-配置表描述文件一节。
## 配置生效标签
通过将Maat接受标签与配置标签的匹配，实现有选择的配置加载。其中配置标签是一个标签数组的集合，记为”tag_sets”，Maat接受标签是标签数组，记为”tags”。
配置标签是指存放在编译配置或分组配置上的标签，标识着该配置在那些Maat实例中生效。由多个tag_set构成，1个set内的多个tag是与的关系，1个tag的多个值是或的关系，值内部用”/”表示层次结构。
格式为一个不含回车、空格的JSON，结构为:
若干tag集合（数组）->tag集合（数组）->若干tag（数组）->{tag名称，tag值（数组）}
例如：
```json
{"tag_sets":[[{"tag":"location","value":["北京/朝阳/华严北里","上海/浦东/陆家嘴"]},{"tag":"isp","value":["电信","移动"]}],[{"tag":"location","value":["北京"]},{"tag":"isp","value":["联通"]}]]}
```
上例有2个tag分组：
- 分组1：（"北京/朝阳/华严北里"∨"上海/浦东/陆家嘴"）∧("电信"∨"移动")
- 分组2：（"北京"∧"联通"）
- 分组1∨分组2
Maat实例初始化时，可以设置自身的标签信息，称为接受标签。格式为同样要求的JSON，内有多个标签，加载配置时匹配实例标签和配置的生效范围标签。例如：
```json
{"tags":[{"tag":"location","value":"北京/朝阳/华严北里/甲22号”},{"tag":"isp","value":"电信"}]}
```
该Maat实例在加载以下标签时：
1. {"tag_sets":[[{"tag":"location","value":["北京/朝阳"]},{"tag":"isp","value":["联通","移动"]}]}，不被接受，因为isp tag不匹配。
2. {"tag_sets":[[{"tag":"location","value":["北京"]}]]}，接受，空tag在任意tag上生效。
对于Maat实例接受标签和配置标签name不匹配的异常情况，Maat遵循不违背即接受的原则，全部接受。
- Maat实例的接受标签是配置标签的真子集时，即tags 属于tag_set，Maat会接受该配置。
- 例如：接受标签为：{"tags":[{"tag":"location","value":"北京”}]} ，配置标签为：{"tags":[{"tag":"location","value":"北京/朝阳”},{"tag":"isp","value":"电信"}]} ，Maat会接受该配置，因为实例仅要求”location”满足“北京”，未对“isp”标签的值作出要求。
- 配置标签是Maat实例接受标签的真子集时，即tag_sets属于tags，Maat会接受该配置。
- 例如：接受标签为：{"tags":[{"tag":"location","value":"北京/朝阳”},{"tag":"isp","value":"电信"}]}，配置标签为：{"tags":[{"tag":"location","value":"北京”}]}，Maat会接受该配置。配置没有“isp”标签，并未违背Maat接受条件。
- Maat实例的接受标签和配置标签的交集为空时，Maat会接受该配置。
当配置标签为“0”或“{}”时，无论Maat实例的接受标签是什么都会接受，这一特性用于向前兼容未设置标签的配置。
## Virtual Table 虚拟表
虚拟一个配置表，其内容为特定物理域配置表的视图。实践中，通常采用网络流量的属性作为虚拟表名，如HTTP_HOST、SSL_SNI等。一个虚拟表可以建立在多个不同类型的物理表之上，但不允许建立在其它虚拟表上。
虚拟表以分组为单位引用实体表中的域配置，引用关系在分组关系表中描述。一个分组可被同一个编译配置的不同虚拟表引用。例如下表，一个关键字的分组keyword_group_1，被一条compile_1的Request Body和Response Body两个虚拟表引用。
| **分组ID** | **父ID** | **有效标志** | **非运算标志位** | **父节点类型** | **分组所属虚拟表** |
| ------------------- | --------- | ------------ | ---------------- | -------------- | ------------------ |
| **keyword_group_1** | compile_1 | 1 | 0 | 0 | REQUEST_BODY |
| **keyword_group_1** | compile_1 | 1 | 0 | 0 | RESPONSE_BODY |
## Conjunction Table 连接表
表名不同，但table id相同的表。旨在数据库表文件和MAAT API之间提供一个虚拟层，通过API调用一次扫描，即可扫描多张同类配置表。
使用方法：
1. 在配置表描述文件中，将需要连接的多个表共用一个table_id；
2. 通过Maat_table_register注册被连接表中的任意一个表名，使用该id进行扫描。
被连接的配置表的各项属性以在配置表描述文件（table_info.conf）中第一个出现的同ID描述行为准，同一table_id下最多支持8个配置表。
支持所有类型表的连接，包括各类域配置、回调类配置。配置分组和配置编译的连接没有意义。
Reference in New Issue Copy Permalink