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.
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
comoend
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ónsum
. - Las APIs de informes a nivel del grupo de entornos no admiten las dimensiones
bot_reason
oincident_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: |
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.