Scopo
Cyber Guru offre la possibilità di acquisire informazioni sulle campagne di phishing inviate agli utenti per monitorarne il comportamento, mediante una REST API che restituisce un set di dati in formato JSON.
L'automazione dell'acquisizione dei dati forniti da Cyber Guru dipende da processi e architetture del cliente e per questo motivo non può essere presidiata da Cyber Guru.
La presente linea guida contiene le direttive e i parametri per l'invocazione del servizio da parte del cliente.
Ambito
Le informazioni si applicano alla piattaforma di Cyber Security Awareness Cyber Guru 2.0
Prerequisiti
Il cliente deve avere le risorse tecnologiche per poter chiamare REST API con una frequenza adeguata alle proprie esigenze.
Procedura
Cyber Guru mette a disposizione due REST API:
Get token
https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Questa API consente di ottenere un token di autorizzazione.
Parametri di chiamata (metodo POST):
- client_id: ext-api
- client_secret: <fornito da Cyber Guru>
- grant_type: client_credentials
Get phishing campaigns data
https://<...>/ext/phishing/campaigns
Questa API consente di ottenere la lista delle campagne di phishing di cui è stata oggetto una specifica company. I dati sono per default non anonimizzati ed è possibile filtrarli per un certo intervallo temporale e/o anno.
Per poter invocare l'API è necessario fornire il token ottenuto nella precedente API come "Bearer token".
Metodo: GET
Parametri di input:
- start_date: opzionale, formato YYYY-MM-DD
- end_date: opzionale, formato YYYY-MM-DD
- year: opzionale, formato YYYY
- anon: opzionale, indica se ottenere i dati anonimizzati (1) o meno (0)
Response:
La response contiene un sottoinsieme selezionato delle colonne presenti nel report phishing Excel scaricabile da piattaforma
-
Response:
campaignName: nome/codice campagna,
templateId: identificativo del template,
templateName: nome del template,
template_type: tipologia del template (email, sms, etc..),
subject: oggetto del template (se presente),
targetId: identificativo del target,
firstname: nome utente,
lastname: cognome utente,
campaignType: descrizione della tipologia di campagna,
target_risk: descrizione del livello di rischio associato all’utente,
email: email utente,
language: lingua template,
country: paese utente,
sent: data invio del template,
open: data apertura del template,
clicked: indica se è avvenuto il click su link inserito nel template,
reported: indica se è un template stato segnalato come phishing dall’utente,
submitted_data: data in cui è avvenuta la segnalazione,
phished_device: tipologia del device da,
active: assume i valori 0/1,
Possibile presenza di una o più organizzazioni dell’utente (ad esempio
Department: difesa) distinte in coppie“chiave”:”valore”
Esempio di output in caso di risposta OK
[
{
"campaignName": "C-01",
"templateId": "1F1BFF1A305311ED9CCBA85E4535D801",
"templateName": "ESER - Poste",
"template_type": "email",
"subject": "Controllo credenziali d’accesso al portale",
"targetId": "4C51AC920AE74A2BA64AE92E1A11A1B0",
"firstname": "******",
"lastname": "******",
"campaignType": "Ordinary",
"target_risk": "Strong",
"email": "ba3fab89-2a30-11ee-96e0-02ad84ed1332@deletedtarget.xxx",
"language": "it",
"country": "IT",
"sent": "2023-06-20 15:35:34",
"open": null,
"clicked": null,
"reported": null,
"submitted_data": null,
"phished_device": null,
"active": 0
},
{
"campaignName": "C-01",
"templateId": "1F0A6E0D305311ED9CCBA85E4535D801",
"templateName": "ESER - iPhone",
"template_type": "email",
"subject": "Il suo ordine è stato spedito",
"targetId": "FDD947C5D85C45AEACC63BB6A1B4328E",
"firstname": "******",
"lastname": "******",
"campaignType": "Ordinary",
"target_risk": "Strong",
"email": "2bf3996d-5085-11ee-96e0-02ad84ed1332@deletedtarget.xxx",
"language": "it",
"country": "AL",
"sent": "2023-06-20 15:35:34",
"open": null,
"clicked": null,
"reported": null,
"submitted_data": null,
"phished_device": null,
"active": 0,
"Organleon52": "org1"
},
{
"campaignName": "C-01",
"templateId": "1EDB5763305311ED9CCBA85E4535D801",
"templateName": "PayPal_1",
"template_type": "email",
"subject": "1 Nuovo Messaggio: Account PayPal",
"targetId": "C5A9F8B7E8AE47488DF6EFE73012129C",
"firstname": "Sara",
"lastname": "Smith",
"campaignType": "Ordinary",
"target_risk": "Strong",
"email": "sara.s@example.it",
"language": "it",
"country": null,
"sent": "2023-06-20 15:35:35",
"open": null,
"clicked": null,
"reported": null,
"submitted_data": null,
"phished_device": null,
"active": 0
}
]
Gestione Errori
Errore di validazione (indicherà dinamicamente nel messaggio quali parametri di input non sono validi)
{
"status": 400,
"error": {
"code": "EXT_1000",
"message": "The start date does not match the format Y-m-d."
}
}
Errore in caso si interrompa per un qualsiasi problema una chiamata interna per recuperare gli utenti della company
{
"status": 404,
"error": {
"code": "EXT_1002",
"message": "Users not found"
}
}
Errore in caso di problemi nella query
{
"status": 404,
"error": {
"code": "EXT_1003",
"message": "An error occur retrieving data"
}
}
Errore in caso di problematiche relative al servizio di Localization
{
"status": 404,
"error": {
"code": "EXT_1004",
"message": "Unexpected error processing data in the requested or preset language"
}
}
Errore server side generico
{
"status": 500,
"error": {
"code": "EXT_1001",
"message": "Unable to retrieve data. Token expired or not valid"
}
}