API-Whitelist

Einführung

Die Lucy-API arbeitet als RESTful-Webdienst. Daher können alle API-Anfragen in beliebiger Reihenfolge ausgeführt werden, ohne von der Abfolge abhängig zu sein.

Navigieren Sie zu Einstellungen -> Allgemeine Systemeinstellungen -> API-Whitelist

Hier müssen Sie die entfernten IP-Adressen angeben, die mit der API kommunizieren dürfen, um einen kontrollierten und sicheren Zugriff auf den Dienst zu gewährleisten.

Anforderungen

• Der Dienst verwendet ausschließlich JSON als Datenaustauschformat. Alle Antworten der API werden in JSON bereitgestellt, und es wird erwartet, dass die meisten Anforderungsparameter ebenfalls in JSON übermittelt werden.

• Jede an die API gesendete Anfrage muss einen "Content-Type"-Header enthalten, der auf "application/json" gesetzt ist, um die ordnungsgemäße Verarbeitung und Interpretation der Anfragedaten sicherzustellen.

• Alle Anfragen müssen strikt über das HTTPS-Protokoll erfolgen. Alle an die API gesendeten Anfragen mit einfachem HTTP werden vom Server abgelehnt.

Authentifizierung

Die Lucy-API verwendet JWT (JSON Web Tokens) zur Authentifizierung. Um Vorgänge zu starten, muss zunächst durch Senden einer Authentifizierungsanfrage ein Token angefordert werden. Dieser erste Schritt ist entscheidend, bevor Sie mit weiteren Anfragen fortfahren. Nachfolgend finden Sie Details zur Authentifizierungsanfrage:

• Erhalt des Tokens: Senden Sie eine Authentifizierungsanfrage an die Lucy-API. Die genauen Details dieser Anfrage, einschließlich des Endpunkts und der erforderlichen Anmeldedaten (typischerweise ein Benutzername und ein Passwort), sind in der API-Dokumentation beschrieben.

• Verwendung des Tokens: Sobald das Token erhalten wurde, sollte es für alle nachfolgenden API-Anfragen im HTTP-Header "Authorization" im Rahmen des "Bearer"-Schemas enthalten sein. Dieser Schritt ist unerlässlich, um Ihre Identität bei der API zu authentifizieren.

• Anfrageformat: Alle anderen Anfragen, abgesehen von der Authentifizierungsanfrage, müssen dieses Token enthalten. Ein Beispiel dafür, wie das Token in einen Anfrage-Header aufgenommen wird, ist wie folgt:

Authorization: Bearer <your_token_here>

Der Client sollte das aus der Authentifizierungsanfrage erhaltene JWT-Token lokal speichern und bis zu seinem Ablauf behalten. Das Ablaufdatum und die Uhrzeit des Tokens sind im Header des Tokens angegeben und bieten einen klaren Hinweis auf seinen gültigen Nutzungszeitraum.

Um die Struktur eines JWT-Tokens zu verstehen und auf Bibliotheken für den Umgang mit JWT in verschiedenen Programmiersprachen zuzugreifen, können Sie besuchen https://jwt.io/.

Ressourcen

Bei der Arbeit mit der Lucy-API beziehen sich "Ressourcen" auf die Daten, die Sie entweder aus der API abrufen oder die Objekte, die Sie über sie erstellen oder ändern. Die Struktur dieser Ressourcen bleibt unabhängig von der Art der von Ihnen ausgeführten Aktion gleich. Diese Einheitlichkeit stellt sicher, dass die Darstellung eines Objekts sich nicht ändert, egal ob Sie Informationen darüber abrufen oder es neu erstellen.

Nehmen Sie "campaigns" als Beispiel: Die Datenstruktur, die Sie erhalten, wenn Sie alle Kampagnen auflisten oder eine einzelne Kampagne abfragen, bleibt dieselbe wie die, die der Server erwartet, wenn Sie eine Anfrage zum Erstellen einer neuen Kampagne senden. Der Hauptunterschied liegt im Umgang mit Links. Bei POST- oder PUT-Vorgängen (Erstellen oder Aktualisieren von Ressourcen) erwartet der Server keine Links innerhalb des Anfragekörpers und ignoriert sie, wenn sie enthalten sind. Diese Links werden ausschließlich in GET-Anfragen verwendet, um Beziehungen zwischen Ressourcen darzustellen.

