日誌脫敏外掛程式（僅專享執行個體） - API Gateway

日誌脫敏外掛程式用於將HTTP請求和響應資料輸出至SLS日誌系統前對敏感資訊進行脫敏處理，以防止資料泄露的風險。可以配置特定的脫敏策略，應用於請求和響應的不同位置，如Header、Query、Token以及Body等。

1. 前提條件

專享執行個體。
API Gateway已配置記錄SLS日誌。
外掛程式綁定的API，所屬分組已配置記錄HTTP請求應答日誌。

2. 概述

在日誌脫敏外掛程式中，您可以配置一系列脫敏規則（Rule）來控制日誌資料的脫敏過程，API Gateway將根據您提供的規則列表，按順序依次對資料進行脫敏處理。脫敏規則包含如下屬性：

名稱（Name）：必填，規則的名稱，用於區分不同的規則。
脫敏策略（Policy）：必填，定義資料脫敏的模式，Policy支援全脫敏、保留部分資料等模式，用於靈活處理不同類型的敏感資訊。
脫敏資料的位置（Location）：必填，指定需要脫敏的資料位元於請求或響應的哪個位置，如Header、Query、Token以及Body等。
參數列表（Parameters）：指定需要脫敏的參數名稱，當Location為Header、Query或Token時必填。
匹配模式（MatchMode）：在Location為請求或響應的Body時必填，MatchMode定義了用於匹配敏感資訊的Regex，無需指定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 Gateway將根據您提供的規則列表，按順序依次對資料進行脫敏處理。

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之前購買的專享執行個體，如果不生效，需提交工單升級執行個體版本。