Validação de conformidade de schema de API - Edge Security Acceleration: Central de Documentação do Alibaba Cloud

Faça upload de um schema de API, como uma especificação OpenAPI. O ESA associa o arquivo automaticamente às suas APIs gerenciadas, valida as solicitações recebidas em relação ao schema e aplica a ação configurada para requisições não conformes.

Como funciona

A validação de schema se aplica a qualquer API gerenciada no recurso de gerenciamento de APIs do ESA.

Quando uma solicitação chega a um nó do ESA, o serviço verifica se ela é destinada a uma API gerenciada:
- Caso negativo, o ESA permite que a solicitação prossiga para outros recursos de segurança.
- Caso positivo, o ESA correlaciona a solicitação com o schema de API correspondente.
O ESA valida a solicitação em relação ao schema:
- Se a solicitação for não conforme, o ESA aplica a ação configurada e registra o evento em log.
- Se a solicitação estiver em conformidade, o ESA permite sua passagem.

Configure validação de schema

Para usar a validação de schema, faça upload de um schema e ative o recurso.

No console do ESA, escolha Websites e clique em Website na coluna desejada.
No painel de navegação à esquerda, escolha Security > API Security.
Na página API Security, selecione a aba Schema Validation e clique em Schema Validation Settings.
Na página de configurações, clique em Upload Schema para enviar seu arquivo de schema personalizado.
O ESA associa automaticamente suas APIs gerenciadas às definições do schema enviado. Após revisar as associações, clique em OK.
Após o upload do schema, configure uma ação padrão para solicitações não conformes. Recomendamos começar com a ação Monitor. Em seguida, ative a chave Status.
Retorne à aba Schema Validation para visualizar os resultados da validação de schema.

Analisar solicitações não conformes

Depois que a validação de schema é configurada, o ESA monitora continuamente as solicitações de API. Na aba Schema Validation, clique em na barra de ferramentas da lista de APIs e selecione um schema para filtrar a lista. A coluna Non-compliant requests exibe a contagem das últimas 24 horas.

Solicitações não conformes podem ser causadas pelos seguintes problemas:

Erros no lado do cliente: Clientes legítimos podem enviar solicitações malformadas, como formato de parâmetro incorreto (por exemplo, dados de formulário em vez de JSON), ausência de parâmetros obrigatórios ou incompatibilidade de tipos (por exemplo, uma string em um campo booleano). Revise o design do seu frontend e adicione validação de entrada e mensagens de erro para evitar esses problemas.
Ataques maliciosos: Atacantes frequentemente enviam solicitações malformadas para sondar vulnerabilidades de injeção ou força bruta. Um pico repentino em solicitações não conformes pode indicar um ataque em andamento. Se você suspeitar de um ataque, altere a ação para Block e configure regras mais restritivas no WAF.

Analisar detalhes da solicitação

Para identificar a causa raiz das solicitações não conformes, inspecione os logs amostrados em Events ou Security Analytics.

Primeiro, identifique uma API que apresente um número incomum de solicitações não conformes.
Escolha o recurso de log apropriado com base na ação configurada:
- Ação definida como None: Como essas solicitações não acionam uma ação de segurança, analise-as no Security Analytics.
- Ação definida como Monitor ou Block: Visto que essas solicitações acionam uma ação de segurança, encontre os logs relacionados mais facilmente em Events.
Esta seção utiliza Events como exemplo. No painel de navegação à esquerda, escolha Security > Events.

Para usar o Security Analytics, escolha Security > Security Analytics no painel de navegação à esquerda.
Na página Events, role até a área Sampling Logs. Filtre por logs que correspondam às regras de API Security. Clique em ao lado de uma entrada de log para visualizar seus detalhes e analisar a solicitação. Use também o Real-time Log para uma análise mais detalhada dos logs de acesso.

Alterar ação

Configure uma ação padrão para todas as APIs ou defina uma ação específica para APIs individuais.

Alterar a ação padrão global: Na aba Schema Validation, clique em Change na coluna Default Action e selecione uma ação:
- Block: Bloqueia a solicitação não conforme e registra o evento.
- Monitor: Permite a passagem da solicitação não conforme e registra o evento.
- None: Nenhuma ação é executada.
Configure uma ação para uma API específica: Na lista de APIs na aba Schema Validation, clique em Change Action para a API desejada e selecione uma ação:
- Default: Utiliza a ação padrão global.
- Block: Bloqueia a solicitação não conforme e registra o evento.
- Monitor: Permite a passagem da solicitação não conforme e registra o evento.
- None: Nenhuma ação é executada.

Analisar APIs sem schema

Após o upload de um arquivo de schema, as APIs compatíveis são vinculadas automaticamente a ele. Na aba Schema Validation, na coluna APIs without Schema, clique em Filter para visualizar a lista de APIs sem schema.

Sem um schema, o ESA não consegue contabilizar solicitações não conformes, o que cria uma possível lacuna de segurança. Uma API pode não ter um schema pelos seguintes motivos:

Omissão no schema: A API não foi incluída no arquivo de schema enviado. Verifique o caminho da API, o host e o método HTTP; em seguida, atualize e envie novamente o arquivo de schema.
Design de API fora do padrão: A API não segue práticas padrão de design, o que impede a correspondência com o schema. Pode ser necessário refatorar a API. Problemas comuns incluem:
- Caminho fora do padrão: O caminho da API está incorreto. Por exemplo, a entrada correta em paths é /users, mas está definida como /user.
- Uso indevido de método HTTP: O método não segue convenções semânticas. Por exemplo, usar o método GET para uma ação destrutiva como /users/delete/123 em vez de DELETE.
- Abuso de código de status: O código de status da resposta da API está incorreto. Por exemplo, todas as respostas retornam 200 OK, e o status real é retornado no corpo da resposta, como { "responses": "500" }.
- Estrutura de I/O confusa: Os dados de entrada ou saída estão incorretos. Por exemplo, um campo email que deveria estar na entrada foi colocado equivocadamente na saída.

Especificações do arquivo de schema

Tipo e tamanho

Os arquivos de validação de schema devem estar no formato .yml, .yaml ou .json. O tamanho máximo do arquivo é de 58 KB. Se o seu arquivo de schema exceder esse limite, use o formato .json e compacte o arquivo localmente antes de fazer o upload.

Conteúdo do schema

Versão

A validação de schema do ESA suporta apenas a OpenAPI Specification (OAS) v3.0.x.

Campos

Campos obrigatórios

openapi: A versão da API, como 3.0.0.
info: Metadados sobre a API, como "version": "1.0.0".
paths: Deve conter pelo menos um caminho de API, como /api.
servers: Informações sobre o host. Os seguintes subcampos são suportados:
- url: Apenas URLs absolutas são suportadas, como https://api.example.com.
- variables: O ESA não suporta variáveis de servidor. Espaços reservados para variáveis são ignorados durante a análise.

Campos opcionais

schema: A definição da estrutura de dados. Os seguintes tipos são suportados:
- int32
- uint32
- int64
- uint64
- float
- double
- boolean
- email
reference: Usa $ref para referenciar um objeto predefinido. Referências externas ou relativas não são suportadas.
requestBody: Define o corpo da solicitação. Apenas dados com content-type igual a application/json são suportados.

Exemplo

A seguir, um exemplo de arquivo de schema .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"
                        }
                    }
                ]
            }
        }
    }
}