Um Beziehungen zu anderen vorhandenen Objekten im System zu definieren, wird empfohlen, ganzzahlige IDs zu verwenden. Dieser Ansatz vereinfacht den Zuordnungsprozess zwischen verschiedenen Ressourcen innerhalb der Lucy-API und sorgt für Klarheit und Konsistenz bei verschiedenen Vorgängen.

API-Rückgabelimit für Datensätze

Beim Abfragen von Lucy-API-Endpunkten, die eine Liste von Ressourcen zurückgeben, ist das Standardverhalten, maximal 100 Datensätze pro Anfrage zurückzugeben. Wenn Sie jedoch in einer einzelnen Anfrage mehr oder weniger Datensätze abrufen müssen, können Sie dies anpassen, indem Sie die LIMIT und OFFSET Anfrageparameter verwenden.

Die maximale Anzahl von Datensätzen, die Sie mit dem LIMIT Parameter anfordern können, ist "1000". Wenn Sie einen LIMIT Wert größer als 1000 angeben, gibt die API weiterhin maximal 1000 Datensätze zurück, um Leistung und Systemstabilität zu gewährleisten. Diese Begrenzung stellt sicher, dass die API Anfragen effizient verarbeiten kann, ohne die Reaktionsfähigkeit des Servers zu beeinträchtigen.

Um zu veranschaulichen, wie Sie die Anzahl der zurückgegebenen Datensätze anpassen können, betrachten Sie das folgende Beispiel:

GET /api/campaigns?sort=-created_at&offset=10&limit=10

In diesem Beispiel sort Parameter ordnet die Kampagnen nach ihrem Erstellungsdatum in absteigender Reihenfolge (-created_at). Der offset Parameter wird verwendet, um die ersten 10 Datensätze zu überspringen, sodass die Liste effektiv beim 11. Datensatz beginnt. Der limit Parameter begrenzt dann die Anzahl der zurückgegebenen Datensätze auf 10. Diese Konfiguration ist besonders nützlich, um Paginierung zu implementieren oder bestimmte Datensegmente aus der Lucy-API abzurufen.

Beispielverwendung

1. Authentifizieren, um ein Token zu erhalten:

   • Anfrage:

     POST /api/auth HTTP/1.1
     Host: phish.local
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"email":"[e-mail]","password":"123"}

   • Antwort:

     {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9..."}

     Verwenden Sie dieses Token im "Authorization"-Header für alle nachfolgenden Anfragen.

2. Eine Empfängergruppe erstellen:

   • Anfrage:

     PUT /api/recipient-groups/ HTTP/1.1
     Host: phish.local
     Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"name":"test recipient group"}

   • Antwort:

     {"recipient-group":{"id":262,"name":"test recipient group","usb_attack":false,"links":[{"rel":"self","href":"/api/recipient-groups/262"}]}}

3. Einen Empfänger zur Gruppe hinzufügen:

   • Anfrage:

     PUT /api/recipient-groups/262/recipients HTTP/1.1
     Host: phish.local
     Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"email":"[e-mail]","name":"Support Test"}

   • Antwort:

     {"recipient":{"email":"[e-mail]","phone":null,"name":"Support Test"}}

Diese Abfolge demonstriert die grundlegenden Vorgänge, um sich zu authentifizieren, eine Empfängergruppe zu erstellen und einen Empfänger mithilfe der API zur Lucy-Plattform hinzuzufügen. Denken Sie daran, das Token, die E-Mail-Adressen, Namen und andere Details bei diesen Anfragen durch Ihre tatsächlichen Daten zu ersetzen.

Detaillierte Dokumentation und Endpunkte

Jeder Lucy-Server enthält einen Swagger-Client, der Administratoren das Erkunden und Testen von Endpunkten ermöglicht. Um auf den Swagger-Client zuzugreifen, navigieren Sie zu Einstellungen -> Allgemeine Systemeinstellungen -> Abschnitt API-Whitelist und wählen Sie API-Dokumentation.

Ein Swagger-API-Client ist eine Softwarebibliothek oder ein Tool, das aus einer Swagger-Spezifikation generiert wird und dazu dient, die Kommunikation mit einer Web-API zu erleichtern, die durch diese Spezifikation beschrieben wird. Swagger, heute als OpenAPI bekannt, ist ein weit verbreitetes Framework für die API-Entwicklung und bietet eine Reihe von Tools zum Entwerfen, Erstellen, Dokumentieren und Nutzen von RESTful-Webdiensten.