API des rapports de sécurité

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

En plus d'utiliser les rapports de sécurité dans l'interface utilisateur d'Apigee, vous pouvez également accéder à toutes les fonctionnalités des rapports de sécurité via l'API des rapports de sécurité. Cette section explique comment utiliser l'API des rapports de sécurité.

Remarque : Les données circulant dans le pipeline Apigee Analytics présentent un délai moyen de 15 à 20 minutes. Par conséquent, un rapport de sécurité dans lequel l'heure de fin est inférieure à 20 minutes dans le passé peut renvoyer des résultats incorrects.

Paramètres dans des exemples d'appels d'API

Les sections suivantes présentent des exemples d'appels d'API qui utilisent l'API des rapports de sécurité. Les appels d'API contiennent les paramètres suivants :

ORG est votre organisation.
ENV est l'environnement dans lequel vous souhaitez calculer le rapport.
ENVGROUP est un groupe d'environnements contenant l'environnement.
REPORT_ID est l'ID de rapport renvoyé par un appel pour créer un rapport de sécurité.
$TOKEN est la variable d'environnement d'un jeton d'accès OAuth.
timeRange est la période du rapport.

Créer un rapport de sécurité

Pour créer un rapport de sécurité, entrez une commande semblable à ce qui suit :

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"

où Query.json est un modèle de requête qui définit la requête. Un exemple de modèle de requête est présenté ci-dessous.

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

La requête comporte les paramètres suivants :

Métriques :
- bot. Cela comprend le nombre d'adresses IP distinctes qui ont été identifiées comme sources de bots.
  
  Fonction d'agrégation : count_distinct
- bot_traffic. Nombre total de requêtes provenant d'adresses IP qui constituent les sources des bots.
  
  Fonction d'agrégation : sum
Consultez la section Fonctions de métriques et d'agrégation.
Dimension : ax_resolved_client_ip. Cela regroupe les décomptes de bots dans le rapport en fonction de l'adresse IP de leur source.
Consultez la section Dimensions.
Filter : environment.
groupByTimeUnit : minute.
timeRange : last7days. Consultez la section Période.

Notez que cet appel d'API renvoie le même rapport que l'exemple de rapport d'adresse IP de bot créé à l'aide de l'interface utilisateur d'Apigee.

Période

Période pour le rapport. Vous pouvez définir le champ timeRange de l'une des manières suivantes :

Indiquez sur quelle durée dans le passé le rapport doit s'étendre. Les options sont les suivantes :
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
Indiquez les heures de début et de fin du rapport, en respectant le format suivant :
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
Les valeurs start et end doivent être antérieures à la date du jour et ne peuvent pas dépasser un an avant la création du rapport.

Exemple de réponse

La requête ci-dessus renvoie une réponse semblable à ce qui suit :

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

La réponse contient les éléments suivants :

L'ID du rapport, que vous pouvez utiliser pour obtenir le rapport une fois qu'il est terminé. Dans l'exemple ci-dessus, l'ID du rapport est 3964675e-9934-4398-bff5-39dd93a67201.
"state" : état du job de création de rapports, qui peut être l'un des suivants :
- enqueued : la tâche de rapport vient d'être créée, mais n'est pas encore en cours d'exécution.
- running : la tâche de rapport est en cours d'exécution.
- completed : la tâche de rapport est terminée. À ce stade, vous pouvez afficher le rapport.
- expired : la tâche de rapport a expiré et vous ne pouvez plus afficher le rapport.

Obtenir l'état du rapport

Pour obtenir l'état d'un rapport, envoyez une requête semblable à ce qui suit :

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"

où REPORT_ID correspond à l'ID du rapport. Consultez la section Paramètres dans les exemples d'appels d'API.

La réponse contient un résumé des paramètres du rapport, ainsi que l'état actuel du rapport. Dans cet exemple, l'état est "completed". Vous pouvez donc afficher les résultats du rapport.

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

Obtenez le rapport

Pour télécharger le rapport de sécurité, envoyez une requête de ce type :

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

où REPORT_ID correspond à l'ID du rapport. Consultez la section Paramètres dans les exemples d'appels d'API.

Cette commande renvoie un fichier contenant le rapport, dont le nom est au format OfflineQueryResult-{ID}.zip. Pour afficher le rapport :

Décompressez OfflineQueryResult-{ID}.zip.
Saisissez gzip -d QueryResults-{ID}*.json.gz.
Saisissez cat QueryResults-{ID}*.json.

Exemple de trafic des bots

L'exemple suivant crée un rapport sur bot_traffic :

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

La requête comporte les paramètres suivants :

Metric : bot_traffic. Il s'agit du nombre total de requêtes provenant d'adresses IP identifiées comme sources de bots, par intervalles d'une minute.

