Presentation

This API provides a simple and powerful REST API to request our databases and integrate your results into your application or script. This documentations contains information on all endpoints and how you can interact whith them.

Only python client is officialy support for the API.

Authentication

Every endpoint need you to be authenticated with an API key. You can setup your API Key in your profile page. API is available only for users with active paid plan.

Every request should have a X-Api-Key header. Your secret API key should be passed as the value.

In case of authentification fails, an error will be raised with HTTP status 403.

Errors

All error are send with HTTP status code corresponding.

The body contend in case of error include a human readable message and a code identifier.


"error": {
	"message":"Wrong API Key.",
    "code":"authent_wrongapikey"
}
Result format

All result are JSON containing a list of result. This list will be in data field.

In some case JSON can also avec a warnings field, containing a list of human readable messages.


{
    "data":[],
    "warnings":[]"
}
GET dashboards

Many endpoints requires dashboard/project id. This ID could be retrieved using this endpoint.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboards

Fields

Field Type Description
id int Uniq ID of the dashboard.
name string Name of the dashboard. Can be edited in WebUI.

Result


{
  "data": [
    {
      "id": 1,
      "name": "My Dashboard"
    }
  ]
}
GET dashboard/{id}

This endpoint gives stats of your dashboard. Informations are similar to dasboard view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1

Fields

Field Type Description
server int Number of distinct IP address in the dashboard.
domain int Number of domains in the dashboard.
service int Number of open ports in the dashboard.
alert int Total of alerts in the dashboard.
hacked int Number of server reported has hacked by someone.
vulnerability int Number of server with known vulnerability.
leak int Number of distinct leaks (email:password) related to domains in dashboard
filedisclosure int Number of server reported has hacked by someone.
weakservice int Number of misconfigured services identified by our system.
proxy int Number of proxy identified in the dashboard.
tornode int Number of tor node identified in the dashboard.
onion int Number onion site in the dashboard.
blacklist int Number blacklist reports in the dashboard.
phishingurl int Number phishing reports in the dashboard.
ssl int Number of SSL errors in the dashboard.
paste int Number of paste (such as Pastebin) in the dashboard.
warez int Number of alerts relating to warez (torrent ...) in the dashboard.
repository int Number of repository identified in the dashboard.
social_networks int Number of social network account in the dashboard.
ids int Number of id (Adsense, GoogleAnalytics ...) found in the dashboard.

Result


{
  "data": [
    {
      "alert": 14,
      "domain": 121,
      "phishingurl": 4,
      "server": 93,
      "service": 61
    }
  ]
}
DELETE dashboard/{id}

Calling this endpoint will delete the dashboard. This action can be canceled.

If resources are still running or waiting, an 400 error will be raised.

Request

curl -X DELETE -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1

Result


{
  "data": []
}
GET dashboard/{id}/details

This endpoint gives detailed view of your dashboard. Informations are similar to details view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/details

Fields

Field Type Description
id string Server uniq ID.
ip string Server IP address.
in_src boolean Flag indicating if IP have been explicitly search.
bookmark boolean Flag indicating if the server is bookmarked in WebUI.
country_code string Country code based to Whois.
country_name string Country name based on Whois.
whois_as int AS number based on Whois.
whois_name string IP range name based on whois.
whois_organisation string Organisation name based on Whois.
whois_range string IP range based on Whois.
geo_city string City name based on whois.
geo_lat float Latitude of the server position.
geo_long string Longitude of the server position.
cloudflare boolean Flag indicating if the server IP is part of Cloudflare IP range..
domains list List of domains linked to this server.
alerts list List of alerts for this server.
leaks list List of leaks related to this server.
services list List of open ports on this server.
social_networks list List of social newtork accounts linked to domains on this server.
ids list List of ID linked to domains on this server.
risk int Compromise risk (rang 1-5).

Result


