badips.com | Home Follow @badipscom

badips.com documentation


1. Introduction
1.1. the reporter role
1.2. the consumer role
2. block IPs with badips.com
3. report IPs to badips.com
3.1. basic API usage
3.2. reporting with fail2ban
3.3. obtain a key
4. synchronize blocklists
5. get reports for your hosts
6. understanding scores
6.1. Which score is right for me?
7. detailed API usage

1. introduction

badips.com is an IP based abuse tracker. Anyone can report "bad" IPs as well as anyone can consume compiled blocklists for free to do whatever they like to do with it.

We refer to a 'badip' or 'badips' as an IP that was seen in context with malicious activities on hosts which are connected with the internet. These activities include, but are not limited to, brute force login attempts, SPAM delivery attempts, Form SPAM attempts or (D)DOS attacks and so on and so forth.

As a user of badips.com you are either a reporter, a consumer or both.

1.1. the reporter role

As a reporter you report offending IPs to badips.com via our API.

You will generally do this for one or more of the following reasons:

An IP which is reported to badips.com is always shared with others, whereas a reporters IP will remain private.

See section 3 for more info on how you can report IPs or integration in other tools.

1.2. the consumer role

As a consumer you download a list of IPs reported to badips.com based on some optional criterias, such as score or time frame etc. With such a list you may feed your firewall or reporting engine or whatever you like.

See section 2 for more information on how you may want to do that.

2. block IPs with badips.com

This section is not finished yet, please check back later or ask in the forum.

You may want to check this blog post for how you could block IPs listed on badips.com.

3. report IPs to badips.com

3.1. basic API usage

A simple API request to report IPs to badips.com looks like this:

wget https://www.badips.com/add/ssh/aa.bb.cc.dd

Where 'aa.bb.cc.dd' represents an IP address and 'ssh' is the category. The category is related to the service which was affected by the malicious activity to the corresponding IP, in this example the attack was hitting the SSH daemon.

Categories are not arbitrary - only some specified categories may be used. You can check which they are here:

https://www.badips.com/get/categories

3.2. reporting with fail2ban

Using fail2ban is the recommended way to report IPs to badips.com.

If you have fail2ban in version 0.8.12 (check with fail2ban-server --version), you can just enable the badips action, like here e.g. for SSH

[ssh]

enabled  = true
action = iptables-multiport
         badips[category=ssh]
         port     = ssh
         filter   = sshd
         logpath  = /var/log/auth.log
         maxretry = 6

If you have a version less than 0.8.12, you'll have to create the badips action first, you can download the config file or run this command in a shell on your server:

wget https://www.badips.com/asset/fail2ban/badips.conf -O /etc/fail2ban/action.d/badips.conf

With the badips.conf from above, you can either activate per category as above or you can enable it globally:

[DEFAULT]

...

banaction = iptables-multiport
            badips

Now restart fail2ban - it should start reporting from now on.

3.3. obtain a key

By obtaining a key you connect your IP(s) to a random string which is only known by you. This enables you to get blocklists of IPs only reported by you or to view statistics about your attackers only. A key can be linked to several reporters, this enables you to synchronize blocklists over all your servers and view statistics for all your servers combined.

The first time you get a key, do this:

wget https://www.badips.com/get/key -qO -

This will print a JSON response on your console, for example this:

{
  "err":"",
  "suc":"new key 5f72253b673eb49fc64dd34439531b5cca05327f has been set.",
  "key":"5f72253b673eb49fc64dd34439531b5cca05327f"
}

Your key is the value following in the "key" field, without quoutes.

4. synchronize blocklists

This section is not finished yet, please check back later or ask in the forum.

5. get reports for your hosts

To see how many IPs you've reported, where they are from and much more, obtain a key, and then enter it in the "Key:" field on the website or just append the "?key=yourkey" parameters to the URL, for example like this: www.badips.com/stats?key=5f72253b673eb49fc64dd34439531b5cca05327f .

6. understanding scores

On badips.com, every IP which is added to the database gets rated. The rating results in a number from zero to five. The score system is here to give an indicator of both, how likely it is that an IP really is 'bad' and how bad it is.

This means that there is one number for two metrics. You can think of this as follows:
If it seems very clear that an attack from this IP really occourred, it's very likely that the IP really is 'bad'. This may lead to a score of, say, 2.64.
If the attack coming from a certain IP is very sophisticated or happens to many people or is very aggressive, the attack may be very bad, so a score could be 3.21.
If then both - very bad and very likely - come together, we may have a score of 4.29.

6.1. Which score is right for me?

7. detailed API usage

GET /add/<category>/<IP>

/add is used to report an IP.

sample request


    https://www.badips.com/add/ssh/1.2.3.4
    

sample answer


      {
        "err":"",
        "suc":"added 1.2.3.4 in category ssh by <your IP>"
      }
    

GET /get/categories

/get/categories is used to retrieve all valid categories.

sample request


    https://www.badips.com/get/categories
    

