Cargue un esquema de API, como una especificación OpenAPI. ESA lo asocia automáticamente con sus API gestionadas, valida las solicitudes entrantes contra el esquema y aplica la acción configurada a las solicitudes no conformes.
Cómo funciona
La validación de esquemas se aplica a cualquier API gestionada dentro de la gestión de API de ESA.
-
Cuando una solicitud llega a un nodo de ESA, ESA comprueba si corresponde a una API gestionada:
Si no es así, ESA permite que la solicitud pase a otras funciones de seguridad.
Si corresponde, ESA asocia la solicitud con el esquema de API correspondiente.
-
ESA valida la solicitud contra el esquema:
Si la solicitud no es conforme, ESA aplica la acción configurada y registra el evento.
Si la solicitud es conforme, ESA permite su paso.
Configurar la validación de esquemas
Para usar la validación de esquemas, cargue un esquema y habilite la función.
En la consola de ESA, elija Websites y, a continuación, haga clic en el sitio web de destino en la columna Website.
En el panel de navegación izquierdo, elija .
En la página API Security, seleccione la pestaña Schema Validation y, a continuación, haga clic en Schema Validation Settings.
En la página de configuración, haga clic en Upload Schema para cargar su archivo de esquema personalizado.
ESA asocia automáticamente sus API gestionadas con las definiciones del esquema cargado. Después de revisar las coincidencias, haga clic en OK.
Una vez cargado el esquema, configure una acción predeterminada para las solicitudes no conformes. Se recomienda comenzar con la acción Monitor. A continuación, habilite el interruptor Status.
Regrese a la pestaña Schema Validation para consultar los resultados de la validación de esquemas.
Analizar solicitudes no conformes
Una vez configurada la validación de esquemas, ESA supervisa continuamente las solicitudes de API. En la pestaña Schema Validation, haga clic en el ícono de filtro 
de la barra de herramientas de la lista de API y seleccione un esquema para filtrar la lista. La columna Non-compliant requests muestra el recuento de las últimas 24 horas.
Las solicitudes no conformes pueden deberse a los siguientes problemas:
Errores del lado del cliente: los clientes legítimos pueden enviar solicitudes mal formadas. Por ejemplo, un formato de parámetro incorrecto (datos de formulario en lugar de JSON), parámetros obligatorios faltantes o discrepancias de tipo (una cadena de texto en un campo booleano). Revise el diseño de su frontend y agregue validaciones de entrada y mensajes de error para evitar estos problemas.
Ataques maliciosos: los atacantes suelen enviar solicitudes mal formadas para buscar vulnerabilidades de inyección o de fuerza bruta. Un aumento repentino de solicitudes no conformes puede indicar un ataque en curso. Si sospecha de un ataque, change the action a Block y configure reglas WAF más estrictas.
Analizar los detalles de las solicitudes
Para encontrar la causa raíz de las solicitudes no conformes, inspeccione los registros de muestra en Events o Security Analytics.
Primero, identifique una API que tenga un número inusual de solicitudes no conformes.
-
Elija la función de registro adecuada según la acción configurada:
La acción es None: dado que estas solicitudes no desencadenan ninguna acción de seguridad, analícelas en Security Analytics.
La acción es Monitor o Block: como estas solicitudes sí desencadenan una acción de seguridad, encontrará los registros relacionados más fácilmente en Events.
-
Esta sección utiliza Events como ejemplo. En el panel de navegación izquierdo, elija .
Para usar Security Analytics, elija en el panel de navegación izquierdo.
En la página Events, desplácese hacia abajo hasta el área Sampling Logs. Filtre los registros que coincidan con las reglas de API Security. Haga clic en el ícono de expansión
junto a una entrada de registro para consultar sus detalles y analizar la solicitud. También puede usar Real-time Log para un análisis más detallado de los registros de acceso.
Cambiar la acción
Configure una acción predeterminada para todas las API o establezca una acción específica para cada una.
-
Cambiar la acción predeterminada global: en la pestaña Schema Validation, haga clic en Change en la columna Default Action y seleccione una acción:
Block: bloquea la solicitud no conforme y registra el evento.
Monitor: permite el paso de la solicitud no conforme y registra el evento.
None: no ejecuta ninguna acción.
-
Configurar una acción para una API específica: en la lista de API de la pestaña Schema Validation, haga clic en Change Action para la API deseada y seleccione una acción:
Default: usa la acción predeterminada global.
Block: bloquea la solicitud no conforme y registra el evento.
Monitor: permite el paso de la solicitud no conforme y registra el evento.
-
None: no ejecuta ninguna acción.
Analizar API sin esquema
Después de cargar un archivo de esquema, las API que cumplen con él se vinculan automáticamente. En la pestaña Schema Validation, dentro de la columna APIs without Schema, haga clic en el botón Filter para consultar la lista de API sin esquema.
Sin un esquema, ESA no puede contar las solicitudes no conformes, lo que genera una posible brecha de seguridad. Una API podría carecer de esquema por las siguientes razones:
Omisión en el esquema: la API no se incluyó en el archivo de esquema cargado. Compruebe la ruta de la API, el host y el método HTTP; luego actualice y vuelva a cargar el archivo de esquema.
-
Diseño de API no estándar: la API no sigue las prácticas de diseño estándar, lo que impide que coincida con el esquema. Es posible que deba refactorizar la API. Entre los problemas comunes se incluyen:
Ruta no estándar: la ruta de la API es incorrecta. Por ejemplo, la entrada correcta de
pathses/users, pero está definida como/user.Uso incorrecto del método HTTP: el método no sigue las convenciones semánticas. Por ejemplo, usar el método
GETpara una acción destructiva como/users/delete/123en lugar deDELETE.Uso indebido de códigos de estado: el código de estado de la respuesta de la API es incorrecto. Por ejemplo, todas las respuestas devuelven
200 OKy el estado real se devuelve en el cuerpo de la respuesta, como{ "responses": "500" }.Estructura de E/S confusa: los datos de entrada o salida son incorrectos. Por ejemplo, un campo
emailque debería estar en la entrada se coloca por error en la salida.
Especificaciones del archivo de esquema
Tipo y tamaño
Los archivos de validación de esquemas deben tener el formato .yml, .yaml o .json. El tamaño máximo del archivo es de 58 KB. Si su archivo de esquema supera este límite, use el formato .json y comprima el archivo localmente antes de cargarlo.
Contenido del esquema
Versión
La validación de esquemas de ESA solo admite OpenAPI Specification (OAS) v3.0.x.
Campos
Campos obligatorios
openapi: la versión de la API, como3.0.0.info: metadatos sobre la API, como"version": "1.0.0".paths: debe contener como mínimo una ruta de API, como/api.-
servers: información sobre el host. Se admiten los siguientes subcampos:url: solo se admiten URL absolutas, comohttps://api.example.com.variables: ESA no admite variables de servidor. Los marcadores de posición de variables se ignoran durante el análisis sintáctico.
Campos opcionales
-
schema: la definición de la estructura de datos. Se admiten los siguientes tipos:int32
uint32
int64
uint64
float
double
boolean
email
reference: usa$refpara hacer referencia a un objeto predefinido. No se admiten referencias externas ni relativas.requestBody: define el cuerpo de la solicitud. Solo se admiten datos con uncontent-typedeapplication/json.
Ejemplo
A continuación se muestra un ejemplo de un archivo de esquema .json.
{
"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"
}
}
]
}
}
}
}