Scopo
Cyber Guru offre la possibilità di acquisire le classifiche degli utenti e dei team presenti in piattaforma mediante una REST API che restituisce i dati in formato JSON, pronti per essere integrati in dashboard, portali o sistemi di reportistica del cliente.
L’automazione dell’acquisizione dei dati 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.
Ambito
Le informazioni si applicano alla piattaforma di Cyber Security Awareness Cyber Guru 2.0.
Prerequisiti
- Il cliente deve disporre delle risorse tecnologiche per poter chiamare REST API.
Procedura
Cyber Guru mette a disposizione due REST API:
Get token:
URL: 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 rankings:
URL: https://<host>/ext/report/rankings
Consente di ottenere le classifiche degli utenti e dei team della company. Per invocare l’API è necessario fornire il token ottenuto in precedenza come Bearer token.
L’API prende in ingresso i seguenti parametri (metodo GET):
| Parametro | Tipo | Obbligatorio | Descrizione |
| type | intero | Sì | 0 = utenti della company, 1 = team della company, 2 = utenti di uno specifico team |
| team | stringa | Solo se type = 2 | Nome del team di cui si vuole ottenere la classifica |
| limit | intero | No | Numero massimo di risultati per pagina (min: 1, max: 1000) |
| page | intero | No | Pagina di risultati da recuperare (usato insieme a limit) |
Esempi di response
Classifica utenti della company (type = 0):
{
"accounts": [
{ "position": "1", "firstname": "Mario", "lastname": "Rossi", "team": "Sales EMEA", "points": "36" },
{ "position": "2", "firstname": "Alessandro", "lastname": "Bianchi", "team": "IT Operations", "points": "32" }
]
}
Classifica team della company (type = 1):
{
"teams": [
{ "position": "1", "team": "Sales EMEA", "members": "23", "points": "31" },
{ "position": "2", "team": "IT Operations", "members": "34", "points": "26" }
]
}
Classifica utenti di uno specifico team (type = 2, es. team = IT Operations):
{
"accounts": [
{ "position": "1", "firstname": "Mario", "lastname": "Bianchi", "team": "IT Operations", "points": "36" },
{ "position": "2", "firstname": "Ciccio", "lastname": "Verdi", "team": "IT Operations", "points": "32" }
]
}
Response con paginazione:
Quando vengono utilizzati i parametri limit e page, la response include un oggetto pagination con le seguenti informazioni:
| Campo | Descrizione |
| current_page | Pagina corrente |
| per_page | Elementi per pagina |
| total_items | Totale elementi disponibili |
| total_pages | Totale pagine disponibili |
| has_next / has_prev | Indica se esiste una pagina successiva/precedente |
| next_page / prev_page | Numero della pagina successiva/precedente (null se non presente) |
| first_page / last_page | Prima e ultima pagina disponibile |
Errori
| Codice HTTP | Codice errore | Descrizione |
| 400 | EXT_1000 | Parametro di input non valido (il messaggio indica quale parametro) |
| 404 | EXT_1003 | Errore nel recupero dei dati |
| 422 | EXT_1007 | Il percorso (level_uuid) indicato non esiste |
| 422 | EXT_1008 | Il team indicato non esiste nella company |
| 500 | EXT_1001 | Token scaduto o non valido |
Cyber Guru è a disposizione per supportare il cliente nella fase di configurazione e di test su ambiente di staging e, a valle dell’esito positivo, in ambiente di produzione.