Have you ever needed to write a quick script to download data from Shodan? Or setup a cronjob to check what Shodan found on your network recently? How about getting a list of IPs out of the Shodan API? For the times where you’d like to have easy script-friendly access to Shodan there’s now a new command-line tool appropriately called shodan.

Installation

The shodan command-line interface (CLI) is packaged with the official Python library for Shodan, which means if you’re running the latest version of the library you already have access to the CLI. To install the new tool in Linux simply execute:

easy_install shodan

Or if you’re running an older version of the Shodan Python library and want to upgrade:

easy_install -U shodan

Once the tool is installed, you have to initialize the environment with your API key using shodan init:

shodan init YOUR_API_KEY

Usage

At the moment, the shodan CLI supports 6 commands. Note that for each command you can learn more about the options it supports by supplying the –help flag.

1. count

Returns the number of results for a search query.

$ shodan count microsoft iis 6.0 5310594

2. download

Search Shodan and download the results into a file where each line is a banner serialized in JSON as specified in https://developer.shodan.io/api/banner-specification

By default it will only download 1,000 results, if you want to download more look at the –limit flag.

For example, to download the latest 1,000 Microsoft-IIS 6.0 servers indexed by Shodan into a file called microsoft-data.json.gz use the following command:

This is the command that you should be using the most, since it lets you save your results and process them afterwards using the parse command. Because paging through results uses query credits, it makes sense to always store searches that you’re doing so you won’t need to use query credits for a search you already did in the past.

3. init

Initialize the shodan CLI. This is the first command you have to run for the tool to work, if you’re unsure about how to install the CLI please read the section above on installation.

shodan init YOUR_API_KEY

4. myip

Returns your Internet-facing IP address.

$ shodan myip 199.30.49.210

5. parse

Use parse to analyze a file that was generated using the download command. It lets you filter out the fields that you’re interested in, convert the JSON to a CSV and is friendly for pipe-ing to other scripts. For example, here’s the command to output the IP address, port and organization in CSV:

$ shodan parse --fields ip_str,port,org --separator , microsoft-data.json.gz

And this is what the output in your terminal would look like:



6. search

This command lets you search Shodan and view the results in a terminal-friendly way. By default it will display the IP, port, hostnames and data. You can use the –fields parameter to print whichever banner fields you’re interested in. For example, to search for Microsoft IIS 6.0 devices and print out their IP, port, organization and hostnames use the following command:

$ shodan search --fields ip_str,port,org,hostnames microsoft iis 6.0

Final Thoughts

I hope you’ve gotten a good idea of what the shodan CLI can do and how it might make your life easier. The tool is still in its early stages but it’s served me well so far. At this point, I’d love to get some feedback on things you’d like to see improved by submitting issues on the GitHub repository:

https://github.com/achillean/shodan-python

Coincidentally, that’s also the place where you can see the code for the tool in case you’re curious about the inner-workings. Please submit ideas for improvements and let me know via email (jmath@shodan.io) or Twitter whether this is useful to you!