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 simply execute:
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
You can get your API key from your Shodan account page located at:Get your API Key
The shodan CLI has a lot of commands, the most popular/ common ones are documented below. For the full list of commands just run the tool without any arguments:
Returns the number of results for a search query.
$ shodan count microsoft iis 6.0 5310594
Search Shodan and download the results into a file where each line is a JSON banner. For more information on what the banner contains check out:Banner Specification
By default it will only download 1,000 results, if you want to download more look at the --limit flag.
The download command is what you should be using most often when getting results from Shodan since it lets you save the 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.
See information about the host such as where it's located, what ports are open and which organization owns the IP.
$ shodan host 22.214.171.124
Returns your Internet-facing IP address.
$ shodan myip 126.96.36.199
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.
The following command outputs the IP address, port and organization in CSV format for the previously downloaded Microsoft-IIS data:
$ shodan parse --fields ip_str,port,org --separator , microsoft-data.json.gz
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.
To search Microsoft IIS 6.0 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