日志脱敏插件（仅专享实例）_API 网关(API Gateway)-阿里云帮助中心

日志脱敏插件用于将HTTP请求和响应数据输出至SLS日志系统前对敏感信息进行脱敏处理，以防止数据泄露的风险。可以配置特定的脱敏策略，应用于请求和响应的不同位置，如Header、Query、Token以及Body等。

1. 前提条件

专享实例。
API网关已配置记录sls日志。
插件绑定的API，所属分组已配置记录HTTP请求应答日志。

2. 概述

在日志脱敏插件中，您可以配置一系列脱敏规则（Rule）来控制日志数据的脱敏过程，API网关将根据您提供的规则列表，按顺序依次对数据进行脱敏处理。脱敏规则包含如下属性：

名称（Name）：必填，规则的名称，用于区分不同的规则；
脱敏策略（Policy）：必填，定义数据脱敏的模式，Policy支持全脱敏、保留部分数据等模式，用于灵活处理不同类型的敏感信息；
脱敏数据的位置（Location）：必填，指定需要脱敏的数据位于请求或响应的哪个位置，如Header、Query、Token以及Body等；
参数列表（Parameters）：指定需要脱敏的参数名称，当Location为Header、Query或Token时必填；
匹配模式（MatchMode）：在Location为请求或响应的Body时必填，MatchMode定义了用于匹配敏感信息的正则表达式，无需指定Parameters。例如匹配特定长度的数字、邮箱地址、身份证号等。

3. 配置详情

在配置脱敏规则时，您可以自定义Name和Parameters的参数值，其它字段则需要根据预设的规则来配置，否则可能导致配置无效。以下是各个字段及可配置选项的详细说明：

Policy支持配置的选项包括：

ALL：默认配置，完全脱敏数据。例如123456被脱敏为******。
KEEP_LEFT：保留最左侧的N个字符，其余字符被加密，需额外配置一个整数参数来确定保留的长度。例如，配置KEEP_LEFT:3，则字符串123456会被脱敏为123***；
KEEP_RIGHT：保留最右侧的N个字符，其余的字符被加密，需额外配置一个整数参数来确定保留的长度。例如，配置KEEP_RIGHT:3，则数据123456会被脱敏为***456；
KEEP_CENTER：从第N个字符开始（以0为起始下标），共保留M个字符数据，其余的字符被加密，需额外配置两个整数参数来确定保留的起始位置和长度（两个参数之间以逗号间隔）。例如，配置KEEP_CENTER:2,2，则数据123456会被脱敏为**34***。

Location支持配置的选项包括：

REQUEST_HEADER：请求的Header，需配合Parameters使用；
REQUEST_QUERY：请求的Query，需配合Parameters使用；
REQUEST_TOKEN：请求的Token，即JWT Token的Claims，需配合Parameters使用；
REQUEST_BODY：请求的Body，需配合MatchMode使用；
RESPONSE_HEADER：响应的Header，需配合Parameters使用；
RESPONSE_BODY：响应的Body，需配合MatchMode使用。

MatchMode支持配置的选项包括：

D：匹配十进制数字，需额外配置一个整数参数来确定匹配的位数。例如，D:11将匹配任意11位的数字序列；
HEX：匹配十六进制数字，字母不区分大小写，需额外配置一个整数参数来确定匹配的位数。例如，HEX:16将匹配16位长度的十六进制序列；
C：匹配纯字母字符串，字母不区分大小写，需额外配置一个整数参数来确定匹配的位数。例如，C:18将匹配任意18位的字母序列；
DC：匹配字母和数字的组合，字母不区分大小写，需额外配置一个整数参数来确定匹配的位数。例如DC:15将匹配任意15位字母数字组合；
EMAIL：匹配电子邮箱地址；
IDCARD：匹配居民身份证号码。

4. 配置示例

可以选择JSON或YAML格式来配置您的插件，两种格式的Schema相同，可以搜索yaml to json转换工具来进行配置格式的转换，YAML格式的模板如下：

---
rules:
  - name: maskRequestQuery        # Rule名称
    location: "REQUEST_QUERY"     # 需要脱敏的位置
    parameters:                   # 需要脱敏的参数
     - userid
     - name
    policy: "KEEP_LEFT:4"         # 脱敏策略，保留最左侧的4个字符，其余字符被隐藏
  - name: maskRequestHeader       # Rule名称
    location: "REQUEST_HEADER"    # 需要脱敏的位置
    parameters:                   # 需要脱敏的参数
     - userid
     - name
    policy: "KEEP_CENTER:4,5"     # 脱敏策略，从左起第4个字符开始（下标从0开始），共保留5个字符，其余字符被隐藏
  - name: maskRequestBody         # Rule名称
    location: "REQUEST_BODY"      # 需要脱敏的位置
    matchMode: HEX:10             # 脱敏模式，此处为10位十六进制数
    policy: "ALL"                 # 脱敏策略，隐藏所有字段
  - name: maskResponseBody        # Rule名称
    location: "RESPONSE_BODY"     # 需要脱敏的位置
    matchMode: EMAIL              # 脱敏模式，此处为邮箱地址
    policy: "KEEP_RIGHT:7"        # 脱敏策略，保留最右侧的7个字符，其余字符被隐藏

