API de estadísticas de seguridad

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

La API de estadísticas de seguridad te permite ver las estadísticas relacionadas con el abuso y los bots de los últimos 14 días. Existen dos tipos de estadísticas de seguridad:

  • Estadísticas tabulares, que no tienen una dimensión de tiempo. Las estadísticas tabulares a menudo se calculan mediante una función de agregación, por ejemplo, sum for message_count o bot_traffic.
  • Estadísticas de series temporales, que tienen una dimensión de tiempo.
Nota: La detección de bots tiene una demora de procesamiento de alrededor de 15 a 20 minutos en promedio.

Parámetros en llamadas a la API de ejemplo

En las siguientes secciones, se proporcionan ejemplos de llamadas a la API que usan la API de estadísticas de seguridad. Las llamadas a la API contienen los siguientes parámetros:

  • ORG: Tu organización
  • ENV: Tu entorno
  • METRIC_i: Una métrica para las estadísticas Consulta Métricas y funciones de agregación.
  • AGGREGATION_i: Una función de agregación para la métrica. Consulta la tabla que se encuentra a continuación
  • DIMENSION_i: Una dimensión para agrupar los valores de la estadística
  • PAGE_SIZE: Cantidad máxima de subcomponentes que se muestran en una sola página
  • time_range: el intervalo de tiempo para las estadísticas en el formulario
    "time_range": {
        "start_time": START_TIME,
        "end_time": END_TIME
    }

    donde:

    • START_TIME es la hora de inicio del intervalo de tiempo.
    • END_TIME es la hora de finalización del intervalo de tiempo.

    START_TIME y END_TIME tienen el formato "YYYY-MM-DDT00:00:00Z".

    La duración del intervalo de tiempo puede ser de 14 días como máximo, y la fecha de inicio y la de finalización deben estar dentro de los últimos 365 días.

Ejemplo: Consulta estadísticas de seguridad tabulares para un entorno

Una solicitud que consulta estadísticas tabulares tiene el siguiente 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
          }
        }'

Consulta Parámetros en llamadas a la API de ejemplo.

Consulta Limitaciones de las estadísticas de seguridad para ver la cantidad máxima de métricas, funciones de agregación y dimensiones que se pueden incluir en una solicitud.

Este es un ejemplo de una solicitud que consulta estadí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
          }
        }'

Consulta la página de referencia de queryTabularStats para obtener descripciones de la solicitud y la respuesta.

Ejemplo: Consulta estadísticas de seguridad de series temporales para un entorno

Las APIs de series temporales muestran estadísticas de series temporales para las métricas elegidas, agrupadas por la dimensión que se eligió.

La siguiente llamada invoca estadísticas de series temporales para el tráfico de bot agrupadas por proxy de API. Como hay cuatro proxies, se producen cuatro secuencias de puntos de serie temporal. El orden de los puntos de cada fila coincide con el índice correspondiente en el campo de columnas.

A continuación, se muestra una solicitud de ejemplo:

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
          }
        }'

Consulta Parámetros en llamadas a la API de ejemplo.

Consulta la página de referencia de queryTabularStats para obtener descripciones de la solicitud y la respuesta.

Ejemplo: Consulta detalles de incidentes para la detección de abuso

En el siguiente ejemplo, se consultan los detalles de un incidente para la detección de abuso de seguridad avanzada de APIs. La llamada muestra detalles sobre el recuento de bots para developer_app en un incidente determinado.

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
          }
        }'

Consulta Parámetros en llamadas a la API de ejemplo.

Esto devuelve una respuesta como la que se muestra a continuación:

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

Consulta la página de referencia de queryTabularStats para obtener descripciones de la solicitud y la respuesta.

Métricas y funciones de agregación

En la siguiente tabla, se describen las métricas y las funciones de agregación disponibles en la API de estadísticas de seguridad:

Metric Descripción Aggregation function
bot La cantidad de direcciones IP distintas para bots detectados en intervalos de un minuto. count_distinct
bot_first_detected Fecha y hora en que se detectó por primera vez el bot. Solo disponible a través de la API. min
bot_last_detected Fecha y hora en que se detectó el bot por última vez. Solo disponible a través de la API. max
bot_traffic La cantidad de mensajes de direcciones IP de bots detectados en intervalos de un minuto. sum
message_count

Cantidad total de llamadas a la API que procesa Apigee en intervalos de un minuto.

Nota: message_count no se puede usar con otras métricas en el mismo informe.

sum
response_size Tamaño de la respuesta. average, max, min, sum

Dimensiones

Las dimensiones te permiten agrupar valores de métricas en función de subconjuntos de datos relacionados. En la siguiente tabla, se describen las dimensiones específicas de los informes de seguridad avanzada de la API:

Dimensión Descripción
bot_reason Puede ser cualquier combinación de reglas de detección de seguridad. bot_reason consiste en el subconjunto de las reglas de detección que coincidieron con el patrón de tráfico del bot.

incident_id (vista previa) El UUID para un incidente de seguridad, que se muestra en una llamada a la API de incidentes. Consulta Ejemplo: obtén detalles o un incidente específico.
security_action La acción de seguridad Es posible que los valores sean ALLOW, DENY o FLAG.
security_action_name El nombre de la acción de seguridad.
security_action_headers Encabezados que puedes usar para consultar una acción de seguridad de las marcas.

Nota: bot_reason y incident_id solo funcionan con las siguientes métricas:

  • bot
  • bot_traffic
  • response_size

Además de las dimensiones descritas anteriormente, la seguridad avanzada de la API también admite las siguientes dimensiones:

  • access_token
  • access_token
  • api_product
  • apiproxy
  • 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

Limitaciones de las estadísticas de seguridad

La API de estadísticas de seguridad (tanto tabulares como de series temporales) tiene los siguientes límites:

  • Tamaño máximo de la página: 14400
  • Máximo de 10 dimensiones de series temporales
  • Máximo de 15 dimensiones de estadísticas tabulares
  • Máximo de 5 agregaciones de métricas
  • Máximo de 5 agregaciones de métricas de series temporales
  • Intervalo de tiempo: la duración puede ser de 14 días como máximo, y la fecha de inicio y la de finalización deben estar dentro de los últimos 365 días.
  • Las dimensiones incident_id y bot_reason no se pueden usar con las métricas message_count o response_size.

Compara la API de estadísticas de seguridad y la API de informes de seguridad

La API de estadísticas de seguridad y la API de informes de seguridad muestran estadísticas de seguridad relacionadas con bots y abusos, pero tienen las siguientes diferencias:

  • La API de estadísticas de seguridad se diseñó para ver las estadísticas del tráfico reciente de la API. Solo se pueden obtener los datos de la API de estadísticas de seguridad de los últimos 14 días, pero puedes ver las estadísticas de inmediato cuando envías una solicitud.

    Las estadísticas de seguridad también se muestran en la vista de métricas de abuso en la IU de Apigee.

  • La API de informes de seguridad está diseñada para ver estadísticas de operaciones de larga duración. Para usar la API de puntuaciones de seguridad, debes enviar un trabajo y visualizar los resultados solo cuando este se haya completado. Se pueden obtener los datos de la API de puntuaciones de seguridad del último año.