API de informes de seguridad

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

Consulta la documentación de Apigee Edge.

Además de usar Informes de seguridad en la IU de Apigee, también puedes acceder a todas las funciones de Informes de seguridad a través de la API de informes de seguridad. En esta sección, se describe cómo usar la API de informes de seguridad.

Nota: Los datos que fluyen a la canalización de Analytics de Apigee tienen un retraso promedio de hasta 15 a 20 minutos. Como resultado, un informe de seguridad en el que la hora de finalización es inferior a 20 minutos en el pasado podría mostrar resultados incorrectos.

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 informes de seguridad. Las llamadas a la API contienen los siguientes parámetros:

Crea un informe de seguridad

Para crear un informe de seguridad, ingresa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

En el ejemplo anterior, Query.json es una plantilla de consulta que define la consulta. A continuación, se muestra un ejemplo de una plantilla de consulta.

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

La consulta tiene los siguientes parámetros:

  • Métricas:
    • bot Esto cuenta la cantidad de direcciones IP distintas que se identificaron como fuentes de bots.

      Función de agregación: count_distinct

    • bot_traffic La cantidad total de solicitudes de direcciones IP que son las fuentes de bots.

      Función de agregación: sum

    Consulta Métricas y funciones de agregación.

  • Dimensión: ax_resolved_client_ip. Esto agrupa los recuentos de bots en el informe por la dirección IP de su fuente.

    Consulta Dimensiones.

  • Filtro: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days. Consulta Intervalo de tiempo.

Ten en cuenta que esta llamada a la API muestra el mismo informe que el ejemplo de informe de direcciones IP del bot creado con la IU de Apigee.

Intervalo de tiempo

Es el intervalo de tiempo del informe. Puedes configurar el campo timeRange de cualquiera de las siguientes maneras:

  • Especifica durante cuánto tiempo se debería extender el informe. Las opciones son las siguientes:
    "timeRange": "{last60minutes/last24hours/last7days}"
  • Especifica una hora de inicio y de finalización para el informe en el siguiente formato:
    "timeRange": {
            "start": "YYYY-MM-DDT00:00:00Z",
            "end": "YYYY-MM-DDT00:00:00Z"
            }

    Tanto start como end deben ser pasadas y pueden ser como máximo 1 año antes del presente cuando creas el informe.

Respuesta de muestra

La consulta anterior muestra una respuesta como la siguiente:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

La respuesta contiene lo siguiente:

  • El ID del informe, que puedes usar para obtenerlo una vez que se complete. En el ejemplo anterior, el ID del informe es 3964675e-9934-4398-bff5-39dd93a67201.
  • "state": Es el estado del trabajo de informe, que puede ser uno de los siguientes:
    • enqueued: El trabajo de informe se acaba de crear, pero aún no se está ejecutando.
    • running: El trabajo de informe se está ejecutando.
    • completed: El trabajo de informe se completó. En esta etapa, puedes ver el informe.
    • expired: El trabajo de informes venció y ya no puedes verlo.

Obtén el estado del informe

Para obtener el estado de un informe, envía una solicitud como la siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

donde REPORT_ID es el ID del informe. Consulta Parámetros en llamadas de API de ejemplo.

La respuesta contiene un resumen de los parámetros del informe, así como el estado actual del informe. En este ejemplo, el estado es "completed", por lo que puedes ver los resultados del informe.

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

Obtén el informe

Para descargar el informe de seguridad, envía una solicitud como la siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

donde REPORT_ID es el ID del informe. Consulta Parámetros en llamadas a la API de ejemplo.

Esto muestra un archivo que contiene el informe, cuyo nombre tiene el formato OfflineQueryResult-{ID}.zip. Para ver el informe, sigue estos pasos:

  1. Descomprime OfflineQueryResult-{ID}.zip.
  2. Ingresa gzip -d QueryResults-{ID}*.json.gz.
  3. Ingresar cat QueryResults-{ID}*.json
  4. .

Ejemplo de tráfico de bot

En el siguiente ejemplo, se crea un informe sobre bot_traffic:

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

La consulta tiene los siguientes parámetros:

  • Métrica: bot_traffic. Esta es la cantidad total de solicitudes de las direcciones IP que se identificaron como fuentes de bots, en intervalos de un minuto.

    Consulta Métricas y funciones de agregación.

  • Dimensión: bot_reason. bot_reason puede ser cualquier combinación de reglas de detección para bots. Cuando se detecta un bot, bot_reason consta del subconjunto de reglas de detección con los que coincidió el patrón de tráfico del bot.

    Consulta Dimensiones.

  • Filtro: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days

Ten en cuenta que esta llamada a la API muestra el mismo informe que el ejemplo de informe de direcciones IP del bot creado con la IU de Apigee.

Retraso de datos de detección de bots

La detección de bots tiene una demora de procesamiento de alrededor de 15 a 20 minutos en promedio.

Crea un informe de seguridad para un grupo de entornos

Con la API de informes de seguridad, puedes crear un informe para los datos en un grupo de entornos (en lugar de solo en un entorno). Para hacerlo, ingresa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

y asegúrate de que la plantilla de consultas, Query.json, contenga la siguiente línea:

"envgroup_hostname": "ENVGROUP"

En el ejemplo anterior, ENVGROUP es el nombre de un grupo de entornos que contiene el entorno. Puedes encontrar el nombre del grupo de entornos en la IU de Apigee yendo a Administrador > Entornos > Grupos.

Notas:

  • Las APIs de informes a nivel del grupo de entornos solo admiten la métrica message_count con la función de agregación sum.
  • Las APIs de informes a nivel del grupo de entornos no admiten las dimensiones bot_reason o incident_id, pero admiten todas las demás dimensiones para los informes de seguridad.

Obtén el estado del informe

Para obtener el estado de un informe, ingresa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

Esto muestra un resumen de la solicitud del informe y el estado actual del informe. Esta es una respuesta de ejemplo:

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

Dado que el estado es "completed", ahora puedes ver el informe, como se describe a continuación.

Visualiza un informe de seguridad

Para ver un informe de seguridad, ingresa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

Esto muestra un archivo que contiene el informe, cuyo nombre tiene el formato OfflineQueryResult-{ID}.zip. Para ver el informe, sigue estos pasos:

  1. Descomprime OfflineQueryResult-{ID}.zip.
  2. Ingresa gzip -d QueryResults-{ID}*.json.gz.
  3. Ingresar cat QueryResults-{ID}*.json
  4. .

Métricas y funciones de agregación

Puedes usar las siguientes métricas y funciones de agregación, que calculan estadísticas a partir de una métrica, para un informe.

Métrica Descripción Aggregation function
bot La cantidad de direcciones IP distintas para bots detectados en intervalos de un minuto. count_distinct
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 carga útil de la respuesta que se muestra en bytes. sum, avg, min, max
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

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 la 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
  • api_product
  • apiproxy
  • ax_dn_region
  • 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_family
  • ax_ua_agent_type
  • ax_ua_agent_version
  • ax_ua_agent_category
  • ax_ua_os_family
  • bot_reason
  • client_id
  • developer
  • developer_app
  • developer_email
  • envgroup_hostname
  • environment
  • incident_id (vista previa)
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • request_verb
  • response_status_code
  • target_host
  • target_url
  • useragent

Limitaciones de los informes de seguridad

Consulta Limitaciones de los informes de seguridad.