Purpose
Cyber Guru provides the ability to gather information about phishing campaigns sent to users in order to monitor their behavior, through a REST API that returns a data set in JSON format.
Automating the acquisition of data provided by Cyber Guru depends on the client's processes and architecture, and for this reason cannot be managed by Cyber Guru.
This guideline contains the instructions and parameters for clients to call the service.
Scope
This information applies to the Cyber Security Awareness Cyber Guru 2.0 platform.
Prerequisites
The client must have the technological resources to call REST APIs at a frequency that meets their needs.
Procedure
Cyber Guru provides two REST APIs:
Get token
https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
This API allows you to obtain an authorization token.
Call parameters (POST method):
- client_id: ext-api
- client_secret: <provided by Cyber Guru>
- grant_type: client_credentials
Get phishing campaigns data
https://<...>/ext/phishing/campaigns
This API allows you to get the list of phishing campaigns that have targeted a specific company. By default, the data is not anonymized, and you can filter it by a specific time range and/or year.
To call this API, you must provide the token obtained from the previous API as a "Bearer token".
Method: GET
Input parameters:
- start_date: optional, format YYYY-MM-DD
- end_date: optional, format YYYY-MM-DD
- year: optional, format YYYY
- anon: optional, indicates whether to get anonymized data (1) or not (0)
Response:
The response contains a selected subset of the columns available in the phishing Excel report downloadable from the platform.
-
Response:
campaignName: campaign name/code,
templateId: template identifier,
templateName: template name,
template_type: type of template (email, sms, etc.),
subject: template subject (if present),
targetId: target identifier,
firstname: user first name,
lastname: user last name,
campaignType: description of the campaign type,
target_risk: description of the risk level associated with the user,
email: user email,
language: template language,
country: user country,
sent: date the template was sent,
open: date the template was opened,
clicked: indicates if a link in the template was clicked,
reported: indicates if the template was reported as phishing by the user,
submitted_data: date the report was submitted,
phished_device: type of device used,
active: can be 0 or 1,
There may be one or more user organizations (for example
Department: defense) shown as“key”:”value”pairs
Example output for a successful response
[
{
"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
}
]
Error Handling
Validation error (the message will dynamically indicate which input parameters are invalid)
{
"status": 400,
"error": {
"code": "EXT_1000",
"message": "The start date does not match the format Y-m-d."
}
}
Error if an internal call to retrieve company users fails for any reason
{
"status": 404,
"error": {
"code": "EXT_1002",
"message": "Users not found"
}
}
Error in case of query issues
{
"status": 404,
"error": {
"code": "EXT_1003",
"message": "An error occur retrieving data"
}
}
Error in case of issues with the Localization service
{
"status": 404,
"error": {
"code": "EXT_1004",
"message": "Unexpected error processing data in the requested or preset language"
}
}
Generic server-side error
{
"status": 500,
"error": {
"code": "EXT_1001",
"message": "Unable to retrieve data. Token expired or not valid"
}
}