API di statistiche sulla sicurezza

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

L'API per le statistiche sulla sicurezza ti consente di visualizzare le statistiche relative ad abusi e bot negli ultimi 14 giorni. Esistono due tipi di statistiche sulla sicurezza:

  • Statistiche tabellari, che non hanno una dimensione temporale. Le statistiche tabellari vengono spesso calcolate utilizzando una funzione di aggregazione, ad esempio sum for message_count o bot_traffic.
  • Statistiche delle serie temporali, che hanno una dimensione temporale.
Nota: il rilevamento di bot ha un ritardo di elaborazione di circa 15-20 minuti in media.

Parametri negli esempi di chiamate API

Le sezioni seguenti forniscono esempi di chiamate API che utilizzano l'API delle statistiche sulla sicurezza. Le chiamate API contengono i seguenti parametri:

  • ORG: la tua organizzazione.
  • ENV: Il tuo ambiente.
  • METRIC_i: una metrica per la statistica. Consulta Metriche e funzioni di aggregazione.
  • AGGREGATION_i: una funzione di aggregazione per la metrica. Consulta la tabella riportata di seguito.
  • DIMENSION_i: una dimensione per raggruppare i valori della statistica.
  • PAGE_SIZE: Numero massimo di componenti secondari restituiti in una singola pagina.
  • time_range: l'intervallo di tempo per le statistiche nel modulo 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    dove:

    • START_TIME è l'ora di inizio dell'intervallo di tempo.
    • END_TIME è l'ora di fine dell'intervallo di tempo.

    START_TIME e END_TIME sono nel formato "YYYY-MM-DDT00:00:00Z".

    La durata dell'intervallo di tempo può essere al massimo di 14 giorni e sia la data di inizio che la data di fine devono rientrare negli ultimi 365 giorni.

Esempio: esegui una query sulle statistiche di sicurezza tabellari per un ambiente

Una richiesta che esegue query sulle statistiche tabellari ha il seguente formato:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

Consulta la sezione Parametri nelle chiamate API di esempio.

Consulta Limitazioni delle statistiche di sicurezza per il numero massimo di metriche, funzioni di aggregazione e dimensioni che possono essere inclusi in una richiesta.

Ecco un esempio di richiesta che esegue query sulle statistiche tabellari:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulta la pagina di riferimento queryTabularStats per le descrizioni della richiesta e della risposta.

Esempio: esegui query sulle statistiche di sicurezza delle serie temporali per un ambiente

Le API delle serie temporali restituiscono statistiche delle serie temporali per le metriche scelte, raggruppate in base alla dimensione scelta.

La seguente chiamata richiama le statistiche delle serie temporali per il traffico bot raggruppato per proxy API. Poiché ci sono quattro proxy, si ottengono quattro sequenze di punti delle serie temporali. L'ordine dei punti di ogni riga corrisponde all'indice corrispondente nel campo delle colonne.

Ecco una richiesta di esempio:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulta la sezione Parametri nelle chiamate API di esempio.

Consulta la pagina di riferimento queryTabularStats per le descrizioni della richiesta e della risposta.

Esempio: esegui una query sui dettagli dell'incidente per il rilevamento di abusi

La query nell'esempio seguente interroga i dettagli di un incidente per il rilevamento di abusi di Advanced API Security. La chiamata restituisce i dettagli del conteggio dei bot per developer_app per un determinato incidente.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulta la sezione Parametri nelle chiamate API di esempio.

Viene restituita una risposta simile alla seguente:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

Consulta la pagina di riferimento queryTabularStats per le descrizioni della richiesta e della risposta.

Metriche e funzioni di aggregazione

La tabella seguente descrive le metriche e le funzioni di aggregazione disponibili nell'API delle statistiche sulla sicurezza:

Metric Descrizione Aggregation function
bot Il numero di indirizzi IP distinti per i bot rilevati in intervalli di un minuto. count_distinct
bot_first_detected Data e ora in cui è stato rilevato per la prima volta il bot. Disponibile solo tramite l'API. min
bot_last_detected Data e ora dell'ultimo rilevamento del bot. Disponibile solo tramite l'API. max
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 a intervalli di un minuto.

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

 sum
response_size Dimensioni della risposta. average, max, min, sum

Dimensioni

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

Dimensioni Descrizione
bot_reason Può essere qualsiasi combinazione delle 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. Vedi Esempio: ottenere dettagli o 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 per 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
  • app_group_app
  • app_group_name
  • 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_version
  • client_id
  • developer
  • developer_app
  • developer_email
  • environment
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

Limitazioni delle statistiche sulla sicurezza

L'API per le statistiche sulla sicurezza (sia tabellari che delle serie temporali) presenta i seguenti limiti:

  • Dimensioni massime della pagina: 14400
  • Massimo 10 dimensioni delle serie temporali
  • Massimo 15 dimensioni delle statistiche tabellari
  • Massimo 5 aggregazioni di metriche.
  • Massimo 5 aggregazioni di metriche delle serie temporali
  • Intervallo di tempo: la durata può essere al massimo di 14 giorni e sia la data di inizio che la data di fine devono essere comprese negli ultimi 365 giorni.
  • Le dimensioni incident_id e bot_reason non possono essere utilizzate con le metriche message_count o response_size.

Confronto tra l'API per le statistiche sulla sicurezza e l'API per i report sulla sicurezza

Sia l'API per le statistiche sulla sicurezza sia l'API per i report sulla sicurezza restituiscono statistiche sulla sicurezza relative ad abusi e bot, ma presentano le seguenti differenze:

  • L'API per le statistiche sulla sicurezza è progettata per visualizzare le statistiche sul traffico API recente. I dati per l'API delle statistiche sulla sicurezza risalgono solo a 14 giorni prima, ma puoi visualizzare le statistiche immediatamente quando invii una richiesta.

    Le statistiche sulla sicurezza vengono visualizzate anche nella visualizzazione delle metriche relative all'abuso nell'interfaccia utente di Apigee.

  • L'API per i report sulla sicurezza è progettata per visualizzare le statistiche relative alle operazioni a lunga esecuzione. Per utilizzare l'API dei punteggi di sicurezza, devi inviare un job e visualizzare i risultati solo al termine del job. I dati per l'API dei punteggi di sicurezza risalgono a un anno.