288 lines
21 KiB
Markdown
288 lines
21 KiB
Markdown
# 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个配置表。
|
||
|
||
支持所有类型表的连接，包括各类域配置、回调类配置。配置分组和配置编译的连接没有意义。 |