Log masking plug-ins (for dedicated instances only)-API Gateway(API Gateway)-阿里云帮助中心

1. Prerequisites

A dedicated instance is used.
API Gateway is configured to record logs to Simple Log Service.
Logging of HTTP requests and responses is enabled for the API group in which the API that is to be bound the log masking plug-in resides. For more information, see Configure the logging of HTTP requests and responses.

2. Overview

A log masking plugin contains a series of masking rules. API Gateway applies these rules before delivering data to Simple Log Service. Each rule has the following attributes:

Name: Required. The name of the rule, used to differentiate between rules.
Policy: Required. The masking pattern. Supports full masking and partial masking to handle different types of sensitive information.
Location: Required. Specifies where the data to be masked is located in the request or response, such as Header, Query, Token, or Body.
Parameters: Required when Location is set to Header, Query, or Token. Specifies the parameter names to mask.
MatchMode: Required when Location is set to Body. A pattern used to match sensitive information, such as numbers of a specific length, email addresses, or ID numbers. When MatchMode is used, you do not need to specify Parameters.

3. Configurations

You can customize the Name and Parameters values in a masking rule. Other attributes must use preset values. Otherwise, the rule may not take effect.

The Policy attribute provides the following options:

ALL (default): All characters are masked. For example, 123456 is masked as ******.
KEEP_LEFT: Keeps the N leftmost characters and masks the rest. This option requires an additional integer parameter that specifies the number of characters to keep. For example, if you configure KEEP_LEFT:3, the string 123456 is masked as 123***.
KEEP_RIGHT: Keeps the N rightmost characters and masks the rest. This option requires an additional integer parameter that specifies the number of characters to keep. For example, if you configure KEEP_RIGHT:3, the string 123456 is masked as ***456.
KEEP_CENTER: Keeps M characters starting from the Nth character (0-indexed) and masks the rest. This option requires two additional integer parameters for the starting position and length, separated by a comma. For example, if you configure KEEP_CENTER:2,2, the string 123456 is masked as **34**.

The Location attribute provides the following options:

REQUEST_HEADER: The request Header. Must be used with Parameters.
REQUEST_QUERY: The request Query. Must be used with Parameters.
REQUEST_TOKEN: The request Token, specifically the claims within a JSON Web Token (JWT). Must be used with Parameters.
REQUEST_BODY: The request Body. Must be used with MatchMode.
RESPONSE_HEADER: The response Header. Must be used with Parameters.
RESPONSE_BODY: The response Body. Must be used with MatchMode.

The MatchMode attribute provides the following options:

D: Matches decimal digits. This option requires an additional integer parameter that specifies the number of digits to match. For example, D:11 matches any sequence of 11 digits.
HEX: Matches hexadecimal digits. Letters are case-insensitive. This option requires an additional integer parameter that specifies the number of characters to match. For example, HEX:16 matches any 16-character hexadecimal sequence.
C: Matches a string of only letters. Letters are case-insensitive. This option requires an additional integer parameter that specifies the number of characters to match. For example, C:18 matches any 18-character alphabetic sequence.
DC: Matches a combination of letters and digits. Letters are case-insensitive. This option requires an additional integer parameter that specifies the number of characters to match. For example, DC:15 matches any 15-character alphanumeric sequence.
EMAIL: Matches email addresses.
IDCARD: Matches ID card numbers.

4. Configuration examples

You can configure a log masking plugin in JSON or YAML format. The two formats share the same schema and can be converted to each other. The following template is in YAML format:

