API schema compliance validation

Analyze non-compliant requests

After you configure schema validation, ESA continuously monitors API requests. On the Schema Validation tab, click the filter icon in the API list toolbar and select a schema to filter the list. ESA then displays the matching APIs, and the Non-compliant requests column shows the number of non-compliant requests from the last 24 hours.

Non-compliant requests can be caused by the following issues:

• Client-side errors: Legitimate clients may send malformed requests, such as an incorrect parameter format (for example, sending form data when JSON is required), missing required parameters, or type mismatches (for example, sending a string for a boolean field). If this happens, review your frontend design and add error detection, submission prompts, and similar safeguards.

• Malicious attacks: Attackers often send malformed requests to probe for vulnerabilities such as injection and brute-force attacks. A sudden spike in non-compliant requests can indicate an ongoing attack. If you suspect an attack, change the action to Block and configure stricter WAF rules.

Analyze APIs without a schema

After you successfully upload a schema file, APIs that conform to the schema are automatically bound to it. On the Schema Validation tab, in the APIs without Schema column, click the Filter button to view the list of APIs without a schema.

For APIs without a schema, ESA cannot count non-compliant requests, which creates a potential security gap. An API might not have a schema for the following reasons:

• Omission from the schema: The API was not included in your uploaded schema file. Check the API path, host, and HTTP method in the list, then update your schema file and upload it again.

• Non-standard API design: The discovered API does not follow standard design practices, which prevents it from matching your schema. You may need to refactor the API. Common issues include:

  • Non-standard path: The API path is incorrect. For example, the correct paths entry is /users, but it is defined as /user.

  • Misused HTTP method: The method does not follow semantic conventions. For example, using the GET method for a destructive action like /users/delete/123 instead of DELETE.

  • Status code abuse: The API response status code is incorrect. For example, all responses return 200 OK, and the actual status is returned in the response body, such as { "responses": "500" }.

  • Confusing I/O structure: The input or output data is incorrect. For example, an email field that should be in the input is mistakenly placed in the output.

Type and size

Schema validation files must be in .yml, .yaml, or .json format. The maximum file size is 58 KB. If your schema file is too large, you can use the .json format and compress the file locally before you upload it.

Schema content

Example

The following is an example of a .json schema file.

{
    "openapi": "3.0.0",
    "info": {
        "title": "example",
        "description": "example",
        "version": "1.0"
    },
    "servers": [
    {
      "url": "https://example1.aliyun.com",
      "description": "example1 url"
    },
    {
      "url": "https://example2.aliyun.com",
      "description": "example2 url"
    }
    ],
    "components": {
        "schemas": {
            "ParamsObject": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "value": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "value"
                ]
            }
        }
    },
    "paths": {
        "/example/{param1}": {
            "get": {
                "operationId": "getexampleById",
                "parameters": [
                    {
                        "name": "param1",
                        "in": "path",
                        "required": true,
                        "description": "id",
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    }
                ]
            }
        },
        "/api1": {
            "post": {
                "operationId": "post_api1",
                "summary": "post api1 request",
                "parameters": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ParamsObject"
                            }
                        }
                    }
                }
            },
            "get" :{
                "operationId": "get_api1",
                "summary": "get api1 request",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        }
    }
}