DroneBL :: Documentation

The DroneBL RPC WebService v2

Highly available querying and manipulation of the DroneBL database.

Introduction

The DroneBL RPC WebService is used to connect the DroneBL to other codebases and scripts. Mostly it is used internally to add and remove entries in the database on demand. To use the WebService, you will need an RPCKEY, which you can get by contacting us. Our BOPM reporting service is an example of possible usage of the RPC webservice.

List of tools

As follows are some scripts that employ the RPC2 methods described below. Use these as they are, modify them, or take them apart to see how they work.

dronebl-tools -- a set of Python scripts to query or report hosts
DroneBLClient.py -- the Python class from dronebl-tools
dronereport -- a PHP-cli script for reporting hosts
dronebl-submit.sh -- a BASH script for reporting hosts
dronebl-remove.sh -- a BASH script depending on curl for removing hosts
dronebl.pl -- an irssi script for advanced lookups
libdronebl-tcl -- a TCL library / Eggdrop script providing query and reporting methods; includes example Eggdrop scripts

Syntax

Url to send requests to: https://dronebl.org/rpc2

A request looks something like this, where METHOD and METHOD-PARAMS belong to the list below:

    <?xml version="1.0"?>
    <request key='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' [staging='1' [debug='1']]>
        <METHOD METHOD-PARAMS />
    </request>

request: Perform a request.

key (mandatory): Your rpc key
staging: do NOT actually perform any add/remove requests, just stage em.

debug: produce extra timing output to analyse performance.

returns:

<?xml version="1.0"?>
<response type="success">
    METHOD-DATA
</response>

METHOD-DATA may contain:

<returntype data="message" ... optional fields ... />

Errors look like this:

    <?xml version="1.0"?>
    <response type="error">
        <code>ERROR-CODE</code>
        <message>ERROR-MESSAGE</message>
        <data>ERROR-DETAILS</data>
    </response>

Methods

Once you have acquired an RPCKEY, you can use these methods. Note that some methods may not be available depending on what level of access your RPCKEY has. If you want to test your script, but do not actually want to execute add/remove requests, add the staging parameter to the REQUEST tag. The value does not matter, it only needs to exist.

typelist: Returns the available types possible.

    <typelist />

returns:

    <typelist type="**type**" description="**description**" />

    <debug data="typelist: <secs>." />

lookup: Looks up an IP or range in DroneBL. You must specify either ip or id.

    <lookup ip="ip or cidr" (or) id="id" [type="type" [listed="0|1|2" [start="unixtime" [stop="unixtime" [own="1" [limit="0-1000"]]]]]] />

id: The index of a record. If you look up a record by its id, then ip is not required.
ip: The IP or CIDR to lookup.
type: The class a record should be in. (default=any).
listed: Show records with listed being either 0(not active), 1(Active). (default=any).
start: A unix timestamp specifying the start offset of records. (default=any).
stop: A unix timestamp specifying the ending offset of records. (default=any).
own: Select records set by the requesting keyowner.

limit: Limit the amount of results to (1-1000) results. (default=1000).

returns:

<result ip="**ip**" port="**port**" type="**type**" comment="**comment**" id="**id**" listed="**listed**" timestamp="**timestamp**" />

<warning data="Missing IP or ID parameter." />
<warning id="**id**" data="**id** is an invalid id." />
<warning ip="**ip**" data="**ip** is not a valid IPv4/IPv6 address or cidr." />
<warning ip="**ip**" data="Prefix has to be numeric." />
<warning data="**type** is not a valid type. Please see http://dronebl.org/classes" />

<debug ip="**ip**" data="lookup: <secs>." />

add: Adds a new entry to the DroneBL.

    <add ip="ip" type="type" [port="1-65535" [comment="comment"]] />

ip (mandatory): The IP of the entry to add.
type (mandatory): The type of blocking class under which the IP should be listed.
port: The port if applicable. (default=none).

comment: very basic description of the event (IRC flood / SSH brute force / list scrape / etc.)

returns:

<success ip="**ip**" id="**id**" data="Added **ip**[ (Simulated)]" />

<warning data="Missing IP parameter." />
<warning ip="**ip**" data="**ip** is not a valid IPv4/IPv6 address." />
<warning ip="**ip**" data="**ip** is whitelisted." />
<warning ip="**ip**" data="**ip** is a private/unallocated address." />
<warning ip="**ip**" data="**ip** is a tor exit node." />
<warning ip="**ip**" data="Missing TYPE parameter." />
<warning ip="**ip**" data="**type** is not a valid type. Please see http://dronebl.org/classes" />
<warning ip="**ip**" data="**ip** already present. Type 17 does not accept already listed entries" />
<warning ip="**ip**" data="**ip** has already been scraped." /> (If you use type 17 and 'Scraped' as comment)
<warning ip="**ip**" data="**port** is an invalid port." />
<warning ip="**ip**" data="You already reported **ip**[:**port**] as type **type**" />
<warning ip="**ip**" data="Unable to add **ip** for unknown reason. Contact maintainer." />

<debug ip="**ip**" data="add: <secs>." />

update: Updates a listing in DroneBL.

    <update id="**id**" comment="**comment**"/>

id (mandatory): The listing/incident ID to update.

comment (mandatory): The new comment.

returns:

<success id="**id**" data="Updated **id**[ (simulated)]" />

<warning data="You have not specified the ID to be updated" />
<warning id="**id**" data="The id **id** does not exist" />
<warning id="**id**" data="**id** already delisted and thus cannot be updated" />
<warning id="**id**" data="You are not authorized to update this incident" />
<warning id="**id**" data="No comment specified, so what is there to update?" />

<debug id="**id**" data="update(_*): <secs>." />

remove: Removes a listing in DroneBL.

    <remove id="**id**" />

id (mandatory): The listing/incident ID to disable.

returns:

<success id="**id**" data="Removed **id**[ (simulated)]" />

<warning data="You have not specified the ID to be removed" />
<warning id="**id**" data="The id **id** does not exist" />
<warning id="**id**" data="**id** already delisted" />
<warning id="**id**" data="**id** is not removable. Please use the website" />
<warning id="**id**" data="You are not authorized to remove this incident" />

<debug id="**id**" data="remove: <secs>." />

Using RPC2

You will need to sign up for an RPCKEY. This is now a public process, and the RPCKEY will work for RPC1 too, which is a bit easier than RPC2, but less powerful.

We are working on standardizing RPC2 as a DNSBL provider interaction protocol. Hopefully other providers will start supporting it.

View Markdown Source