Log masking plug-ins (for dedicated instances only) - API Gateway

API Gateway provides the log masking plug-in to mask sensitive information in HTTP requests and responses before sending the data to Simple Log Service for storage. You can configure your own masking rules to mask data in different locations, such as Header, Query, Token, and Body, in requests and responses.

1. Prerequisites

A dedicated instance is used.
API Gateway is integrated with Simple Log Service, and the necessary log storage resources are created in 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

You can configure a series of masking rules for a log masking plug-in to define how you want data to be masked. Then, API Gateway masks data based on the configured rules before delivering the data to Simple Log Service. A data masking rule contains the following attributes:

Name: the name of the rule. Rules are distinguished by their names. This attribute is required.
Policy: the masking mode, which may be full masking or partial masking. You can use this attribute to process different data types. This attribute is required.
Location: the location of the parameter that you want to mask, such as Header, Query, Token, or Body. This attribute is required.
Parameters: the parameters that you want to mask. This attribute is required when the Location value is Header, Query, or Token.
MatchMode: the regular expression that is used to match sensitive information. This attribute is required when the Location value is Body, in which case you do not need to specify the Parameters attribute. You can use this attribute to match numbers of a specific length, email addresses, and ID numbers.

3. Configurations

When you configure a masking rule, you can configure custom values for Name and Parameters. However, you must use the preset values for other attributes. Otherwise, the rule may not take effect. This section describes each attribute in detail:

The Policy attribute provides the following options:

ALL (default): All characters are masked. For example, 123456 is masked as ******.
KEEP_LEFT: All characters are masked except for the N left-most characters. If you use this option, you must configure an integer parameter to specify the N. For example, if you configure KEEP_LEFT:3, the string 123456 is masked as 123***.
KEEP_RIGHT: All characters are masked except for the N right-most characters. If you use this option, you must configure an integer parameter to specify the N. For example, if you configure KEEP_RIGHT:3, the string 123456 is masked as ***456.
KEEP_CENTER: All characters are masked except for the M characters after the N left-most characters. If you use this option, you must configure two integer parameters to specify the M and N. 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. This attribute is used together with Parameters.
REQUEST_QUERY: the request Query. This attribute is used together with Parameters.
REQUEST_TOKEN: the request Token or the Claims of the Jason Web Token (JWT). This attribute is used together with Parameters.
REQUEST_BODY: the request Body. This attribute is used together with MatchMode.
RESPONSE_HEADER: the response Header. This attribute is used together with Parameters.
RESPONSE_BODY: the response Body. This attribute is used together with MatchMode.

The MatchMode attribute provides the following options:

D: matches decimal numbers. If you use this option, you must configure an integer parameter to specify the number of characters to match. For example, if you configure D:11, any 11-digit decimal number is matched.
HEX: matches hexadecimal numbers. Letters are not case-sensitive. If you use this option, you must configure an integer parameter to specify the number of characters to match. For example, if you configure HEX:16, any 16-digit hexadecimal number is matched.
C: matches all-letter strings. Letters are not case-sensitive. If you use this option, you must configure an integer parameter to specify the number of characters to match. For example, if you configure C:18, any string of 18 letters is matched.
DC: matches strings of mixed letters and numbers. Letters are not case-sensitive. If you use this option, you must configure an integer parameter to specify the number of characters to match. For example, if you specify DC:15, any string of mixed letters and numbers that is 15 characters in length is matched.
EMAIL: matches email addresses.
IDCARD: matches ID card numbers.

4. Configuration examples

You can configure a log masking plug-in in JSON or YAML format. The two formats have the same schema and can be converted to each other by using a conversion tool. The following code provides a template 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 following items describe the rules configured in the preceding example:

maskRequestQuery: masks the values of the userid and name parameters in the Query section of a request. All characters except for the four left-most characters in a string are masked.
maskRequestHeader: masks the values of the userid and name parameters in the Header section of a request. All characters except for the five characters after the four left-most characters in a string are masked.
maskRequestBody: masks all hexadecimal numbers that are 10 characters in length in the request body. All characters in the numbers are masked.
maskResponseBody: masks all email addresses in the response body. All characters except for the seven right-most characters are masked in the email addresses.

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 code 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 code snippet shows a sample HTTP response (idcard indicates ID numbers) to the preceding request:

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.
Mask the name value in the Query section of the request. Mask all characters except for the two left-most characters.

---
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:

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:

6. Limits

Log masking plug-ins are provided only for dedicated instances.

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

If log masking plug-ins do not take effect in your dedicated instance that was purchased before April 02, 2024, submit a ticket to have your instance upgraded.