API de estatísticas de segurança

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A API de estatísticas de segurança permite visualizar estatísticas relacionadas a bots e abuso nos últimos 14 dias. Existem dois tipos de estatísticas de segurança:

  • Estatísticas tabulares, que não têm uma dimensão de tempo. As estatísticas tabulares costumam ser calculadas usando uma função de agregação. Por exemplo, sum for message_count ou bot_traffic.
  • Estatísticas de série temporal, que têm uma dimensão de tempo.
Observação:a detecção de bots tem um atraso de processamento de cerca de 15 a 20 minutos, em média.

Parâmetros em chamadas de API de exemplo

As seções a seguir mostram exemplos de chamadas de API que usam a API de estatísticas de segurança. As chamadas de API contêm os seguintes parâmetros:

  • ORG: sua organização.
  • ENV: seu ambiente.
  • METRIC_i: uma métrica da estatística. Consulte Métricas e funções de agregação.
  • AGGREGATION_i: uma função de agregação da métrica. Consulte a tabela abaixo.
  • DIMENSION_i: uma dimensão para agrupar os valores da estatística.
  • PAGE_SIZE: número máximo de subcomponentes retornados em uma única página.
  • time_range: o período das estatísticas no formato 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    em que:

    • START_TIME é o horário de início do período.
    • END_TIME é o horário de término do período.

    START_TIME e END_TIME estão no formato "YYYY-MM-DDT00:00:00Z".

    A duração do período pode ser de no máximo 14 dias, e as datas de início e término precisam estar nos últimos 365 dias.

Exemplo: consultar as estatísticas de segurança tabulares de um ambiente

Uma solicitação que consulta estatísticas tabulares tem o seguinte formato:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas de API.

Consulte Limitações das estatísticas de segurança para ver o número máximo de métricas, funções de agregação e dimensões que podem ser incluídas em uma solicitação.

Confira um exemplo de solicitação que consulta estatísticas tabulares:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte a página de referência queryTabularStats para conferir descrições da solicitação e da resposta.

Exemplo: consultar as estatísticas de segurança de série temporal de um ambiente

As APIs de série temporal retornam estatísticas de série temporal para as métricas escolhidas, agrupadas pela dimensão escolhida.

A chamada a seguir invoca estatísticas de série temporal para o tráfego de bots agrupado por proxy de API. Como há quatro proxies, isso produz quatro sequências de pontos de série temporal. A ordem dos pontos de cada linha corresponde ao índice respectivo no campo de colunas.

Confira um exemplo de solicitação:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas de API.

Consulte a página de referência queryTabularStats para conferir descrições da solicitação e da resposta.

Exemplo: consultar detalhes do incidente para detecção de abuso

No exemplo a seguir, consultamos os detalhes de um incidente para a Detecção de abuso da API Security avaçanda. A chamada retorna detalhes da contagem de bots do developer_app para um determinado incidente.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas de API.

Isso retorna uma resposta como a seguinte:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

Consulte a página de referência queryTabularStats para conferir descrições da solicitação e da resposta.

Métricas e funções de agregação

A tabela a seguir descreve as métricas e funções de agregação disponíveis na API de estatísticas de segurança:

Metric Descrição Aggregation function
bot O número de endereços IP distintos para bots detectados em intervalos de um minuto. count_distinct
bot_first_detected Data e hora em que o bot foi detectado pela primeira vez. Disponível apenas na API. min
bot_last_detected Data e hora em que o bot foi detectado pela última vez. Disponível apenas na API. max
bot_traffic O número de mensagens de endereços IP de bots detectados em intervalos de um minuto. sum
message_count

Número total de chamadas de API processadas pela Apigee em intervalos de um minuto.

Observação: não é possível usar message_count com outras métricas no mesmo relatório.

 sum
response_size Tamanho da resposta. average, max, min, sum

Dimensões

As dimensões permitem agrupar valores de métricas com base em subconjuntos relacionados dos dados. A tabela a seguir descreve as dimensões específicas dos Relatórios de segurança avançada da API:

Dimensão Descrição
bot_reason Pode ser qualquer combinação das regras de detecção de segurança. bot_reason consiste no subconjunto de regras de detecção a que o padrão de tráfego do bot corresponde.
incident_id (pré-lançamento) O UUID de um incidente de segurança, que é retornado por uma chamada para a API Incidents. Consulte Exemplo: Mais detalhes ou um incidente específico.
security_action A ação de segurança. Possivelmente, os valores são ALLOW, DENY ou FLAG.
security_action_name O nome da ação de segurança.
security_action_headers Cabeçalhos que podem ser usados para consultar uma ação de segurança da flag.

Observação: bot_reason e incident_id funcionam apenas com as seguintes métricas:

  • bot
  • bot_traffic
  • response_size

Além das dimensões descritas acima, a segurança avançada da API também oferece suporte às seguintes dimensões:

  • access_token
  • api_product
  • apiproxy
  • app_group_app
  • app_group_name
  • ax_edge_execution_fault_code
  • ax_geo_city
  • ax_geo_continent
  • ax_geo_country
  • ax_geo_region
  • ax_isp
  • ax_resolved_client_ip
  • ax_ua_agent_version
  • client_id
  • developer
  • developer_app
  • developer_email
  • environment
  • is_filtered_out
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

Limitações das estatísticas de segurança

A API de estatísticas de segurança (tabulares e de séries temporais) tem os seguintes limites:

  • Tamanho máximo da página: 14400.
  • Máximo de 10 dimensões de série temporal.
  • Máximo de 15 dimensões de estatísticas tabulares.
  • Máximo de cinco agregações de métricas.
  • Máximo de cinco agregações de métricas de série temporal
  • Período: a duração pode ser de no máximo 14 dias, e as datas de início e término precisam estar nos últimos 365 dias.
  • As dimensões incident_id e bot_reason não podem ser usadas com as métricas message_count ou response_size.
  • A dimensão is_filtered_out é compatível apenas com estatísticas tabulares e se aplica também a dados antigos.

Comparar as APIs de estatísticas de segurança e de relatórios de segurança

Tanto a API de estatísticas de segurança quanto a API de relatórios de segurança retornam estatísticas de segurança relacionadas a bots e abuso, mas têm as seguintes diferenças:

  • A API de estatísticas de segurança foi projetada para ver estatísticas de tráfego recente de APIs. Os dados da API de estatísticas de segurança voltam, no máximo, 14 dias, mas você pode visualizar as estatísticas imediatamente ao enviar uma solicitação.

    As estatísticas de segurança também são exibidas na visualização de métricas de abuso na IU da Apigee.

  • A API de relatórios de segurança foi projetada para visualizar estatísticas de operações de longa duração. Para usar a API de pontuações de segurança, envie um job e visualize os resultados somente quando o job for concluído. Os dados da API de pontuação de segurança voltam, no máximo, um ano.