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:

ORG es tu organización.
ENV es el entorno en el que quieres que se calcule el informe.
ENVGROUP es un grupo de entornos que contiene el entorno.
REPORT_ID es el ID del informe que muestra una llamada para crear un informe de seguridad.
$TOKEN es la variable de entorno para un token de acceso de OAuth.
timeRange es el intervalo de tiempo del informe.

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:

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

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:

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

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.