Gestire i report sulla sicurezza utilizzando l'API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come creare e visualizzare report sulla sicurezza utilizzando l'API per i report sulla sicurezza.

Per una panoramica dei report sulla sicurezza, incluse le limitazioni, consulta Panoramica dei report sulla sicurezza. Per la documentazione di riferimento dell'API per i report sulla sicurezza, consulta il riferimento dell'API Security Reports.

Nota:i dati che confluiscono nella pipeline di Apigee Analytics hanno un ritardo medio di 15-20 minuti. Di conseguenza, un report sulla sicurezza in cui l'ora di fine è inferiore a 20 minuti nel passato potrebbe restituire risultati errati.

Parametri negli esempi di chiamate API

Le sezioni seguenti forniscono esempi di chiamate API che utilizzano l'API securityReports. Le chiamate API contengono i seguenti parametri:

Creare un report sulla sicurezza

Per creare un report sulla sicurezza, inserisci un comando come il seguente:

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"

dove Query.json è un modello di query che definisce la query. Di seguito è riportato un esempio di modello di query.

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

La query ha i seguenti parametri:

  • Metriche:

    • bot. Questo conteggio indica il numero di indirizzi IP distinti che sono stati identificati come origini di bot.

      Funzione di aggregazione: count_distinct

    • bot_traffic. Il numero totale di richieste provenienti da indirizzi IP che sono le origini dei bot.

      Funzione di aggregazione: sum

    Consulta Metriche e funzioni di aggregazione.

  • Dimensione: ax_resolved_client_ip. Questo raggruppa i conteggi dei bot nel report in base all'indirizzo IP della loro origine. Consulta la sezione Dimensioni per informazioni sulle dimensioni supportate.
  • Filtro: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days. Consulta Intervallo di tempo.

Tieni presente che questa chiamata API restituisce lo stesso report dell'esempio di report sugli indirizzi IP dei bot creato utilizzando la UI di Apigee.

Intervallo di tempo

L'intervallo di tempo per il report. Puoi impostare il campo timeRange in uno dei seguenti modi:

  • Specifica per quanto tempo nel passato deve estendersi il report. Le opzioni sono: 
    "timeRange": "{last60minutes/last24hours/last7days}"
  • Specifica un'ora di inizio e di fine per il report nel seguente formato: 
    "timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }

    Sia start che end devono essere nel passato e possono essere al massimo 1 anno prima del presente quando crei il report.

Esempio di risposta

La query precedente restituisce una risposta simile alla seguente:

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

La risposta contiene quanto segue:

  • L'ID report, che puoi utilizzare per ottenere il report una volta completato. Nell'esempio riportato sopra, l'ID report è 3964675e-9934-4398-bff5-39dd93a67201.
  • "state": lo stato del job del report, che può essere uno dei seguenti:
    • enqueued: Il job di report è stato appena creato, ma non è ancora in esecuzione.
    • running: il job del report è in esecuzione.
    • completed: il job relativo al report è stato completato. A questo punto, puoi visualizzare il report.
    • expired: il job di report è scaduto e non puoi più visualizzare il report.

Ottenere lo stato del report

Per conoscere lo stato di un report, invia una richiesta come la seguente:

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"

dove REPORT_ID è l'ID report. Consulta Parametri nelle chiamate API di esempio.

La risposta contiene un riepilogo dei parametri del report, nonché lo stato attuale del report. In questo esempio, lo stato è "completed", quindi puoi visualizzare i risultati del report.

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

Scarica il rapporto

Per scaricare il report sulla sicurezza, invia una richiesta come la seguente:

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

dove REPORT_ID è l'ID report. Consulta Parametri nelle chiamate API di esempio.

Viene restituito un file contenente il report, il cui nome è nel formato OfflineQueryResult-{ID}.zip. Per visualizzare il report:

  1. Decomprimi OfflineQueryResult-{ID}.zip.
  2. Inserisci gzip -d QueryResults-{ID}*.json.gz.
  3. Inserisci cat QueryResults-{ID}*.json
    4. .

Esempio di traffico bot

L'esempio seguente crea un report su bot_traffic:

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

La query ha i seguenti parametri:

  • Metrica: bot_traffic. È il numero totale di richieste provenienti da indirizzi IP che sono stati identificati come origini bot, a intervalli di un minuto.

    Consulta Metriche e funzioni di aggregazione.

  • Dimensione: bot_reason. bot_reason può essere qualsiasi combinazione delle regole di rilevamento per i bot. Quando viene rilevato un bot, bot_reason è costituito dal sottoinsieme delle regole di rilevamento a cui corrisponde il pattern di traffico del bot.

    Consulta la sezione Dimensioni.

  • Filtro: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days

Tieni presente che questa chiamata API restituisce lo stesso report dell'esempio di report sugli indirizzi IP dei bot creato utilizzando la UI di Apigee.

Ritardo dei dati di rilevamento dei bot

Il rilevamento di bot ha un ritardo di elaborazione di circa 15-20 minuti in media.

Creare un report sulla sicurezza per un gruppo di ambienti

Utilizzando l'API Security Reports, puoi creare un report per i dati in un gruppo di ambienti (anziché solo un ambiente). Per farlo, inserisci un comando come il seguente:

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

e assicurati che il modello di query, Query.json, contenga la seguente riga:

"envgroup_hostname": "ENVGROUP"

dove ENVGROUP è il nome di un gruppo di ambienti che contiene l'ambiente. Puoi trovare il nome del gruppo di ambienti nell'UI di Apigee andando su Amministrazione > Ambienti > Gruppi.

Note:

  • Le API Report a livello di gruppo di ambienti supportano solo la metrica message_count con la funzione di aggregazione sum.
  • Le API Report a livello di gruppo di ambienti non supportano le dimensioni bot_reason o incident_id, ma supportano tutte le altre dimensioni per i report sulla sicurezza.

Ottenere lo stato del report

Per conoscere lo stato di un report, inserisci un comando come il seguente:

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"

Viene restituito un riepilogo della richiesta di report e lo stato attuale del report. Ecco una risposta di esempio:

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

Poiché lo stato è "completed", ora puoi visualizzare il report, come descritto di seguito.

Visualizzare un report sulla sicurezza

Per visualizzare un report sulla sicurezza, inserisci un comando come il seguente:

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"

Viene restituito un file contenente il report, il cui nome è nel formato OfflineQueryResult-{ID}.zip. Per visualizzare il report:

  1. Decomprimi OfflineQueryResult-{ID}.zip.
  2. Inserisci gzip -d QueryResults-{ID}*.json.gz.
  3. Inserisci cat QueryResults-{ID}*.json
    4. .