Blacklist Data Feed

1. About

The Blacklist Data Feed is a subscription service that provides a list of all malicious IP addresses reported on the BHD website. The feed is updated every 10 minutes. You can receive up-to-date data by using our easy-to-use RESTful API. The IP addresses provided by the feed can be used to update firewall rules in order to block attackers.

2. Types of data sets

The Blacklist Data Feed is comprised of four different databases. Each has a particular characteristic and purpose. Below table depicts properties of supported types:

DB Type Description Best for
Fast This dataset contains IP addresses having at least one negative comment. It may contain false-positive results. This is the largest database. Backend hosts, back office, non-client-facing systems
Basic This dataset contains IP addresses having at least three negative comments. It may contain false-positive results. Systems that can afford for rare false-positives results
Safe This dataset contains IP addresses having at least six negative comments. The number of false-positive results is minimized. This is the most secure database. Frontend hosts, client-facing systems
Free It contains the most commonly reported IP addresses. This service is distributed under the Creative Commons Attribution-ShareAlike 4.0 International License. The database doesn't contain all reported IPs, but only top 10%. Blogs, private websites, testing

3. Pricing

DB type Plan Price
Fast
Basic
Safe
Bronze
Updated daily
$5/month
billed annually: $50
billed semi-annually: $30
Fast
Basic
Safe
Silver
Updated hourly
$15/month
billed monthly
Fast
Basic
Safe
Gold
Updated every 10 minutes
$30/month
billed monthly
Free Distributed under the Creative Commons Attribution-ShareAlike 4.0 International License Free

4. REST API

4.1 GET /v1/blacklist/:api_key/:database_type/:time_range/ip_list.txt.gz

Returns all IPs for the data set.

Resource URL

https://api.blackhat.directory/v1/blacklist/:api_key/:database_type/:time_range/ip_list.txt.gz

Resource Information

Response Format GZipped text file containing one IP address per line
Requires Authentication Yes (API Key)
Rate Limited Yes
Rate It depends on plan:
Bronze - 31 req/month
Silver - 24 req/day
Gold - 6 req/hour

Parameters

Parameter Required Description
api_key Yes Your authentication token.
We will send you your API Key once the payment is received.
database_type Yes Database type.
Possible values: basic, safe, fast, free. See paragraph 2.
time_range Yes Specifies a time range of the last malicious activity of a host. When you provide the 1m (one month) time range then all hosts reported in the previous month will be included in the returned blacklist. The longer time range, the more IP addresses are returned. The shorter time range, the more significant IP addresses are returned.
Possible values: 1w, 2w, 1m, 2m

Example Request

HTTP 200 OK
The response is returned using chunked transfer encoding.

$ curl https://api.blackhat.directory/v1/blacklist/:api_key/fast/1w/ip_list.txt.gz

$ curl https://api.blackhat.directory/v1/blacklist/:api_key/basic/2w/ip_list.txt.gz

$ curl https://api.blackhat.directory/v1/blacklist/:api_key/free/1m/ip_list.txt.gz

$ curl https://api.blackhat.directory/v1/blacklist/:api_key/safe/2m/ip_list.txt.gz

Example Response

10.1.1.1
10.1.1.2
10.1.1.3
fd12:3456:789a:1::1
...

Error Messages

Code Message Description
400 Time range '3m' not supported Could not recognize the provided time range.
400 Database type 'supreme' not supported Could not recognize the provided database type.
403 Permission denied The provided API Key doesn't exist.
403 Subscription starts at 13 Nov 2018 15:59:35 Your subscription has not started yet.
403 Subscription finished at 13 Nov 2018 15:59:35 Your subscription has been finished.
429 Request limit (100) exceeded Too many requests. Upgrade your plan.

Example Error

HTTP/1.1 403 Forbidden
Content-Length: 95
Content-Type: application/json
Date: Tue, 13 Nov 2018 15:59:35 GMT

{"success":false,"token":"8a30a180-8192-4f80-b97e-21101fa77be9","errors":["Permission denied"]}

4.2 GET /v1/accounts/:api_key/status

Coming soon.

5. Payment methods

Wire transfer, PayPal.

6. Terms of Service

7. How to place an order

Drop us a line via the contact form.
Please provide the following data:

  • Chosen plan
  • The time when your subscription should start
  • Billing information
  • Payment method