====== API & Webhook ======

===== Introduction =====

Kaduu consists of two plattforms:

  * Deepweb (https://deepweb.leak.center)
  * Control (https://control.leak.center)

Deepweb is used for live queries that can take up to 3 hours. Control is mainly DB driven. API access is currently only available for "Control". Control uses a REST API which you can reach via SSL. 

===== API Documentation =====

Please find two API documentations here: 
  * {{ ::kaduu-2.2-swagger-fixed.zip |}}
  * The{{ :kaduu-2.0.pdf | PDF documentation has}} some more details about authentication and filters.

Please note that Kaduu SaaS API is based on a REST/HTTPS protocol with JSON format. All endpoints except the
authentication expect the JSON input and Content-Type: application/json header provided with the
request. All endpoint results are in JSON format. Before using any other API calls, you should obtain an authentication token – it is required for all subsequent API calls. In order to obtain the token, you should send a POST request to the

https://app.leak.center/uaa/oauth/token URL with the following data:
Headers
Content-Type application/x-www-form-urlencoded
Form
client_id client-api
client_secret comfy-litigate-embargo-forelimb
grant_type password
username <your username>
password <your password>

All fields in form should be URL-encoded.

The server responds with a token in JSON format:
{
  "access_token": "<your token>",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "svc-saas",
  "jti": "fcea19dc-091c-4b58-901e-3e9bb8df162f"
}

The API consumer should copy the resulting access_token value from the response and use it in
Authorization header with Bearer scheme for all other requests:

Authorization: Bearer <your token>



===== Webhook =====

Please define your webhook under your account settings. You need to define "http" as a alerting method. The system will POST all new findings to that URL as a JSON list of alert objects. You may leave this field blank in order to disable alert notifications.

{{::webhook.png?900|}}


===== API Script for all endpoints =====


The customer has various options in Kaduu for accessing the query data:
  * Via dashboard: data can be displayed and then exported (CSV, XML, DOCX etc)
  * Via webhook
  * Via REST API
  * Via alerting (email)

The REST API allows you great flexibility in automation and integration into your existing processes and applications. In this chapter we illustrate how the API can be used with a customizable Python script which could assist you with few business use cases:

  * White labeled alerts: You use Kaduu to regularly provide end customers or specific people with email alerts on certain topics (e.g. leaked data). To do this, you want to use an email with your design, company name and structure and also send this via your infrastructure.
  * Ticketing System Integration: You want to integrate Kaduu into your existing environment and create tickets or incidents automatically in Splunk, Jira, Slack or similar systems.
  * Automated Output Parsing: You want to store all results for certain search queries daily in an easy-to-process format (CSV, XLS, etc.) locally in a folder of your choice for analysis and further processing.
  * Reduce Workload in Alerting: You want to save time when using Kaduu's email alerts: Instead of logging into the system for email alerts and researching the cause of the alerts, you want to receive the specific raw data of the alerts via email.

You can learn more in the {{ :readme.docx |readme.docx}} or {{ ::api_script.zip |download the python files}}.




===== API Script to find and extracts accounts in leaks =====

This script is designed to help users search through data leaks for specific information like email addresses and passwords. It automates the process of logging into the Leak Center's API service, where the leaks are stored. Once logged in, the script uses search criteria specified by the user (such as particular tags that might relate to the type of information they're interested in, e.g., "accounts") to find relevant data within the leaks.

The script handles several key steps:

  * Logging In: It starts by using a username and password to log into the API and get a security token. This token is necessary for making secure requests to the service.
  * Reading Input Data: It reads from various text files that contain the user's search terms, date ranges for when the data was leaked, and specific tags related to the leaks.
  * Searching Leaks: Using the provided search terms, the script sends a query to the API to find leaks that match the criteria.
  * Processing Results: Once it retrieves the data, the script filters through it to find and extract only those details that match the user's needs, saving the results in a text file for easy access.
  * Continued Searches: The script can handle multiple pages of results from the API, ensuring it captures all relevant data.


The script can be downloaded {{ ::new_script_2.zip |here}}. It uses:
  * auth.txt - your Kaduu email and pwd
  * DateRange.txt - the date range for the query. Could be for example "2020-01-01 TO *" or "2020-01-01 TO *2024-01-01"
  * input.txt - should contain your domain (like "example.com" - dont use a subdomain)
  * Tags.txt - by default "accounts"