Implementando Segurança com Validação de Esquema de API

Visão Geral

A validação de esquema de API garante que todos os dados trocados através de APIs estejam em conformidade com uma estrutura predefinida, definida em documentos OpenAPI Specification (OAS) ou JSON Schema. Isso previne ataques de injeção (SQLi, XSS, XXE), bloqueia atribuição em massa rejeitando propriedades desconhecidas, impede vazamento de dados validando esquemas de resposta e garante segurança de tipo em todas as interações de API. A validação de esquema opera tanto no nível do gateway de API (aplicação em tempo de execução) quanto durante o desenvolvimento (segurança "shift-left").

Quando Usar

• Ao implantar ou configurar capacidades de segurança de validação de esquema de API em seu ambiente
• Ao estabelecer controles de segurança alinhados aos requisitos de conformidade
• Ao construir ou melhorar a arquitetura de segurança para este domínio
• Ao realizar avaliações de segurança que exigem esta implementação

Pré-requisitos

• OpenAPI Specification v3.0 ou v3.1 para todos os endpoints de API
• Gateway de API com suporte à validação de esquema (Cloudflare API Shield, Kong, AWS API Gateway)
• Compreensão de JSON Schema draft-07 ou posterior
• Ambiente de desenvolvimento com bibliotecas de validação OpenAPI
• Pipeline de CI/CD para testes automatizados de conformidade de esquema

Implementação Principal

Esquema OpenAPI com Restrições de Segurança

openapi: 3.1.0
info:
  title: API Segura de E-commerce
  version: 2.0.0
servers:
  - url: https://api.example.com/v2
    description: Produção (HTTPS forçado)
security:
  - OAuth2:
      - read:products
      - write:orders

paths:
  /products:
    post:
      operationId: createProduct
      security:
        - OAuth2: [write:products]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Produto criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /products/{productId}:
    get:
      operationId: getProduct
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

components:
  schemas:
    ProductCreate:
      type: object
      required: [name, price, category]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          pattern: '^[a-zA-Z0-9\s\-\.]+$'  # Sem caracteres especiais para prevenção de injeção
        description:
          type: string
          maxLength: 2000
          # Sanitizar entidades HTML
        price:
          type: number
          format: float
          minimum: 0.01
          maximum: 999999.99
          exclusiveMinimum: 0
        category:
          type: string
          enum: [electronics, clothing, food, furniture, other]
        tags:
          type: array
          items:
            type: string
            maxLength: 50
            pattern: '^[a-zA-Z0-9\-]+$'
          maxItems: 10
          uniqueItems: true
      additionalProperties: false  # CRÍTICO: Impede atribuição em massa

    Product:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        price:
          type: number
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
      additionalProperties: false  # Impede vazamento de dados de campos internos

    ValidationErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          enum: [VALIDATION_ERROR]
        message:
          type: string
          maxLength: 500
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              error:

…