Administra informes de seguridad con la API

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

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo crear y ver informes de seguridad con la API de informes de seguridad.

Para obtener una descripción general de los informes de seguridad, incluidas las limitaciones, consulta Descripción general de los informes de seguridad. Para consultar la documentación de referencia de la API de los informes de seguridad, consulta la referencia de la API de los 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 para obtener información sobre las dimensiones admitidas.
  • 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. Ingresa 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.

Cómo ver 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. Ingresa cat QueryResults-{ID}*.json
    4. .