Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Oltre a utilizzare i report di sicurezza nell'interfaccia utente di Apigee, puoi accedere a tutte le funzionalità dei report sulla sicurezza tramite l'API dei report sulla sicurezza. Questa sezione descrive come utilizzare l'API Security Reports.
Parametri nelle chiamate API di esempio
Le seguenti sezioni forniscono esempi di chiamate API che utilizzano l'API per i report di sicurezza. Le chiamate API contengono i seguenti parametri:
- ORG è la tua organizzazione.
- ENV è l'ambiente in cui vuoi che venga calcolato il report.
- ENVGROUP è un gruppo di ambienti contenente l'ambiente.
- REPORT_ID è l'ID report restituito da una chiamata per creare un report sulla sicurezza.
$TOKEN
è la variabile di ambiente per un token di accesso OAuth.timeRange
è l'intervallo di tempo per il report.
Creare un report sulla sicurezza
Per creare un report di 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 contiene i seguenti parametri:
- Metriche:
bot
. Viene conteggiato 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 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 il numero di bot nel report in base all'indirizzo IP della loro origine.Consulta la sezione Dimensioni.
- Filtro:
environment
. - GroupByTimeUnit:
minute
- intervallo di tempo:
last7days
. Consulta Intervallo di tempo.
Tieni presente che questa chiamata API restituisce lo stesso report dell'esempio del report sugli indirizzi IP dei bot creato utilizzando l'interfaccia utente di Apigee.
Intervallo di tempo
L'intervallo di tempo per il report. Puoi impostare il campo timeRange
in uno dei seguenti modi:
- Specifica l'intervallo di tempo nel quale deve essere esteso il report. Le opzioni sono:
"timeRange": "{last60minutes/last24hours/last7days}"
- Specifica un'ora di inizio e un'ora di fine per il report nel seguente formato:
"timeRange": { "start": "YYYY-MM-DDT00:00:00Z", "end": "YYYY-MM-DDT00:00:00Z" }
Entrambi
start
eend
devono essere nel passato e possono risalire al massimo a un 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 recuperarlo una volta completato.
Nell'esempio riportato sopra, l'ID report è
3964675e-9934-4398-bff5-39dd93a67201
. "state"
: lo stato del job relativo al 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 di segnalazione è stato completato. In questa fase, puoi visualizzare il report.expired
: il job di report è scaduto e non puoi più visualizzare il report.
Visualizzare lo stato del report
Per conoscere lo stato di una segnalazione, 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"
, pertanto 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 report
Per scaricare il report sulla sicurezza, invia una richiesta simile alla 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.
Verrà restituito 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
Esempio di traffico generato da bot
Nell'esempio seguente viene creato un report relativo a bot_traffic
:
{ "dimensions": [ "bot_reason" ], "metrics": [ { "aggregation_function": "sum", "name": "bot_traffic" } ], "groupByTimeUnit": "minute", "timeRange": "last7days" }
La query contiene i seguenti parametri:
Metrica:
bot_traffic
. Questo è il numero totale di richieste da indirizzi IP 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 corrispondenti al pattern 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 dell'esempio del report sugli indirizzi IP dei bot creato utilizzando l'interfaccia utente di Apigee.
Ritardo dati rilevamento bot
Il rilevamento dei bot ha un ritardo di elaborazione di circa 15-20 minuti in media.
Creare un report sulla sicurezza per un gruppo di ambienti
Con l'API Security Reports, puoi creare un report per i dati di un gruppo di ambienti (anziché solo per un 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 assicurati 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. Per trovare il nome del gruppo di ambienti nell'interfaccia utente di Apigee, vai ad Amministratore > Ambienti > Gruppi.
Note:
- Le API report a livello di gruppo di ambiente supportano solo la metrica
message_count
con la funzione di aggregazionesum
. - Le API report a livello di gruppo di ambiente 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"
Viene restituito un riepilogo della richiesta di report e lo stato corrente del report. 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 di 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"
Verrà restituito 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
Metriche e funzioni di aggregazione
Per un report, puoi utilizzare le seguenti metriche e funzioni di aggregazione, che calcolano le statistiche da una metrica, per un report.
Metrica | Descrizione | Aggregation function |
---|---|---|
bot |
Il numero di indirizzi IP distinti per i bot rilevati a intervalli di un minuto. | count_distinct |
bot_traffic |
Il numero di messaggi dagli indirizzi IP dei bot rilevati a 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 di risposta restituito in byte. | sum , avg , min , max |
bot_first_detected |
Data e ora del primo rilevamento del bot. 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 consentono di raggruppare i valori delle metriche in base a sottoinsiemi di dati correlati. 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 corrispondenti al modello di traffico del bot. |
incident_id (anteprima) |
L'UUID di un incidente di sicurezza, restituito da una chiamata all'API Incidents. Consulta Esempio: ottieni i dettagli o un incidente specifico. |
security_action |
L'azione di sicurezza. I possibili valori 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 per un'azione di sicurezza con flag. |
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 relative ai report sulla sicurezza
Vedi Limitazioni dei report sulla sicurezza.