Consultez la section Fonctions de métriques et d'agrégation.
Dimension : bot_reason. bot_reason peut être n'importe quelle combinaison des règles de détection pour les bots. Lorsqu'un bot est détecté, bot_reason comprend le sous-ensemble des règles de détection correspondant au modèle de trafic du bot.

Consultez la section Dimensions.
Filter : environment.
groupByTimeUnit : minute.
timeRange : last7days.

Notez que cet appel d'API renvoie le même rapport que l'exemple de rapport d'adresse IP de bot créé à l'aide de l'interface utilisateur d'Apigee.

Délai de détection des bots

La détection des bots présente un délai de traitement d'environ 15 à 20 minutes en moyenne.

Créer un rapport de sécurité pour un groupe d'environnement

L'API de rapports de sécurité vous permet de créer un rapport de données d'un groupe d'environnement (par opposition à un environnement). Pour ce faire, entrez une commande semblable à ce qui suit :

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

Assurez-vous que le modèle de requête, Query.json, contient la ligne suivante :

"envgroup_hostname": "ENVGROUP"

où ENVGROUP est le nom d'un groupe d'environnement contenant l'environnement. Vous pouvez trouver le nom du groupe d'environnement dans Administration > Environnements > Groupes.

Remarques :

Les API Reports au niveau des groupes d'environnements ne sont compatibles qu'avec la métrique message_count avec la fonction d'agrégation sum.
Les API Reports au niveau des groupes d'environnements ne sont pas compatibles avec les dimensions bot_reason ou incident_id, mais elles sont compatibles avec toutes les autres dimensions pour les rapports de sécurité.

Obtenir l'état du rapport

Pour obtenir l'état d'un rapport, saisissez une commande semblable à celle-ci :

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"

Cette requête renvoie un résumé de la requête de rapport et l'état actuel de celui-ci. Voici un exemple de réponse :

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

Comme l'état est défini sur "completed", vous pouvez maintenant afficher le rapport, comme décrit ci-dessous.

Afficher un rapport de sécurité

Pour afficher un rapport de sécurité, entrez une commande semblable à celle-ci :

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"

Cette commande renvoie un fichier contenant le rapport, dont le nom est au format OfflineQueryResult-{ID}.zip. Pour afficher le rapport :

Décompressez OfflineQueryResult-{ID}.zip.
Saisissez gzip -d QueryResults-{ID}*.json.gz.
Saisissez cat QueryResults-{ID}*.json.

Métriques et fonctions d'agrégation

Vous pouvez utiliser les métriques et les fonctions d'agrégation suivantes, qui calculent les statistiques sur une métrique, pour un rapport.

Métrique	Description	`Aggregation function`
`bot`	Nombre d'adresses IP distinctes pour les bots détectés sur des intervalles d'une minute.	`count_distinct`
`bot_traffic`	Nombre de messages provenant d'adresses IP de bots détectés sur un intervalle d'une minute.	`sum`
`message_count`	Nombre total d'appels d'API traités par Apigee par intervalles d'une minute. Remarque : `message_count` ne peut pas être utilisé avec d'autres métriques du même rapport.	`sum`
`response_size`	Taille de la charge utile de réponse renvoyée en octets.	`sum`, `avg`, `min`, `max`
`bot_first_detected`	Date et heure auxquelles le bot a été détecté pour la première fois. Disponible uniquement via l'API.	`min`
`bot_last_detected`	Date et heure auxquelles le bot a été détecté pour la dernière fois. Disponible uniquement via l'API.	`max`

Dimensions

Les dimensions vous permettent de regrouper des valeurs de métriques en fonction des sous-ensembles de données associés. Le tableau suivant décrit les dimensions spécifiques à Advanced API Security :

Dimension	Description
`bot_reason`	Peut être n'importe quelle combinaison des règles de détection de sécurité. `bot_reason` comprend le sous-ensemble de règles de détection correspondant au modèle de trafic du bot.
`incident_id` (aperçu)	UUID pour un incident de sécurité, qui est renvoyé par un appel à l'API Incidents. Consultez la section Exemple : Obtenir des détails ou un incident spécifique.
`security_action`	L'action de sécurité. Les valeurs possibles sont `ALLOW`, `DENY` ou `FLAG`.
`security_action_name`	Nom de l'action de sécurité.
`security_action_headers`	En-têtes que vous pouvez utiliser pour interroger une action de sécurité de signalement.

Remarque : bot_reason et incident_id ne fonctionnent qu'avec les métriques suivantes :

bot
bot_traffic
response_size

Outre les dimensions décrites ci-dessus, Advanced API Security accepte également les dimensions suivantes :

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 (aperçu)
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

Limites des rapports de sécurité

Consultez la page Limites applicables aux rapports de sécurité.