The Apility.io Command Line Interface

Several weeks ago we announced our new Python client library. We love to see how our users not only use our API for their internal products and services, but also for their commercial products. This month we introduce the first command line interface (CLI) tool to access our API services. Using the Python Library we currently use for our in-house developments (we are a Python house) we have developed and hosted the source code on Github. Following our strong commitment with the community,  we have released it under the Apache 2.0 license, so feel free to collaborate with us to improve it!

How to install it

Since this library is based on our Python library, we support Python 2 and 3, for versions 2.7+ and 3.4+ respectively. It is recommended that Python 2 users use python 2.7.9+ to take advantage of the SSL Certificate Validation feature that is not included in earlier versions. You can install the Apility.io Command Line Interface tool with pip:

$ pip install apilityio-cli

Or with easy_install:

$ easy_install apilityio-cli

Documentation

You can read the Command Line Interface documentation hosted in Pypi.org. The user can start using the CLI right away, even without registering in the service! If you have any question you can visit the website at https://apility.io, review the REST API specification at https://apility.io/apidocs and also read the User Guide at https://apility.io/docs.

Verify installation

To verify if the command has been successfully installed, the user can open a terminal in the target Operating System and type the apility command as follows:

$ apility
 usage: apility [-h] [--apikey APIKEY] [--config CONFIG]
                      [--format {XML,CSV,TEXT,JSON}]
                      [--tableonly TABLEONLY] [--rows ROWS] [--page PAGE]
                      [--timestamp TIMESTAMP]
                      {badip,baddomain,bademail,geoip,asip,asnum,whoisip,historyip,historydomain,historyemail,getquarantine}
                      parameter
 apility: error: the following arguments are required: command, parameter

If the command is not found in the PATH of the user’s session probably the tool has not been installed correctly. Please contact our support team or check our issue tracker.

Use the CLI without an API KEY (anonymous mode)

If the user does not provide a valid API KEY the CLI tool will work in anonymous mode. In this mode, the API has a limit of 100 hits per day and per IP address, enough for quick testing and sporadic use. If the user needs more hits then he/she has to register in our site and obtain a valid API KEY. The FREE plan allows 250 hits per day. If you need more hits per day you should consider an upgrade to some of our paid plans.

Use the CLI with an API KEY

If the user already has a valid API KEY then he/she has to pass it with the CLI. There are three different ways to do it:

  • Use the –apikey optional parameter in every single command executed.
  • Create an environment variable called APILITYIO_API_KEY and assign the API KEY before executing any command.
  • Write a configuration file readable by the command line tool.

You can learn more about how to configure the tool reading the documentation in Pypi.org.

Export Formats

The command line interface tool permits different export formats depending on how you want to manage data:

  • TEXT: Key/value or Tabular text output depending on the number of results and the parameter –tableonly.
  • CSV: Tabular comma-separated output. Strings are inside double quotes and lists of elements are separated by semicolons.
  • JSON: Direct dump of the JSON format used by the REST API.
  • XML: Transformation of the JSON format to XML.

Example 1, Check an IP address and show data in Text format:

Check if an IP address or a list of IP addresses belong to any list of the blacklist databases of Apility.io. It also returns the blacklists where the IP addresses were found. IP addresses are passed as a comma-separated list. For details about all fields returned by the call read https://apility.io/apidocs/#ip-check.

Example single IP address:

$ apility badip 1.2.3.4
+---+------------+-------------------+
| ! | IP ADDRESS |     BLACKLISTS    |
+---+------------+-------------------+
| ! |  1.2.3.4   | STOPFORUMSPAM-365 |
|   |            |  STOPFORUMSPAM-90 |
|   |            | STOPFORUMSPAM-180 |
+---+------------+-------------------+

Example multiple IP addresses:

$ apility badip 1.2.3.4,8.8.8.8,1.1.1.1,0.0.0.1
+---+------------+-------------------+
| ! | IP ADDRESS |     BLACKLISTS    |
+---+------------+-------------------+
| ! |  1.2.3.4   | STOPFORUMSPAM-365 |
|   |            |  STOPFORUMSPAM-90 |
|   |            | STOPFORUMSPAM-180 |
|   |  1.1.1.1   |                   |
| ! |  0.0.0.1   |  TEAMCYMRU-BOGONS |
|   |            |    IANA-BOGONS    |
|   |  8.8.8.8   |                   |
+---+------------+-------------------+

Example 2, Check a domain and show data in Text format:

Check if a domain or a list of Domain and its MX and NS records belong to any list of the blacklist databases of Apility.io. It returns a list of the scoring and blacklists where the Domains info were found. For details about all fields returned by the call read https://apility.io/apidocs/#domain-check.

$ apility badip baddomain mailinator.com
+-----------------------+-------------------------+
| KEY                   | VALUE                   |
+-----------------------+-------------------------+
| SCORE                 | -2                      |
| DOMAIN                | mailinator.com          |
| DOMAIN SCORE          | -2                      |
| DOMAIN BLACKLISTS     | LISINGE-DED             |
|                       | DEA                     |
|                       | MARTENSON-DED           |
|                       | IVOLO-DED               |
| MX BLACKLISTS         | LISINGE-DED             |
|                       | IVOLO-DED               |
|                       | MARTENSON-DED           |
|                       | DEA                     |
| MX HOSTS              | mail.mailinator.com     |
|                       | mail2.mailinator.com    |
| NS BLACKLISTS         |                         |
| NS HOSTS              | james.ns.cloudflare.com |
|                       | betty.ns.cloudflare.com |
| DOMAIN IP             | 104.25.199.31           |
| DOMAIN IP SCORE       | -1                      |
| DOMAIN IP BLACKLISTS  | LISINGE-DED-IP          |
|                       | IVOLO-DED-IP            |
|                       | MARTENSON-DED-IP        |
| DOMAIN IP QUARANTINED | False                   |
| SOURCE IP             | 79.156.253.222          |
| SOURCE IP SCORE       | 0                       |
| SOURCE IP BLACKLISTS  |                         |
| SOURCE IP QUARANTINED | False                   |
+-----------------------+-------------------------+

API Documentation

This CLI has been built around the python library. You can read the Python Library documentation here:http://apilityio-python-lib.readthedocs.io/en/latest/

You can also read the original REST API specification here: https://apility.io/apidocs

What’s next?

So now you can start coding or integrate our library with your application or service! And we would like to know about it! So please don’t hesitate and contact us to tell us about your product or service!