上述配置中各个Rule的规则含义如下：

maskRequestQuery：对Request Query中的参数userid和name进行加密，加密策略为保留最左侧的4个字符；
maskRequestHeader：对Request Header中的参数userid和name进行加密，加密策略为保留第4到第8个字符（下标从0开始）；
maskRequestBody：对Request Body中的10位十六进制数进行加密，加密策略为隐藏所有字符；
maskResponseBody：对Response Body中的邮箱信息进行加密，加密策略为保留最右侧的7个字符。

重要

当配置的脱敏策略有冲突时，API网关将根据您提供的规则列表，按顺序依次对数据进行脱敏处理。

5. 应用场景

HTTP请求为：

POST /sls?name=test HTTP/1.1
Accept-Encoding: gzip,deflate
X-Ca-Stage: RELEASE
X-Ca-Timestamp: 1713423308449
User-Agent: Apache-HttpClient/4.5.6 (Java/1.8.0_172)
Content-MD5: 9QxBgTbb7psVMovQUjXXXXX
X-Ca-Real-IP: 101.37.XX.XX
eagleeye-rpcid: 0.1
Authorization: sdhfcvisdhjnvkdf
X-Forwarded-Proto: http
x-ca-nonce: cb5e4526-b4e9-42f3-a365-a095f5c22ff9
Content-Length: 31
Content-Type: application/json
Host: eaa961f4c0184712bce440XXXX-cn-beijing.alicloudapi.com

{
	"Body":"{"idcard":"11000019900702XXXX"}"
        "userid":"3628756075"
}

HTTP应答如下，其中idcard为身份证号：

Response：
200
Date: Thu, 18 Apr 2024 06:55:08 GMT
Content-Type: application/oct-stream
Content-Length: 854
Connection: keep-alive
X-Ca-Request-Id: 5FF51156-536B-4541-BED0-46A0C4D6929B
Content-Disposition: attachment; filename=ApiResponseForInnerDomain

{
	"Body":"{"idcard":"11000019900702XXXX"}"
        "userid":"3628756075"
}

5.1 对HTTP请求和响应的Header、Query位置参数进行日志脱敏

HTTP请求Header中的Authorization，从左起第4个字符开始，共保留5个字符，其余字符隐藏。
HTTP请求Query中的name，保留最左侧的2个字符，其余字符隐藏

---
rules:
  - name: request_query           # Rule名称
    location: "REQUEST_QUERY"     # 需要脱敏的位置
    parameters:                   # 需要脱敏的参数
     - name
    policy: "KEEP_LEFT:2"         # 脱敏策略，保留最左侧的2个字符，其余字符被隐藏
  - name: request_header          # Rule名称
    location: "REQUEST_HEADER"    # 需要脱敏的位置
    parameters:                   # 需要脱敏的参数
     - Authorization
    policy: "KEEP_CENTER:4,5"     # 脱敏策略，从左起第4个字符开始，共保留5个字符，其余字符被隐藏

查看日志：

5.2 对HTTP请求和响应的Body进行日志脱敏

对HTTP请求Body和响应Body中的身份证号进行日志完全脱敏。
HTTP请求中匹配任意10位的十进制数字时，只保留最右侧的3个字符，其余字符隐藏。

YAML

---
rules:
  - name: request_body_IDCARD      # Rule名称
    location: "REQUEST_BODY"      # 需要脱敏的位置，将请求Body中的身份证隐藏
    matchMode: IDCARD              # 脱敏模式，此处为身份证
    policy: "ALL"                 # 脱敏策略，隐藏所有字段  
  - name: request_body_D       # Rule名称
    location: "REQUEST_BODY"      # 需要脱敏的位置
    matchMode: D:10             # 脱敏模式，此处为10位十进制数
    policy: "KEEP_RIGHT:3"        # 脱敏策略，保留最右侧的3个字符，其余字符被隐藏    
  - name: response_body_IDCARD      # Rule名称
    location: "RESPONSE_BODY"      # 需要脱敏的位置，将应答Body中的身份证隐藏
    matchMode: IDCARD              # 脱敏模式，此处为身份证
    policy: "ALL"                 # 脱敏策略，隐藏所有字段

查看日志：

6. 使用限制

日志脱敏插件仅适用于专享实例。

插件元数据的大小限制为50KB。

2024-04-02号之前购买的专享实例，如果不生效，需提交工单升级实例版本。