---
rules:
  -name: maskRequestQuery        # The rule name.
    location: "REQUEST_QUERY"     # The location of the parameters to be masked.
    parameters:                   # The parameters to be masked.
     - userid
     - name
    policy: "KEEP_LEFT:4"         # The masking policy. All characters are masked except the four left-most characters.
  - name: maskRequestHeader       # The rule name.
    location: "REQUEST_HEADER"    # The location of the parameters to be masked.
    parameters:                   # The parameters to be masked.
     - userid
     - name
    policy: "KEEP_CENTER:4,5"     # The masking policy. All characters are masked except for the five characters after the four left-most characters.
  - name: maskRequestBody         # The rule name.
    location: "REQUEST_BODY"      # The location to be masked.
    matchMode: HEX:10             # The matching mode. 10-character hexadecimal strings are matched.
    policy: "ALL"                 # The masking policy. All characters are masked.
  - name: maskResponseBody        # The rule name.
    location: "RESPONSE_BODY"     # The location to be masked.
    matchMode: EMAIL              # The matching mode. Email addresses are matched.
    policy: "KEEP_RIGHT:7"        # The masking policy. All characters except for the seven right-most characters are masked.

The preceding example configures the following rules:

maskRequestQuery: Masks the userid and name parameters in the request Query by keeping the four leftmost characters.
maskRequestHeader: Masks the userid and name parameters in the request Header by keeping five characters starting from the fourth character (0-indexed).
maskRequestBody: Masks 10-character hexadecimal numbers in the request Body by masking all characters.
maskResponseBody: Masks all email addresses in the response body. All characters except the seven rightmost characters are masked.

Important

If two configured rules conflict with each other, API Gateway applies both rules based on their sequence in the rule list.

5. Sample scenarios

The following snippet shows a sample HTTP request:

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"
}

The following snippet shows the corresponding HTTP response (idcard indicates ID numbers):

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 Mask parameters in the Header and Query sections of requests and responses

Mask the Authorization value in the Header section of the request. Mask all characters except for the five characters after the four left-most characters.
For name in the request Query, keep the two leftmost characters and mask the rest.

---
rules:
  - name: request_query           # The rule name.
    location: "REQUEST_QUERY"     # The location of the parameters to be masked.
    parameters:                   # The parameters to be masked.
     - name
    policy: "KEEP_LEFT:2"         # The masking policy. All characters except for the two left-most characters are masked.
  - name: request_header          # The rule name.
    location: "REQUEST_HEADER"    # The location of the parameters to be masked.
    parameters:                   # The parameters to be masked.
     - Authorization
    policy: "KEEP_CENTER:4,5"     # The masking policy. All characters except for the five characters after the four left-most characters are masked.

Check whether the rules take effect in logs:

requestHeaders: {"Authorization":"****cvisd******"}

requestQueryString: name=te**

5.2 Mask information in request and response bodies

Masks ID numbers in request and response bodies. All characters are masked.

Mask decimal numbers that are 10 characters in length. All characters except for the three right-most characters are masked.

YAML

---
rules:
  - name: request_body_IDCARD      # The rule name.
    location: "REQUEST_BODY"      # The location of the information to be masked. ID numbers are masked in request bodies.
    matchMode: IDCARD              # The matching mode. ID numbers are matched.
    policy: "ALL"                 # The masking policy. All characters are masked.  
  - name: request_body_D       # The rule name.
    location: "REQUEST_BODY"      # The location to be masked.
    matchMode: D:10             # The matching mode. 10-character decimal strings are matched.
    policy: "KEEP_RIGHT:3"        # The masking policy. All characters except for the three right-most characters are masked.    
  - name: response_body_IDCARD      # The rule name.
    location: "RESPONSE_BODY"      # The location of the information to be masked. ID numbers are masked in response bodies.
    matchMode: IDCARD              # The matching mode. ID numbers are matched.
    policy: "ALL"                 # The masking policy. All characters are masked.

Check whether the rules take effect in logs:

requestBody: { "idcard":"******************" "userid":"******075" }

responseBody: { "Body":"{\n"idcard":"******************"}" }

6. Limits

Log masking plugins are available only for dedicated instances.

The metadata of a single plugin cannot exceed 50 KB in size.

If the plugin does not take effect on a dedicated instance purchased before April 2, 2024, submit a ticket to upgrade the instance version.