sample answer


     {
       "categories": [
         {
           "Name": "ssh",
           "Desc": "SSH bruteforce login attacks and other ssh related attacks"
         }
       ]
     }
    

GET /get/stats/count

/get/stats/count returns the number of IPs in our database.

sample request


    https://www.badips.com/get/stats/count
    

sample answer


    {
      "count":236
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/stats/countbycountry

/get/stats/countbycountry returns the number of IPs in our database by country.

sample request


    https://www.badips.com/get/stats/countbycountry
    

sample answer


    {
      "countbycountry":[
        "CN":92,
        "US":22,
        "FR":12,
        "KR":10,
        [...]
        }
      ]
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/stats/countbycategory

/get/stats/countbycategory returns the number of IPs in our database by category.

sample request


    https://www.badips.com/get/stats/countbycategory
    

If you'd like to see a breakdown for a parent category, enter query whit ?category= :


    https://www.badips.com/get/stats/countbycategory?category=http
    

sample answer


    {
      "countbycategory": [
      {
        "dovecot-pop3imap": 13207
      },
      {
        "ssh": 8292
      },
      {
        "postfix": 3159
      },
    [...]
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>
  • ?age=
    • e.g. 2w , 1d, 12h

GET /get/stats/countbyopenport

/get/stats/countbyopenport returns the number of IPs in our database which have defined ports open.

sample request


    https://www.badips.com/get/stats/countbyopenport?port=443
    

sample answer


    {
          "port 443 closed": 216,
          "port 443 open": 39
    }
    

additional options

  • ?port=
    • 22
    • 80
    • 443
    • 3389
  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/list/<category>/<score>

/get/list/ returns a list of IPs based on your selections.

sample request


    https://www.badips.com/get/list/ssh/0
    

sample answer


    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    [...]
    

additional options

  • ?format=
    • ipset
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/info/<IP>

/get/info/<IP> returns information on the given IP.

sample request


    https://www.badips.com/get/info/61.160.212.66
    

sample answer (listed IP)


    {
      "ReporterCount": {
        "sum": 7,
        "ssh": 7
      },
      "Categories": [
        "ssh"
      ],
      "Score": {
        "ssh": 5
      },
      "LastReport": {
        "ssh": 1389590320
      },
      "Whois": {
        "descr": [
          "CHINANET jiangsu province network",
          "China Telecom",
          "A12,Xin-Jie-Kou-Wai Street",
          "Beijing 100088",
          "CHINANET jiangsu province network"
        ],
        "inetnum": "61.160.0.0 - 61.160.255.255",
        "netname": "CHINANET-JS",
        "country": "CN"
      },
      "CountryCode": "CN",
      "rDNS": null,
      "suc": "IP 61.160.212.66 is listed on badips.com!",
      "Listed": true
    }
    

sample answer (IP not listed)


    {
        "suc": "IP 14.37.91.32 is not listed on badips.com!",
        "Listed": false
    }
    

Two fields are always* returned: "Listed" and "suc", "suc" is a bit more verbose while "Listed" is a bool. You can check "Listed" if you want to know wheter an IP is listed on badips.com or not.

*If you formulate an invalid request (e.g. an invalid IP format) you get a 400 error and "err" is set to inform you about the problem.

GET /get/country/<country>

/get/country/ returns a list of networks within the given country.

sample request


    https://www.badips.com/get/country/nl
    

sample answer


    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    [...]
    

additional options

  • ?format=
    • ipset
    • plain

GET /get/key

/get/key/ returns a unique key that is associated to your IP. This key can then later be used to query the website or API and retrieve personalised content. This can only be done from a reporting IP.

sample request


    https://www.badips.com/get/key
    

sample answer


    {
      "err":"",
      "suc":"new key 65bedf87249c427b0cb461687d25f7ac5d493540 has been set.",
      "key":"65bedf87249c427b0cb461687d25f7ac5d493540"
    }
    

additional options

  • ?force
  • set a new key, even if you already have one.

GET /set/key/<key>

/set/key/ adds the IP of the requester to a key. This can only be done from a reporting IP. Before you can set a key, you have to get one (see get/key above).

sample request


    https://www.badips.com/set/key/<key>
    

sample answer


    {
      "err":"",
      "suc":"new key 65bedf87249c427b0cb461687d25f7ac5d493540 has been set.",
      "key":"65bedf87249c427b0cb461687d25f7ac5d493540"
    }
    

additional options

  • ?force
  • set a new key, even if you already have one.

Error Handling

If your request produces an error, it will return HTTP status code 400 and represented in the returned JSON. Generally you can check if err object is empty. See sample request and sample answers.

sample request - no error


    https://www.badips.com/add/ssh/1.2.3.4
    

sample answer - no error


      {
        "err":"",
        "suc":"added 1.2.3.4 in category ssh by <your IP>"
      }
    

sample request - with error


    https://www.badips.com/add/ssh/10.0.0.1
    

sample answer - with error


    {
      "err":"IP is invalid (malformed or private).",
      "suc":""
    }