Esta página se ha traducido con Cloud Translation API.

API Security reports

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

Consulta la documentación de Apigee Edge.

Además de usar los informes de seguridad en la interfaz de usuario de Apigee, también puede acceder a todas las funciones de los 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 Apigee Analytics tienen un retraso de entre 15 y 20 minutos de media. Por lo tanto, es posible que un informe de seguridad en el que la hora de finalización sea inferior a 20 minutos en el pasado devuelva resultados incorrectos.

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 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 devuelto por una llamada a crear un informe de seguridad.
$TOKEN es la variable de entorno de un token de acceso OAuth.
timeRange es el periodo del informe.

Crear un informe de seguridad

Para crear un informe de seguridad, introduce 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"

donde Query.json es una plantilla de consulta que define la consulta. A continuación, se muestra un ejemplo de 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. Cuenta el número de direcciones IP distintas que se han identificado como fuentes de bots.
  
  Función de agregación: count_distinct
- bot_traffic. El número total de solicitudes procedentes de direcciones IP que son fuentes de bots.
  
  Función de agregación: sum
Consulta Métricas y funciones de agregación.
Dimensión: ax_resolved_client_ip. De esta forma, se agrupan los recuentos de bots del informe por la dirección IP de su fuente.
Consulta Dimensiones.
Filtro: environment.
groupByTimeUnit: minute
timeRange: last7days. Consulta Periodo.

Ten en cuenta que esta llamada a la API devuelve el mismo informe que el ejemplo de informe de direcciones IP de bots creado con la interfaz de Apigee.

Periodo

El periodo del informe. Puedes definir el campo timeRange de una de las siguientes formas:

Especifica el periodo que debe abarcar el informe. Las opciones son las siguientes:
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
Especifique la hora de inicio y de finalización del informe con el siguiente formato:
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
Tanto start como end deben ser fechas anteriores y no pueden ser más de un año anteriores a la fecha actual al crear el informe.

Respuesta de ejemplo

La consulta anterior devuelve 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 puede usar para obtener el informe una vez que se haya completado. En el ejemplo anterior, el ID de informe es 3964675e-9934-4398-bff5-39dd93a67201.
"state": el estado del trabajo del informe, que puede ser uno de los siguientes:
- enqueued: el trabajo de generación de informes se acaba de crear, pero aún no se está ejecutando.
- running: el trabajo de generación de informes está en curso.
- completed: el trabajo del informe se ha completado. En esta fase, puede ver el informe.
- expired: el trabajo del informe ha caducado y ya no puedes verlo.

Obtener 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"
}

Descargar 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 los parámetros de las llamadas a la API de ejemplo.

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

Descomprimir OfflineQueryResult-{ID}.zip.
Introduce gzip -d QueryResults-{ID}*.json.gz.
Indica el número de cat QueryResults-{ID}*.json

Ejemplo de tráfico de robots

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. Es el número total de solicitudes de direcciones IP que se han identificado 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 las reglas de detección de bots. Cuando se detecta un bot, bot_reason consta del subconjunto de las reglas de detección con las que coincide 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 devuelve el mismo informe que el ejemplo de informe de direcciones IP de bots creado con la interfaz de Apigee.

Retraso en los datos de detección de bots

La detección de bots tiene un retraso de procesamiento de entre 15 y 20 minutos de media.

Crear un informe de seguridad de un grupo de entornos

Con la API de informes de seguridad, puede crear un informe de datos de un grupo de entornos (en lugar de un solo entorno). Para ello, introduce 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 consulta Query.json contenga la siguiente línea:

"envgroup_hostname": "ENVGROUP"

donde ENVGROUP es el nombre de un grupo de entornos que contiene el entorno. Para ver el nombre del grupo de entornos en la interfaz de Apigee, vaya a Administrar > Entornos > Grupos.

Notas:

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

Obtener el estado del informe

Para obtener el estado de un informe, introduce 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"

De esta forma, se devuelve un resumen de la solicitud del informe y el estado actual del informe. A continuación se muestra 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"
  }
}

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

Ver un informe de seguridad

Para ver un informe de seguridad, introduce 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"

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

Descomprimir OfflineQueryResult-{ID}.zip.
Introduce gzip -d QueryResults-{ID}*.json.gz.
Indica el número de cat QueryResults-{ID}*.json

Métricas y funciones de agregación

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

Métrica	Descripción	`Aggregation function`
`bot`	Número de direcciones IP distintas de los bots detectados en intervalos de un minuto.	`count_distinct`
`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 carga útil de la respuesta devuelta en bytes.	`sum`, `avg`, `min`, `max`
`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`

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 la 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
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 las limitaciones de los informes de seguridad.

API Security reports Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Parámetros en llamadas a la API de ejemplo

Crear un informe de seguridad

Periodo

Respuesta de ejemplo

Obtener el estado del informe

Descargar el informe

Ejemplo de tráfico de robots

Retraso en los datos de detección de bots

Crear un informe de seguridad de un grupo de entornos

Obtener el estado del informe

Ver un informe de seguridad

Métricas y funciones de agregación

Dimensiones

Limitaciones de los informes de seguridad

API Security reports