Propósito
Cyber Guru ofrece la posibilidad de obtener información sobre las campañas de phishing enviadas a los usuarios para monitorear su comportamiento, a través de una REST API que devuelve un conjunto de datos en formato JSON.
La automatización de la adquisición de los datos proporcionados por Cyber Guru depende de los procesos y la arquitectura del cliente, por lo que no puede ser gestionada por Cyber Guru.
Esta guía contiene las directrices y los parámetros para que el cliente invoque el servicio.
Ámbito
La información se aplica a la plataforma de Concienciación en Ciberseguridad Cyber Guru 2.0
Requisitos previos
El cliente debe contar con los recursos tecnológicos necesarios para poder llamar a la REST API con la frecuencia que requiera.
Procedimiento
Cyber Guru pone a disposición dos REST API:
Obtener token
https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Esta API permite obtener un token de autorización.
Parámetros de la llamada (método POST):
- client_id: ext-api
- client_secret: <proporcionado por Cyber Guru>
- grant_type: client_credentials
Obtener datos de campañas de phishing
https://<...>/ext/phishing/campaigns
Esta API permite obtener la lista de campañas de phishing a las que ha estado expuesta una empresa específica. Los datos, por defecto, no están anonimizados y es posible filtrarlos por un intervalo de fechas y/o año.
Para poder invocar la API es necesario proporcionar el token obtenido en la API anterior como "Bearer token".
Método: GET
Parámetros de entrada:
- start_date: opcional, formato YYYY-MM-DD
- end_date: opcional, formato YYYY-MM-DD
- year: opcional, formato YYYY
- anon: opcional, indica si se obtienen los datos anonimizados (1) o no (0)
Respuesta:
La respuesta contiene un subconjunto seleccionado de las columnas presentes en el informe de phishing en Excel descargable desde la plataforma
-
Respuesta:
campaignName: nombre/código de la campaña,
templateId: identificador de la plantilla,
templateName: nombre de la plantilla,
template_type: tipo de plantilla (email, sms, etc.),
subject: asunto de la plantilla (si está presente),
targetId: identificador del destinatario,
firstname: nombre del usuario,
lastname: apellido del usuario,
campaignType: descripción del tipo de campaña,
target_risk: descripción del nivel de riesgo asociado al usuario,
email: correo electrónico del usuario,
language: idioma de la plantilla,
country: país del usuario,
sent: fecha de envío de la plantilla,
open: fecha de apertura de la plantilla,
clicked: indica si se hizo clic en el enlace incluido en la plantilla,
reported: indica si la plantilla fue reportada como phishing por el usuario,
submitted_data: fecha en la que se realizó el reporte,
phished_device: tipo de dispositivo desde el que se realizó la acción,
active: puede tener los valores 0/1,
Puede haber una o más organizaciones del usuario (por ejemplo
Department: defensa) diferenciadas en pares“clave”:”valor”
Ejemplo de salida en caso de respuesta 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
}
]
Gestión de errores
Error de validación (indicará dinámicamente en el mensaje qué parámetros de entrada no son válidos)
{
"status": 400,
"error": {
"code": "EXT_1000",
"message": "The start date does not match the format Y-m-d."
}
}
Error en caso de que se interrumpa por cualquier motivo una llamada interna para recuperar los usuarios de la empresa
{
"status": 404,
"error": {
"code": "EXT_1002",
"message": "Users not found"
}
}
Error en caso de problemas en la consulta
{
"status": 404,
"error": {
"code": "EXT_1003",
"message": "An error occur retrieving data"
}
}
Error en caso de problemas relacionados con el servicio de Localización
{
"status": 404,
"error": {
"code": "EXT_1004",
"message": "Unexpected error processing data in the requested or preset language"
}
}
Error genérico del lado del servidor
{
"status": 500,
"error": {
"code": "EXT_1001",
"message": "Unable to retrieve data. Token expired or not valid"
}
}