Yuleak API¶

Latest Version on PyPI Documentation Status Licence

The official Python library for the Yuleak API.

Features¶

Convenient methods for making calls to the API.
Automatic parsing of API responses into Python objects.

Installation¶

yuleak-api is available on PYPI

pip install yuleak-api

Documentation¶

You can use the API with default demo key for development purpose but to use it you’ll need to register to Yuleak.

Authentication ¶

from yuleak_api.client import YuleakClient
YuleakClient.set_apikey('my_secret_api_key')

Errors ¶

In case of error, GET methods will return an empty list and POST/DELETE will return False.

The error will be displayed in yuleak-api logger.

Warnings will (such as a deprecated endpoint) will also be displayed in yuleak-api logger.

Pagination ¶

Pagination will be handle by the YuleakClient, you do not have to care about.

Usage¶

This is not intended to provide complete documentation of the API.

For more details, please refer to the official documentation.

For more information on the included models and abstractions, please read the code.

Credits ¶

Please check your credits amount before making any search or renew action to avoid errors.

print(YuleakClient.credits())

Dashboards ¶

dashboards = YuleakClient.dashboards()
for dashboard in dashboards:
    # Display stats (similar to dashboard view in WebUI)
    print(dashboard.stats())
    # Display map (similar to map widget in WebUI)
    print(dashboard.map())
    # Display graph (similar to graph view in WebUI)
    for node in dashboard.graph():
        if node.type == 'asn':
            print('AS: {0}'.format(node.label))
            for child in node.neighbors:
                if child.type == 'server':
                    print(child)
    # Display timeline (similar to timeline widget in WebUI)
    print(dashboard.timeline())
    # Display details (similar to details view in WebUI)
    for server in dashboard.details():
        print(server.geo.country_name)
    dashboard.delete()

Resources ¶

resources = dashboard.resources()
for resource in resources:
    print('{0} :: {1}'.format(resource.value, resource.status))
    if resource.type == 'server':
        resource.renew()
    else:
        resource.delete()

Bookmarks ¶

server = dashboard.details()[0]
assert not server.bookmark
server.add_bookmark()
assert server.bookmark
server.del_bookmark()
assert not server.bookmark

Filters ¶

dashboard.add_filter('domain', 'all')
for f in dashboard.filters():
    print(f)
    f.delete()

Search ¶

YuleakClient.search('yuleak.com')
dashboard = YuleakClient.dashboards()[-1]
dashboard.search('yuleak.io')
# Mass search
new_servers = dashboard.list_new_servers()
if YuleakClient.credits() >= new_servers > 0:
    dashboard.searchall()

Changelog¶

v1.3.4¶

requests timeout can now be set with YuleakClient.REQUESTS_TIMEOUT
requests retry on error can now be set with YuleakClient.REQUESTS_RETRY

v1.3.3¶

correct error on ‘DELETE dashboard/{id}’ endpoint

v1.3.2¶

correct error on ‘searchall’ endpoint

v1.3.1¶

correct error on pip install

v1.3.0¶

GET dashboard/{id}/renewall added
POST dashboard/{id}/renewall added

v1.2.0¶

GET dashboard/{id}/searchall added
POST dashboard/{id}/searchall added

v1.1.0¶

Change to match the Yuleak API path modifications

Contents¶

Generated Code Documentation¶

Python client for Yuleak API.

class yuleak_api.client.YuleakClient¶

Client for Yuleak API.

Class must be used without instance of it.

classmethod credits()¶

Get current user remaining credits

See https://app.yuleak.com/apidoc#get-credits for endpoint details.

Returns:: available credits amount

classmethod dashboards()¶

Get the current user dashboards list

See https://app.yuleak.com/apidoc#get-dashboards for endpoint details.

Returns:: list of Dashboard items

classmethod delete_request(endpoint, params=None)¶

Make a DELETE request to the API.

Args:: endpoint (str): Name of the endpoint to query. params (dict): GET data to send
Returns:: (bool) True if the request performed well

classmethod get_request(endpoint)¶

Make a GET request to the API.

Args:: endpoint (str): Name of the endpoint to query.
Returns:: a list of items

classmethod post_request(endpoint, data=None)¶

Make a POST request to the API.

Args:: endpoint (str): Name of the endpoint to query. data (dict): Data to send
Returns:: (bool) True if the request performed well

classmethod search(search)¶

Launch a new search (credits will be used). A new dashboard will be created.

See https://app.yuleak.com/apidoc#post-search for endpoint details.

Args:: search (str): Expression to search
Returns:: (bool) True if the search has been launched

classmethod set_apikey(apikey)¶

Define the ApiKey to use (by defaut ‘demo’ is used).

Args:: apikey (str): ApiKey to use

class yuleak_api.models.dashboard.Dashboard(id_, name)¶

Dashboard model

add_filter(category, value, type_='required')¶

Add a filter to the current dashboard.

See https://app.yuleak.com/apidoc#post-filters for endpoint details.

Args:: category (str): Filter category (server, domain, alert, date) value (str): Filter value (all, blacklist, cloudflare …) type_ (str): Filter type: required (by default) or ignored
Returns:: True if the filter has been added

delete()¶

Delete the current dashboard and all its data.

See https://app.yuleak.com/apidoc#post-delete for endpoint details.