{
  "data": [
    {
      "id": "6465ec74397c9126916786bbcd6d7601",
      "ip": "1.2.3.4",
      "in_src": false,
      "bookmark": false,
      "country_code": "us",
      "country_name": "United States",
      "whois_as": 1234,
      "whois_name": "Yuleak Test AS",
      "whois_organisation": "Yuleak-1234 - Yuleak Company, US",
      "whois_range": "1.2.3.4/26",
      "geo_city": "Paris",
  	  "geo_lat": 48.85,
      "geo_long": 2.34,
      "cloudflare": false,
	  "risk": 3,
      "domains": [
        {
          "id": "31743d8c4d6041a9ac045cebe18398f8",
  	      "parent": "6465ec74397c9126916786bbcd6d7601",
          "in_src": false,
          "tags": [
            "wordpress"
          ],
          "value": "blog.yuleak.com",
		  "risks": 0,
	      "screenshot": "https://screen.yuleak.com/token/blog.yuleak.com.png"
        }
      ],
      "alerts": [
        {
          "id": "db0176c793d6cb29bf1bf62e6094293f",
	      "parent": "31743d8c4d6041a9ac045cebe18398f8",
          "date": "2019-04-26T08:47:16.600701",
	      "first_seen": "2019-04-26T08:47:16.600701",
          "type": "ssl",
          "value": "Expired on 2018-03-21",
	      "risk": 3
        }
	  ],
      "leaks": [
        {
	      "id": "4ee645a91d1aec4465428ed6b69e2747",
	      "parent": "31743d8c4d6041a9ac045cebe18398f8",
          "date": "2019-04-26T08:47:16.600701",
	      "first_seen": "2019-04-26T08:47:16.600701",
          "email": "[email protected]",
          "password": "******",
	      "risk": 4
        }
      ],
      "services": [
        {
	      "id": "bdac43f9a043eedacb2fea690a55b08b",
	      "parent": "6465ec74397c9126916786bbcd6d7601",
          "date": "2019-04-26T08:47:16.600701",
	      "first_seen": "2019-04-26T08:47:16.600701",
          "name": "OpenSSH",
          "port": 22,
          "protocol": "tcp",
          "version": "7.2p2",
          "weak": false,
	      "risk": 0
        }
      ],
	  "social_networks": [
	    {
	      "id": "a66b724df70b072c6681ef1b00547563",
	      "parent": "31743d8c4d6041a9ac045cebe18398f8",
	      "date": "2019-04-26T08:47:16.600701",
	      "first_seen": "2019-04-26T08:47:16.600701",
	      "login": "YuleakDemo",
	      "plateform": "twitter",
		  "icon": "fa-twitter",
	      "risk": 0,
	      "link": "https://www.twitter.com/YuleakDemo"
	    }
	  ],
	  "ids": [
	    {
	      "id": "efd12c4eb0b3b2b28086dd44210cec9f",
	      "parent": "31743d8c4d6041a9ac045cebe18398f8",
	      "date": "2019-04-26T08:47:16.600701",
	      "first_seen": "2019-04-26T08:47:16.600701",
	      "type": "adsense",
	      "value": "pub-123456789",
	      "risk": 0
	    }
      ]
    }
  ]
}
GET dashboard/{id}/download

This endpoint return the same informations as details without pagination.

Requests to this endpoint are limited to one per 30 seconds.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/download

Fields

Field Type Description
id string Server uniq ID.
ip string Server IP address.
in_src boolean Flag indicating if IP have been explicitly search.
bookmark boolean Flag indicating if the server is bookmarked in WebUI.
country_code string Country code based to Whois.
country_name string Country name based on Whois.
whois_as int AS number based on Whois.
whois_name string IP range name based on whois.
whois_organisation string Organisation name based on Whois.
whois_range string IP range based on Whois.
geo_city string City name based on whois.
geo_lat float Latitude of the server position.
geo_long string Longitude of the server position.
cloudflare boolean Flag indicating if the server IP is part of Cloudflare IP range..
domains list List of domains linked to this server.
alerts list List of alerts for this server.
leaks list List of leaks related to this server.
services list List of open ports on this server.
social_networks list List of social newtork accounts linked to domains on this server.
ids list List of ID linked to domains on this server.
risk int Compromise risk (rang 1-5).

Result


