Zweck
Cyber Guru bietet die Möglichkeit, die Ranglisten der Nutzer und Teams auf der Plattform über eine REST-API abzurufen. Die Daten werden im JSON-Format bereitgestellt und können direkt in Dashboards, Portale oder Reporting-Systeme des Kunden integriert werden.
Die Automatisierung der Datenabfrage hängt von den Prozessen und der Architektur des Kunden ab und kann daher nicht von Cyber Guru überwacht werden.
Diese Anleitung enthält die Vorgaben und Parameter für die Nutzung des Dienstes.
Geltungsbereich
Die Informationen gelten für die Cyber Security Awareness Plattform Cyber Guru 2.0.
Voraussetzungen
- Der Kunde muss über die technischen Ressourcen verfügen, um REST-APIs aufrufen zu können.
Vorgehensweise
Cyber Guru stellt zwei REST-APIs zur Verfügung:
Token abrufen:
URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Mit dieser API kann ein Autorisierungstoken abgerufen werden. Aufrufparameter (POST-Methode):
- client_id : ext-api
- client_secret : (wird von Cyber Guru bereitgestellt)
- grant_type : client_credentials
Ranglisten abrufen:
URL: https://<host>/ext/report/rankings
Hiermit können die Ranglisten der Nutzer und Teams des Unternehmens abgerufen werden. Für den API-Aufruf muss das zuvor erhaltene Token als Bearer-Token übergeben werden.
Die API erwartet folgende Parameter (GET-Methode):
| Parameter | Typ | Erforderlich | Beschreibung |
| type | Integer | Ja | 0 = Nutzer des Unternehmens, 1 = Teams des Unternehmens, 2 = Nutzer eines bestimmten Teams |
| team | String | Nur wenn type = 2 | Name des Teams, dessen Rangliste abgerufen werden soll |
| limit | Integer | Nein | Maximale Anzahl der Ergebnisse pro Seite (min: 1, max: 1000) |
| page | Integer | Nein | Ergebnisseite, die abgerufen werden soll (wird zusammen mit limit verwendet) |
Beispiele für Responses
Rangliste der Nutzer des Unternehmens (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" }
]
}
Rangliste der Teams des Unternehmens (type = 1):
{
"teams": [
{ "position": "1", "team": "Sales EMEA", "members": "23", "points": "31" },
{ "position": "2", "team": "IT Operations", "members": "34", "points": "26" }
]
}
Rangliste der Nutzer eines bestimmten Teams (type = 2, z. B. 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 mit Paginierung:
Wenn die Parameter limit und page verwendet werden, enthält die Response ein Pagination-Objekt mit folgenden Informationen:
| Feld | Beschreibung |
| current_page | Aktuelle Seite |
| per_page | Elemente pro Seite |
| total_items | Gesamtzahl der verfügbaren Elemente |
| total_pages | Gesamtzahl der verfügbaren Seiten |
| has_next / has_prev | Gibt an, ob es eine nächste/vorherige Seite gibt |
| next_page / prev_page | Nummer der nächsten/vorherigen Seite (null, falls nicht vorhanden) |
| first_page / last_page | Erste und letzte verfügbare Seite |
Fehler
| HTTP-Code | Fehlercode | Beschreibung |
| 400 | EXT_1000 | Ungültiger Eingabeparameter (die Nachricht gibt an, welcher Parameter betroffen ist) |
| 404 | EXT_1003 | Fehler beim Abrufen der Daten |
| 422 | EXT_1007 | Der angegebene Pfad (level_uuid) existiert nicht |
| 422 | EXT_1008 | Das angegebene Team existiert im Unternehmen nicht |
| 500 | EXT_1001 | Token abgelaufen oder ungültig |
Cyber Guru steht zur Verfügung, um den Kunden bei der Konfiguration und beim Testen in der Staging-Umgebung zu unterstützen und nach erfolgreichem Abschluss auch in der Produktionsumgebung zu begleiten.