The Shodan API makes it possible to get a distribution of values for a property using a concept called facets. A facet is typically named after a matching property and lets you see how many results there are for a given property value. Filters let you narrow down search results while facets let you see the big picture of the results. For example, to get a breakdown of the top 10 countries with the most web servers you would use a search query of HTTP and ask the API to facet on country.
The left sidebar of the Shodan search results is created using facets. And the entire Internet Exposure website is powered by a free API key that runs facet queries:
You can explore the list of available facets from our Facet Analysis page.
Everything on this page can be done with a free API key
Usage: shodan stats [OPTIONS] <search query>
Provide summary information about a search query
Options:
--limit INTEGER The number of results to return.
--facets TEXT List of facets to get statistics for.
-O, --filename TEXT Save the results in a CSV file of the provided name.
-h, --help Show this message and exit.
The stats command is the primary way to perform facet queries in Shodan. If you only give it a search query then it will automatically facet on a few popular properties such as org and port. The real advantage of the CLI however is that you have complete control over the facets so lets see how to create our own facet queries.
The --facets is how you define the list of facets that you want to get information about. Multiple values can be provided by giving a comma-separated list of values. For example, the below command gets a breakdown of the top 10 ports that SSH runs on:
$ shodan stats --facets port ssh
ssh is the search query. We are using the port facet to get a breakdown of the port property. And by default, the stats command will return the top 10 values of a facet.
Lets also learn which organizations are running most of the SSH services:
$ shodan stats --facets port,org ssh
We are faceting on both port and org. The search query is still ssh.
Optionally, you can specify how many facet values you would like to see by adding a :<number> after the facet name. For example, lets get a breakdown of the top 100 ports that SSH is running on:
$ shodan stats --facets port:100 ssh
And you can have different limits for each facet:
$ shodan stats --facets port:100,org:20 ssh
The above would get a breakdown of the top 100 ports and the top 20 organizations that are running SSH. And of course you can combine facets and filters to get more interesting breakdowns. For example, here is a list of the top 50 cities in the U.S. that are running SSH:
$ shodan stats --facets city:50 ssh country:US