Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza documentazione di Apigee Edge.
Oltre all'utilizzo report sulla sicurezza nella UI di Apigee puoi anche accedere a tutte le funzionalità relative ai report sulla sicurezza tramite l'API per i report sulla sicurezza. In questa sezione viene descritto come utilizzare l'API per i report sulla sicurezza.
Parametri nelle chiamate API di esempio
Le seguenti sezioni forniscono esempi di chiamate API che utilizzano i report di sicurezza tramite Google Cloud CLI o tramite l'API Compute Engine. Le chiamate API contengono i seguenti parametri:
- ORG è la tua organizzazione.
- ENV è l'ambiente in cui vuoi calcolare il report.
- ENVGROUP è un gruppo di ambienti contenente l'ambiente.
- REPORT_ID è l'ID report restituito da una chiamata a crea un report sulla sicurezza.
$TOKEN
è la variabile di ambiente per un Token di accesso OAuth.timeRange
è l'intervallo di tempo del report.
Crea un report sulla sicurezza
Per creare un report sulla sicurezza, inserisci un comando simile al 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
. Viene conteggiato il numero di indirizzi IP distinti che sono stati identificate come fonti di bot.Funzione di aggregazione:
count_distinct
bot_traffic
. Il numero totale di richieste da indirizzi IP che sono le fonti dei bot.Funzione di aggregazione:
sum
Consulta Metriche e funzioni di aggregazione.
- Dimensione:
ax_resolved_client_ip
. Questo raggruppa il conteggio dei bot nel report per all'indirizzo IP dell'origine.Consulta la sezione Dimensioni.
- Filtro:
environment
. - groupByTimeUnit:
minute
- Intervallo di tempo:
last7days
. Vedi Intervallo di tempo.
Tieni presente che questa chiamata API restituisce lo stesso report del 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
nei seguenti modi:
- Specifica per quanto tempo deve essere esteso 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
siaend
devono essere nel passato e possono essere al massimo 1 anno prima della data presente, quando crei il report.
Esempio di risposta
La query precedente restituisce una risposta come la 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 del report, che puoi utilizzare per scaricare il report una volta completato.
Nell'esempio precedente, l'ID report è
3964675e-9934-4398-bff5-39dd93a67201
. "state"
: lo stato del job di segnalazione, che può essere uno dei seguenti:enqueued
: il job di report è stato appena creato, ma non è ancora in esecuzione.running
: il job di report è in esecuzione.completed
: il job di segnalazione è stato completato. In questa fase, puoi visualizzare il report.expired
: il job di segnalazione è scaduto e non puoi più visualizzarlo.
Visualizzare lo stato del report
Per visualizzare 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 e lo stato attuale
del report. In questo esempio, lo stato è "completed"
, per cui 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.
Questo restituisce un file contenente il report, il cui nome è nel formato
OfflineQueryResult-{ID}.zip
. Per visualizzare il report:
- Decomprimi
OfflineQueryResult-{ID}.zip
. - Inserisci
gzip -d QueryResults-{ID}*.json.gz
. - Inserisci
cat QueryResults-{ID}*.json
di Google.
Esempio di traffico generato da 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 dagli indirizzi IP che sono state identificate come origini bot, a intervalli di un minuto.Consulta Metriche e funzioni di aggregazione.
Dimensione:
bot_reason
.bot_reason
può essere una qualsiasi combinazione regole di rilevamento per i bot. Quando viene rilevato un bot,bot_reason
è costituito da: sottoinsieme di regole di rilevamento corrispondenti al modello di traffico del bot.Consulta la sezione Dimensioni.
- Filtro:
environment
. - groupByTimeUnit:
minute
- Intervallo di tempo:
last7days
Tieni presente che questa chiamata API restituisce lo stesso report del Esempio di report sugli indirizzi IP dei bot creato utilizzando la UI di Apigee.
Ritardo dei dati di rilevamento bot
Il rilevamento dei bot ha un ritardo di elaborazione medio di circa 15-20 minuti.
Creare un report di sicurezza per un gruppo di ambienti
Utilizzando l'API Security Reporting, puoi creare un report per i dati di un gruppo di ambienti (piuttosto che su un semplice ambiente). Per farlo, inserisci un comando simile al 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 verifica che il modello di query, Query.json
, contenga la riga seguente:
"envgroup_hostname": "ENVGROUP"
dove ENVGROUP è il nome di un gruppo di ambienti che contiene l'ambiente. Puoi trovare il nome del gruppo di ambienti nella 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 aggregazionesum
. - Le API Report a livello di gruppo di ambienti non supportano le dimensioni
bot_reason
oincident_id
, ma supportano tutte le altre dimensioni per i report sulla sicurezza.
Visualizzare lo stato del report
Per visualizzare lo stato di un report, inserisci un comando simile al 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"
Restituisce un riepilogo della richiesta di report e il relativo stato corrente. Ecco un esempio di risposta:
{ "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 simile al 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"
Questo restituisce un file contenente il report, il cui nome è nel formato
OfflineQueryResult-{ID}.zip
. Per visualizzare il report:
- Decomprimi
OfflineQueryResult-{ID}.zip
. - Inserisci
gzip -d QueryResults-{ID}*.json.gz
. - Inserisci
cat QueryResults-{ID}*.json
di Google.
Metriche e funzioni di aggregazione
Puoi utilizzare le seguenti metriche e funzioni di aggregazione, che consentono di calcolare statistiche da una metrica per un report.
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 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: |
sum |
response_size |
Dimensioni del payload della risposta restituito in byte. | sum , avg , min , max |
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 |
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 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
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 di sicurezza
Vedi Limitazioni dei report di sicurezza.