[
  {
    "id": "6465ec74397c9126916786bbcd6d7601",
    "ip": "1.2.3.4",
    "in_src": false,
    "bookmark": false,
    "country_code": "us",
    "country_name": "United States",
    "whois_as": 1234,
    "whois_name": "Yuleak Test AS",
    "whois_organisation": "Yuleak-1234 - Yuleak Company, US",
    "whois_range": "1.2.3.4/26",
    "geo_city": "Paris",
	"geo_lat": 48.85,
	"geo_long": 2.34,
    "cloudflare": false,
	"risk": 3,
    "domains": [
      {
        "id": "31743d8c4d6041a9ac045cebe18398f8",
	    "parent": "6465ec74397c9126916786bbcd6d7601",
        "in_src": false,
        "tags": [
          "wordpress"
        ],
        "value": "blog.yuleak.com",
		"risks": 0
      }
    ],
    "alerts": [
      {
        "id": "db0176c793d6cb29bf1bf62e6094293f",
	    "parent": "31743d8c4d6041a9ac045cebe18398f8",
        "date": "2019-04-26T08:47:16.600701",
	    "first_seen": "2019-04-26T08:47:16.600701",
        "type": "ssl",
        "value": "Expired on 2018-03-21",
	    "risk": 3
      }
	],
    "leaks": [
      {
	    "id": "4ee645a91d1aec4465428ed6b69e2747",
	    "parent": "31743d8c4d6041a9ac045cebe18398f8",
        "date": "2019-04-26T08:47:16.600701",
	    "first_seen": "2019-04-26T08:47:16.600701",
        "email": "[email protected]",
        "password": "******",
	    "risk": 4
      }
    ],
    "services": [
      {
	    "id": "bdac43f9a043eedacb2fea690a55b08b",
	    "parent": "6465ec74397c9126916786bbcd6d7601",
        "date": "2019-04-26T08:47:16.600701",
	    "first_seen": "2019-04-26T08:47:16.600701",
        "name": "OpenSSH",
        "port": 22,
        "protocol": "tcp",
        "version": "7.2p2",
        "weak": false,
	    "risk": 0
      }
    ],
	"social_networks": [
	  {
	    "id": "a66b724df70b072c6681ef1b00547563",
	    "parent": "31743d8c4d6041a9ac045cebe18398f8",
	    "date": "2019-04-26T08:47:16.600701",
	    "first_seen": "2019-04-26T08:47:16.600701",
	    "login": "YuleakDemo",
	    "plateform": "twitter",
		"icon": "fa-twitter",
	    "risk": 0,
	    "link": "https://www.twitter.com/YuleakDemo"
	  }
	],
	"ids": [
	  {
	    "id": "efd12c4eb0b3b2b28086dd44210cec9f",
	    "parent": "31743d8c4d6041a9ac045cebe18398f8",
	    "date": "2019-04-26T08:47:16.600701",
	    "first_seen": "2019-04-26T08:47:16.600701",
	    "type": "adsense",
	    "value": "pub-123456789",
	    "risk": 0
	  }
    ]
  }
]
GET dashboard/{id}/map

This endpoint gives servers positions. Informations are similar to map view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/map

Fields

.
Field Type Description
label string Marker name, made with country, city name and server ips.
lat float Latitude.
long float Longitude.

Result


{
  "data": [
    {
      "lat": 31.2087,
      "long": 121.594,
      "label": "<\b>US - San Fransisco<\br/><\/b>104.16.1.2"
    }
  ]
}
GET dashboard/{id}/graph

This endpoint gives graph elements of your dashboard. Informations are similar to graph view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/graph

Fields

Field Type Description
nodes.id string Node uniq ID (32 to 64 chars).
nodes.label string Node label.
nodes.type string Node type (server, domain, asn). Node type are similar to fields in dashboard endpoint result.
nodes.ok boolean Flag indicating if node is linked to any alert.
edges.from string Start node uniq ID (32 to 64 chars).
nodes.to string End node uniq ID (32 to 64 chars).

Result


{
  "nodes": [
    {
      "id": "6465ec74397c9126916786bbcd6d7601",
      "label": "1.2.3.4",
      "ok": true,
      "type": "server"
    },
    {
      "id": "8641cc6fe45a178ccfc1b932f409982e",
      "label": "yuleak.com",
      "ok": true,
      "type": "domain"
    }
  ],
  "edges": [
    {
      "from": "6465ec74397c9126916786bbcd6d7601",
      "to": "8641cc6fe45a178ccfc1b932f409982e"
    }
  ]
}
GET dashboard/{id}/timeline

This endpoint gives timeline elements of your dashboard. Informations are similar to timeline view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/timeline

Fields

Field Type Description
date string Alert first seen date.
total int Number of alerts this day.

Result


{
  "data": [
    {
      "date": "2019-06-21",
      "total": 3
    }
  ]
}
GET dashboard/{id}/statsdns

This endpoint gives stats for DNS typosquatting information. Informations are similar to dns view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/statsdns

Fields

Field Type Description
legit int Number of legitimate domains.
suspicious int Number of suspicious domains.
other int Number of domains with similar names.
parking int Number of domains parked.
last_check datetime Date of last DNS check (DNS is refreshed after each search).
processing boolean Flag indicating if a request is queued for your dashbaord.

Result


{
  "data": [
    {
      "legit": 0,
      "suspicious": 0,
	  "other": 0,
      "parking": 0,
	  "last_check": "2019-04-26T08:47:16.60070",
	  "processing": false
	}
  ]
}
GET dashboard/{id}/dns

This endpoint gives all DNS typosquatting information. Informations are similar to dns view in WebUI.

