API delle statistiche sulla sicurezza

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

L'API delle statistiche di sicurezza consente di visualizzare statistiche sugli abusi e relativi ai bot su ultimi 14 giorni. Esistono due tipi di statistiche sulla sicurezza:

  • Statistiche tabulari, che non hanno una dimensione temporale. Le statistiche tabulari sono spesso calcolati 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 dei bot ha un ritardo di elaborazione di circa 15-20 minuti su media.

Parametri nelle chiamate API di esempio

Le sezioni seguenti forniscono esempi di chiamate API che utilizzano le statistiche sulla sicurezza API. 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 della metrica. Consulta la tabella riportata di seguito.
  • DIMENSION_i: un 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 lunghezza dell'intervallo di tempo può essere al massimo di 14 giorni e sia la data di inizio che la data di fine deve essere compreso negli ultimi 365 giorni.

Esempio: eseguire query su statistiche tabulari sulla sicurezza per un ambiente

Una richiesta di query sulle statistiche tabulari 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 Parametri nelle chiamate API di esempio.

Consulta Limitazioni delle statistiche sulla sicurezza 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 tabulari:

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 le Pagina di riferimento queryTabularStats per le descrizioni della richiesta e la risposta.

Esempio: eseguire query sulle statistiche di sicurezza di una serie temporale per un ambiente

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

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

Ecco un esempio di richiesta:

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 Parametri nelle chiamate API di esempio.

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

Esempio: eseguire una query sui dettagli degli incidenti per il rilevamento di comportamenti illeciti

L'esempio seguente esegue query sui dettagli di un incidente per Advanced API Security Rilevamento di comportamenti illeciti. La chiamata ritorna dettagli del numero di 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 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 le Pagina di riferimento queryTabularStats per le descrizioni della richiesta e la risposta.

Metriche e funzioni di aggregazione

La tabella seguente descrive le metriche e le funzioni di aggregazione disponibili in l'API delle statistiche di 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 La data e l'ora in cui è stato rilevato il bot. Disponibile solo tramite l'API. min
bot_last_detected La data e l'ora dell'ultimo rilevamento del bot. Disponibile solo tramite l'API. max
bot_traffic Il numero di messaggi provenienti dagli indirizzi IP dei 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 utilizzato con altre metriche nello stesso tipo. report.

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

Dimensioni

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

Dimensioni Descrizione
bot_reason Può essere una qualsiasi combinazione di livelli di regole di rilevamento. bot_reason è costituito da sottoinsieme di regole di rilevamento corrispondenti al modello di traffico del bot.
incident_id (anteprima) L'UUID di un incidente di sicurezza, restituito da una chiamata all'API Incidents. Vedi Esempio: visualizzare i 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 una query relativa a un'azione di segnalazione della sicurezza.

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

  • bot
  • bot_traffic
  • response_size

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

  • access_token
  • access_token
  • api_product
  • apiproxy
  • 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 di sicurezza (tabulari e serie temporali) ha i seguenti limiti:

  • Dimensioni massime della pagina: 14.400
  • Massimo 10 dimensioni di serie temporali
  • È consentito un massimo di 15 dimensioni di statistiche tabulari.
  • Massimo 5 aggregazioni di metriche.
  • Massimo 5 aggregazioni di metriche di serie temporali
  • Intervallo di tempo: la durata può essere al massimo di 14 giorni con data di inizio e data di fine deve essere compreso 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 delle statistiche di sicurezza sia l'API dei report di sicurezza restituiscono abusi e sicurezza relativa ai bot. statistiche, ma con le seguenti differenze:

  • L'API per le statistiche sulla sicurezza è progettata per Visualizzare le statistiche relative al traffico API recente. I dati dell'API per le statistiche di sicurezza risalgono a soli 14 giorni fa, ma puoi visualizzare le statistiche immediatamente quando invii una richiesta.

    Le statistiche sulla sicurezza sono visualizzate anche nella Visualizzazione delle metriche relative agli abusi nella UI di Apigee.

  • L'API Security Reporting è progettato per visualizzare statistiche per le operazioni a lunga esecuzione. Per utilizzare l'API Security Score, invii un job e visualizzi i risultati solo quando il job viene completato. I dati dell'API dei punteggi di sicurezza risalgono a un anno fa.