API Security Reports

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Oltre a utilizzare i report sulla sicurezza nell'interfaccia utente di Apigee, puoi anche accedere a tutte le funzionalità dei report sulla sicurezza tramite l'API di report sulla sicurezza. Questa sezione descrive come utilizzare l'API Security Reports.

Nota: i dati che fluiscono 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 fa potrebbe restituire risultati errati.

Parametri nelle chiamate API di esempio

Le sezioni seguenti forniscono esempi di chiamate API che utilizzano l'API Security Reports. Le chiamate all'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 conteggia il numero di indirizzi IP distinti che sono stati identificati come sorgenti 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. In questo modo, i conteggi dei bot nel report vengono raggruppati in base all'indirizzo IP della relativa origine.

    Consulta la sezione Dimensioni.

  • Filtro: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days. Consulta la sezione Intervallo di tempo.

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

Intervallo di tempo

L'intervallo di tempo del 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 sia end devono riferirsi al passato e possono risalire al massimo a un anno prima del giorno in cui crei il report.

Risposta di esempio

La query riportata sopra 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 recuperare il report al termine dell'elaborazione. Nell'esempio precedente, l'ID report è 3964675e-9934-4398-bff5-39dd93a67201.
  • "state": lo stato del job del report, che può essere uno dei seguenti:
    • enqueued: il job del 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 del report è scaduto e non puoi più visualizzarlo.

Visualizza 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 corrente 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 è del tipo 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 di 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. Si tratta del numero totale di richieste provenienti da indirizzi IP che sono stati identificati come origini di bot, a intervalli di un minuto.

    Consulta Metriche e funzioni di aggregazione.

  • Dimensione: bot_reason. bot_reason può essere qualsiasi combinazione di 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 l'interfaccia utente di Apigee.

Ritardo dei dati sul rilevamento dei bot

Il rilevamento dei bot ha un ritardo di elaborazione medio di circa 15-20 minuti.

Creare un report sulla sicurezza per un gruppo di ambienti

Con l'API di generazione di report sulla sicurezza, puoi creare un report per i dati di un gruppo di ambienti (anziché solo per 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'interfaccia utente di Apigee andando a 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.

Visualizza 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 corrente 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.

Visualizzazione di 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 è del tipo 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. .

Metriche e funzioni di aggregazione

Per un report puoi utilizzare le seguenti metriche e funzioni di aggregazione, che calcolano le statistiche da una metrica.

Metrica Descrizione Aggregation function
bot Il numero di indirizzi IP distinti per i bot rilevati in intervalli di un minuto. count_distinct
bot_traffic Il numero di messaggi provenienti da indirizzi IP di bot rilevati in intervalli di un minuto. sum
message_count

Numero totale di chiamate API elaborate da Apigee in intervalli di un minuto.

Nota:message_count non può essere utilizzato con altre metriche nello stesso report.

sum
response_size Dimensioni del payload della risposta restituito in byte. sum, avg, min, max
bot_first_detected Data e ora in cui il bot è stato rilevato per la prima volta. Disponibile solo tramite l'API. min
bot_last_detected Data e ora dell'ultimo rilevamento del bot. Disponibile solo tramite l'API. max

Dimensioni

Le dimensioni ti consentono di raggruppare i valori delle metriche in base a sottoinsiemi correlati dei dati. La tabella seguente descrive le dimensioni specifiche per Advanced API Security:

Dimensioni Descrizione
bot_reason Può essere qualsiasi combinazione di regole di rilevamento di sicurezza. bot_reason è costituito dal sottoinsieme delle regole di rilevamento a cui corrisponde il pattern di traffico del bot.

incident_id (anteprima) L'UUID di un incidente di sicurezza, restituito da una chiamata all'API Incidents. Consulta Esempio: visualizzare i dettagli di un incidente specifico.
security_action L'azione di sicurezza. I valori possibili sono ALLOW, DENY o FLAG.
security_action_name Il nome dell'azione di sicurezza.
security_action_headers Intestazioni che puoi utilizzare per eseguire query su un'azione di sicurezza di segnalazione.

Nota: bot_reason e incident_id funzionano solo con le seguenti metriche:

  • bot
  • bot_traffic
  • response_size

Oltre alle dimensioni descritte sopra, Advanced API Security supporta anche le seguenti dimensioni:

  • 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 (anteprima)
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • request_verb
  • response_status_code
  • target_host
  • target_url
  • useragent

Limitazioni dei report sulla sicurezza

Consulta Limitazioni dei report sulla sicurezza.