If some resources are still being processed, warning field will contain a message.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/dns

Fields

Field Type Description
domain string Domain name.
ip string First IP found with DNS query.
classification string Yuleak classification for this domain.

Result


{
  "data": [
    {
      "domain": "yuleak.com",
      "ip": 1.1.1.1,
	  "classification": "legit"
	}
  ]
}
GET credits

This endpoint return your credits balance. Every search cost you credits (1 per IP/Domain).

To avoid errors when using search endpoint, please check your balance before sending requests.

Request

curl -H 'X-Api-Key:mdemo' https://api.yuleak.com/credits

Fields

Field Type Description
credits int Your credits balance.

Result


{
  "data": [
    {
      "credits": 605
    }
  ]
}
POST search

This endpoint launch a new research, value parameter is mandatory.

The endpoint dashboard/{id}/search allow to search in a existing dashboard.

Request

curl -X POST -H 'X-Api-Key:demo' -d 'value=yuleak.com' -d 'dashboard=1' https://api.yuleak.com/search

Result


{
  "data": []
}
GET dashboard/{id}/searchall

This endpoint with GET method will return a list of IP presents on the dashboard but not yet searched.

Request

curl -X GET -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/searchall

Result


{
  "data": ['1.1.1.1','1.1.1.2']
}
POST dashboard/{id}/searchall

This endpoint will launch a search on all IP in the dashboard wich are not already in resources. (Credits will be consumed)

Request

curl -X POST -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/searchall

Result


{
  "data": []
}
POST dashboard/{id}/renew

This endpoint re-launch a research, value parameter is mandatory.

Request

curl -X POST -H 'X-Api-Key:demo' -d 'value=yuleak.com' https://api.yuleak.com/dashboard/1/renew

Result


{
  "data": []
}
GET dashboard/{id}/renewall

This endpoint with GET method will return the cost of a full renew of the dashboard's resources.

Request

curl -X GET -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/renewall

Result


{
  "data": [{'credits': 13}]
}
POST dashboard/{id}/renewall

This endpoint re-launch all researches of the dashboard.

Request

curl -X POST -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/renewall

Result


{
  "data": []
}
GET dashboard/{id}/resources

This endpoint return the list of search made in a specific dashboard.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/resources

Fields

Field Type Description
value string Search content.
type string Search type (domain, ip, range ...).
status string Search status.
date datetime Last execution date.

Result


{
  "data": [
    {
      "value": "yuleak.com",
      "type": "domain",
      "status": "inprogress",
      "date": "2019-04-26T08:47:16.600701"
    }
  ]
}
DELETE dashboard/{id}/resources

This endpoint delete a search, value parameter is mandatory.

You must provide both dashboard_id (in url) and value (in data).

Request

curl -X DELETE -H 'X-Api-Key:demo' -d 'value=yuleak.com' https://api.yuleak.com/dashboard/1/resources

Result


{
  "data": []
}
POST dashboard/{id}/server/{server}/bookmark

This endpoint bookmark a server (it will be always, even if filter is applied, first), id of the dashboard and server id are mandatory.

Request

curl -X POST -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/server/6465ec74397c9126916786bbcd6d7601/bookmark

Result


{
  "data": []
}
DELETE dashboard/{id}/server/{server}/bookmark

This endpoint will deleted specified bookmark, id of the dashboard and server id are mandatory.

Request

curl -X DELETE -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/server/6465ec74397c9126916786bbcd6d7601/bookmark

Result


{
  "data": []
}
GET dashboard/{id}/filters

This endpoint gives filters applied to the given dashboard.

Request

curl -H 'X-Api-Key:demo' https://api.yuleak.com/dashboard/1/filters

Fields

.
Field Type Description
category string Filter category (server, alert, domain, date).
value string Filter value.
type string Filter type: required or ignored.

Result


{
  "data": [
	{
	  "category": "alert",
	  "value": "blacklist",
	  "type": "required"
	}
  ]
}
POST dashboard/{id}/filters

This endpoint add a new filter to the given dashboard, category and value parameters are mandatory.

type parameter is optional. By default it is set to required

Request

curl -X POST -H 'X-Api-Key:demo' -d 'value=blacklist' -d 'category=alert' https://api.yuleak.com/dashboard/1/filters

Result


{
  "data": []
}
DELETE dashboard/{id}/filters

This endpoint delete an existing filter of the given dashboard, category and value parameters are mandatory.

Request

curl -X DELETE -H 'X-Api-Key:demo' -d 'value=blacklist' -d 'category=alert' https://api.yuleak.com/dashboard/1/filters

Result


{
  "data": []
}