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 estadísticas relacionadas con abusos y bots de los últimos 14 días. Hay dos tipos de estadísticas de seguridad:

  • Estadísticas tabulares, que no tienen una dimensión temporal. Las estadísticas tabulares suelen calcularse mediante una función de agregación, como sum for message_count o bot_traffic.
  • Estadísticas de series temporales, que sí tienen una dimensión temporal.
Nota: La detección de bots tiene un retraso de procesamiento de entre 15 y 20 minutos de media.

Parámetros en llamadas a la API de ejemplo

En las siguientes secciones se muestran 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 de la estadística. Consulta Métricas y funciones de agregación.
  • AGGREGATION_i: una función de agregación de la métrica. Consulta la tabla que aparece más abajo.
  • DIMENSION_i: una dimensión para agrupar los valores de la estadística.
  • PAGE_SIZE: número máximo de subcomponentes devueltos en una sola página.
  • time_range: el periodo de las estadísticas del formulario. 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    donde:

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

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

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

Ejemplo: Consultar estadísticas de seguridad tabulares de 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 de ejemplo a la API.

Consulta las limitaciones de las estadísticas de seguridad para ver el número máximo de métricas, funciones de agregación y dimensiones que se pueden incluir en una solicitud.

A continuación, se muestra 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 ver las descripciones de la solicitud y la respuesta.

Ejemplo: Consultar estadísticas de seguridad de series temporales de un entorno

Las APIs de series temporales devuelven estadísticas de series temporales de las métricas elegidas, agrupadas por la dimensión seleccionada.

La siguiente llamada invoca estadísticas de series temporales del tráfico de bots agrupadas por proxy de API. Como hay cuatro proxies, se obtienen cuatro secuencias de puntos de series temporales. El orden de los puntos de cada fila coincide con el índice correspondiente del campo "columns".

Aquí tienes 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 de ejemplo a la API.

Consulta las descripciones de la solicitud y la respuesta en la página de referencia de queryTabularStats.

Ejemplo: consultar los detalles de un incidente para detectar abusos

En el siguiente ejemplo se consulta la información de un incidente de la función Detección de abusos de la API Advanced Security. La llamada devuelve detalles sobre el recuento de bots de la aplicación de desarrollador de un incidente concreto.

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 de ejemplo a la API.

Se devuelve una respuesta como la siguiente:

{
  "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 las descripciones de la solicitud y la respuesta en la página de referencia de queryTabularStats.

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 Número de direcciones IP distintas de los bots detectados en intervalos de un minuto. count_distinct
bot_first_detected Fecha y hora en que se detectó el bot por primera vez. 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 Número de mensajes procedentes de direcciones IP de bots detectados en intervalos de un minuto. sum
message_count

Número total de llamadas a la API procesadas por 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 le 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 las APIs:

Dimensión Descripción
bot_reason Puede ser cualquier combinación de las reglas de detección de seguridad. bot_reason consta del subconjunto de reglas de detección con las que coincide el patrón de tráfico del bot.
incident_id (vista previa) El UUID de un incidente de seguridad, que devuelve una llamada a la API Incidents. Consulta Ejemplo: Obtener detalles o un incidente específico.
security_action La acción de seguridad. Los valores posibles son ALLOW, DENY o FLAG.
security_action_name Nombre de la acción de seguridad.
security_action_headers Encabezados que puedes usar para consultar una acción de seguridad de denuncia.

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, Advanced API Security también admite las siguientes dimensiones:

  • 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

Limitaciones de las estadísticas de seguridad

La API de estadísticas de seguridad (tanto en formato tabular como de serie temporal) tiene los siguientes límites:

  • Tamaño máximo de página: 14.400
  • Un máximo de 10 dimensiones de serie temporal
  • Máximo de 15 dimensiones de estadísticas tabulares
  • Máximo de 5 agregaciones de métricas.
  • Un 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 tanto la fecha de inicio como 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 ni response_size.

Comparación de la API de estadísticas de seguridad y la API de informes de seguridad

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

  • La API de estadísticas de seguridad se ha diseñado para ver estadísticas del tráfico de las APIs recientes. Los datos de la API de estadísticas de seguridad solo se conservan durante 14 días, pero puedes ver las estadísticas inmediatamente cuando envíes una solicitud.

    Las estadísticas de seguridad también se muestran en la vista de métricas de abusos de la interfaz de usuario de Apigee.

  • La API de informes de seguridad se ha diseñado para ver estadísticas de operaciones de larga duración. Para usar la API de puntuaciones de seguridad, debes enviar un trabajo y ver los resultados solo cuando se haya completado. Los datos de la API de puntuaciones de seguridad se remontan a un año.