Aller au contenu principal
Connexion
Deutsch English (United States) Español Italiano

API Cyber Guru Phishing

Objectif


Cyber Guru offre la possibilité d’obtenir des informations sur les campagnes de phishing envoyées aux utilisateurs afin de surveiller leur comportement, via une API REST qui renvoie un ensemble de données au format JSON.
L’automatisation de la récupération des données fournies par Cyber Guru dépend des processus et de l’architecture du client et, pour cette raison, ne peut pas être gérée par Cyber Guru.
Ce guide contient les directives et les paramètres pour l’appel du service par le client.


Périmètre
Les informations s’appliquent à la plateforme de Cyber Security Awareness Cyber Guru 2.0


Prérequis
Le client doit disposer des ressources technologiques nécessaires pour pouvoir appeler l’API REST à une fréquence adaptée à ses besoins.


Procédure
Cyber Guru met à disposition deux API REST :
Get token
https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token 


Cette API permet d’obtenir un jeton d’autorisation.


Paramètres d’appel (méthode POST) :

  • client_id : ext-api
  • client_secret : <fourni par Cyber Guru>
  • grant_type : client_credentials

Get phishing campaigns data


https://<...>/ext/phishing/campaigns


Cette API permet d’obtenir la liste des campagnes de phishing auxquelles une entreprise spécifique a été exposée. Par défaut, les données ne sont pas anonymisées et il est possible de les filtrer par intervalle de dates et/ou par année.
Pour appeler l’API, il est nécessaire de fournir le jeton obtenu via l’API précédente comme « Bearer token ».
Méthode : GET
Paramètres d’entrée :

  • start_date : optionnel, format AAAA-MM-JJ
  • end_date : optionnel, format AAAA-MM-JJ
  • year : optionnel, format AAAA
  • anon : optionnel, indique si les données doivent être anonymisées (1) ou non (0)


Réponse :

La réponse contient un sous-ensemble sélectionné des colonnes présentes dans le rapport phishing Excel téléchargeable depuis la plateforme

  • Réponse :

    • campaignName : nom/code de la campagne,

    • templateId : identifiant du modèle,

    • templateName : nom du modèle,

    • template_type : type de modèle (email, sms, etc.),

    • subject : objet du modèle (si présent),

    • targetId : identifiant de la cible,

    • firstname : prénom de l’utilisateur,

    • lastname : nom de famille de l’utilisateur,

    • campaignType : description du type de campagne,

    • target_risk : description du niveau de risque associé à l’utilisateur,

    • email : email de l’utilisateur,

    • language : langue du modèle,

    • country : pays de l’utilisateur,

    • sent : date d’envoi du modèle,

    • open : date d’ouverture du modèle,

    • clicked : indique si un clic a été effectué sur un lien du modèle,

    • reported : indique si le modèle a été signalé comme phishing par l’utilisateur,

    • submitted_data : date à laquelle le signalement a été effectué,

    • phished_device : type d’appareil utilisé,

    • active : prend les valeurs 0/1,

    • Possibilité de présence d’une ou plusieurs organisations de l’utilisateur (par exemple Department: défense) distinctes en paires “clé”:”valeur”

 

Exemple de sortie en cas de réponse 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
    }
]

 

Gestion des erreurs

Erreur de validation (le message indiquera dynamiquement quels paramètres d’entrée ne sont pas valides)

{
    "status": 400,
    "error": {
        "code": "EXT_1000",
        "message": "The start date does not match the format Y-m-d."
    }
}

Erreur si un appel interne pour récupérer les utilisateurs de la société est interrompu pour un quelconque problème

{
    "status": 404,
    "error": {
        "code": "EXT_1002",
        "message": "Users not found"
    }
}

Erreur en cas de problème lors de la requête

{
    "status": 404,
    "error": {
        "code": "EXT_1003",
        "message": "An error occur retrieving data"
    }
}

Erreur en cas de problème lié au service de localisation

{
    "status": 404,
    "error": {
        "code": "EXT_1004",
        "message": "Unexpected error processing data in the requested or preset language"
    }
}

 

Erreur serveur générique

{
    "status": 500,
    "error": {
        "code": "EXT_1001",
        "message": "Unable to retrieve data. Token expired or not valid"
    }
}