Propósito
Cyber Guru ofrece la posibilidad de obtener los rankings de usuarios y equipos presentes en la plataforma a través de una REST API que devuelve los datos en formato JSON, listos para ser integrados en dashboards, portales o sistemas de reportes del cliente.
La automatización de la adquisición de datos depende de los procesos y arquitecturas del cliente y, por este motivo, no puede ser gestionada por Cyber Guru.
Esta guía contiene las directrices y los parámetros para invocar el servicio.
Ámbito
La información se aplica a la plataforma de Cyber Security Awareness Cyber Guru 2.0.
Requisitos previos
- El cliente debe contar con los recursos tecnológicos necesarios para poder consumir REST API.
Procedimiento
Cyber Guru pone a disposición dos REST API:
Obtener token:
URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Esta API permite obtener un token de autorización. Parámetros de la petición (método POST):
- client_id : ext-api
- client_secret : (proporcionado por Cyber Guru)
- grant_type : client_credentials
Obtener rankings:
URL: https://<host>/ext/report/rankings
Permite obtener los rankings de usuarios y equipos de la empresa. Para invocar la API es necesario proporcionar el token obtenido previamente como Bearer token.
La API recibe los siguientes parámetros (método GET):
| Parámetro | Tipo | Obligatorio | Descripción |
| type | entero | Sí | 0 = usuarios de la empresa, 1 = equipos de la empresa, 2 = usuarios de un equipo específico |
| team | cadena | Solo si type = 2 | Nombre del equipo del que se desea obtener el ranking |
| limit | entero | No | Número máximo de resultados por página (mín: 1, máx: 1000) |
| page | entero | No | Página de resultados a recuperar (se usa junto con limit) |
Ejemplos de respuesta
Ranking de usuarios de la empresa (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" }
]
}
Ranking de equipos de la empresa (type = 1):
{
"teams": [
{ "position": "1", "team": "Sales EMEA", "members": "23", "points": "31" },
{ "position": "2", "team": "IT Operations", "members": "34", "points": "26" }
]
}
Ranking de usuarios de un equipo específico (type = 2, ej. 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" }
]
}
Respuesta con paginación:
Cuando se utilizan los parámetros limit y page, la respuesta incluye un objeto pagination con la siguiente información:
| Campo | Descripción |
| current_page | Página actual |
| per_page | Elementos por página |
| total_items | Total de elementos disponibles |
| total_pages | Total de páginas disponibles |
| has_next / has_prev | Indica si existe una página siguiente/anterior |
| next_page / prev_page | Número de la página siguiente/anterior (null si no existe) |
| first_page / last_page | Primera y última página disponible |
Errores
| Código HTTP | Código de error | Descripción |
| 400 | EXT_1000 | Parámetro de entrada no válido (el mensaje indica cuál) |
| 404 | EXT_1003 | Error al recuperar los datos |
| 422 | EXT_1007 | La ruta (level_uuid) indicada no existe |
| 422 | EXT_1008 | El equipo indicado no existe en la empresa |
| 500 | EXT_1001 | Token caducado o no válido |
Cyber Guru está disponible para apoyar al cliente en la fase de configuración y pruebas en el entorno de staging y, tras un resultado positivo, en el entorno de producción.