API de estatísticas de segurança

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A API Security Stats permite-lhe ver estatísticas relacionadas com abusos e bots 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 são frequentemente calculadas através de uma função de agregação, por exemplo, sum for message_count ou bot_traffic.
  • Estatísticas de séries cronológicas, que têm uma dimensão de tempo.
Nota: a deteção de bots tem um atraso de processamento de cerca de 15 a 20 minutos, em média.

Parâmetros em exemplos de chamadas API

As secções seguintes dão exemplos de chamadas da API que usam a API security stats. As chamadas da API contêm os seguintes parâmetros:

  • ORG: a sua organização.
  • ENV: o seu ambiente.
  • METRIC_i: uma métrica para a estatística. Consulte as métricas e as funções de agregação.
  • AGGREGATION_i: uma função de agregação para a 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 devolvidos numa única página.
  • time_range: o intervalo de tempo das estatísticas no formulário 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    where:

    • START_TIME é a hora de início do intervalo de tempo.
    • END_TIME é a hora de fim do intervalo de tempo.

    START_TIME e END_TIME têm o formato "YYYY-MM-DDT00:00:00Z".

    O intervalo de tempo pode ter, no máximo, 14 dias, e a data de início e a data de fim têm de estar nos últimos 365 dias.

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

Um pedido 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 da API.

Consulte as Limitações nas estatísticas de segurança para ver os números máximos de métricas, funções de agregação e dimensões que podem ser incluídos num pedido.

Segue-se um exemplo de um pedido 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 para ver descrições do pedido e da resposta.queryTabularStats

Exemplo: consultar estatísticas de segurança de séries cronológicas para um ambiente

As APIs de séries cronológicas devolvem estatísticas de séries cronológicas para as métricas escolhidas, agrupadas pela dimensão escolhida.

A seguinte chamada invoca estatísticas de séries cronológicas para o tráfego de bots agrupado por proxy de API. Como existem 4 proxies, isto gera 4 sequências de pontos de séries cronológicas. A ordem dos pontos de cada linha corresponde ao índice correspondente no campo das colunas.

Segue-se um pedido de exemplo:

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 da API.

Consulte a página de referência para ver descrições do pedido e da resposta.queryTabularStats

Exemplo: consultar detalhes de incidentes para deteção de abuso

O exemplo seguinte consulta os detalhes de um incidente para a deteção de abuso da API Advanced Security. A chamada devolve detalhes sobre a quantidade de bots para a app do programador 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 da API.

Isto devolve uma resposta semelhante à 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 para ver descrições do pedido e da resposta.queryTabularStats

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

A tabela seguinte descreve as métricas e as 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 detetados em intervalos de 1 minuto. count_distinct
bot_first_detected Data e hora em que o bot foi detetado pela primeira vez. Disponível apenas através da API. min
bot_last_detected Data e hora da última deteção do bot. Disponível apenas através da API. max
bot_traffic O número de mensagens de endereços IP de bots detetados em intervalos de um minuto. sum
message_count

O número total de chamadas de API processadas pelo Apigee em intervalos de um minuto.

Nota: message_count não pode ser usada 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 de dados relacionados. A tabela seguinte 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 deteção de segurança. bot_reason consiste no subconjunto das regras de deteção que corresponderam ao padrão de tráfego do bot.
incident_id (pré-visualização) O UUID de um incidente de segurança, que é devolvido por uma chamada à API Incidents. Consulte Exemplo: obter detalhes ou um incidente específico.
security_action A ação de segurança. Os valores possíveis são ALLOW, DENY ou FLAG.
security_action_name O nome da ação de segurança.
security_action_headers Cabeçalhos que pode usar para consultar uma ação de segurança de flag.

Nota: bot_reason e incident_id só funcionam 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 suporta as 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
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

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

A API de estatísticas de segurança (tabular e de séries cronológicas) tem os seguintes limites:

  • Tamanho máximo da página: 14400
  • Máximo de 10 dimensões de séries cronológicas
  • Máximo de 15 dimensões de estatísticas tabulares
  • Máximo de 5 agregações de métricas.
  • Máximo de 5 agregações de métricas de intervalos temporais
  • Intervalo de tempo: a duração pode ser de, no máximo, 14 dias, e a data de início e a data de fim têm de estar nos últimos 365 dias.
  • Não é possível usar as dimensões incident_id e bot_reason com as métricas message_count ou response_size.

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

Tanto a API de estatísticas de segurança como a API de relatórios de segurança devolvem estatísticas de segurança relacionadas com abusos e bots, mas têm as seguintes diferenças:

  • A API de estatísticas de segurança foi concebida para ver estatísticas sobre o tráfego recente da API. Os dados da API de estatísticas de segurança só remontam a 14 dias, mas pode ver as estatísticas imediatamente quando envia um pedido.

    As estatísticas de segurança também são apresentadas na vista Métricas de abuso na IU do Apigee.

  • A API de relatórios de segurança foi concebida para ver estatísticas de operações de longa duração. Para usar a API de classificações de segurança, envia uma tarefa e vê os resultados apenas quando a tarefa estiver concluída. Os dados da API de pontuações de segurança remontam a um ano.