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:

Dimensiones	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.