Shodan Pentesting Guide
Note: This is one of my favorite guide on Shodan and thought of sharing it, all the credit goes to writer and I hope this helps you guys
Shodan is a tool for searching devices connected to the internet. Unlike search engines which help you find websites, Shodan helps you find information about desktops, servers, IoT devices, and more. This information includes metadata such as the software running on each device.
Common uses of Shodan include Network Security, Market Research, Cyber Risk, scanning IoT devices, and Tracking Ransomware. This guide will focus on comprehensively covering these applications in a pentesting context.
Shodan is a tool that lets you explore the internet; discovering connected devices or network services, monitoring network security, making global statistics and so on.
The Shodan’s website/database references results from extensive port scanning of the Internet.
Shodan interfaces
This section will show you the various ways you can connect to Shodan.
It’s possible to interact with Shodan via the well known website, the official python command-line interface tool and library, a variety of community driven libraries for many languages and also the official REST API.
CLI tool
The official shodan command-line interface (CLI) is written in python, for quick usage in your terminal.
Install
In a virtual python environment like pyenv:
$ easy_install shodanOn BlackArch you can also install the following package:
# pacman -S python-shodanOnce you have installed shodan CLI tool, to setup your API token just do:
$ shodan init <YOUR_API_KEY>Command overview
A dozen of straightforward commands are available:
–help
info
If you have setup your API token, you can check the number of credits you have left:
Query credits are used to search Shodan and scan credits are used to scan IPs.
A search request consumes 1 query credit and scanning 1 IP consumes 1 scan credit.
version
When writing this article I was using shdoan 1.21.2:
count
Returns the number of results for a search query.
download
Search Shodan and download the results into a file where each line is a JSON banner.
By default it will only download 1,000 results, if you want to download more look at the –limit flag.
The download command lets you save the results and process them afterwards using the parse command.
So if you often search for the same queries it will help you save credits.
The export credits are used to download data from the website at the rate of: 1 export credit lets you download up to 10,000 results. They are single-use which means that once you use them they don’t automatically renew at the start of the month.
But if you don’t have export credits, you can use 1 query credit to save 100 results.
For example here I will download 1000 results of the query openssh:
After the download you can check how many credits you have left:
host
See information about the host such as where it’s located, what ports are open and which organization owns the IP.
myip
Returns your Internet-facing IP address.
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.
The following command outputs filtered data for the previously downloaded openssh data:
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.
A simple query won’t consume any credits but if you use a search filter or request page 2 and beyond, credits will be consumed.
Example of query that won’t cost credits:
Example of query that will cost 1 credit (because using a filter):
scan
Scan an IP/ netblock using Shodan.
Launching a scan will cost credits:
1 scan credit lets you scan 1 IP
By default a scan result will be displayed to stdout but you can save it to a file to be able to parse it later.
If the host has already been scanned in the last 24 hours, you won’t be able to scan it again without an Enterprise grade plan.
You are also able to see the scans you previously launched with their ID and status:
To save your scan results you are not forced to use –filename. You can simply launch a scan without saving it, and download the results later thanks to the scan ID:
As scan are done asynchronously, you can check the status of a scan at any moment.
To see the scan ID when launching a scan you can use the verbose mode:
Customers with an Enterprise Data License will be allowed to request a scan of the entire Internet by simply specifying the port and protocol/module.
Available protocols and modules can be listed with shodan scan protocols.
stats
Provide summary information about a search query
It seems that by default you will get only top 10 and not for all facets:
But we can customize this behavior:
Website
Main interface
The main interface of Shodan is the search engine.
It works like the search command of the CLI tool but with a fancy WebUI to display the results. It shows a summary for each host, the total count of hosts that matched the query like the count command of the CLI and some stats like the stats command.
Once you have selected a host, you will be able to see a shot specification table, vulnerabilities impacting the host, open ports and banners for open ports.
Downloading data
After you made a search, a Download Results button will be available:
Then you will be able to download the search results in JSON, CSV or XML.
Only the JSON format will contain the full data and be compatible with the Shodan CLI tool. CSV format will only contain IP, port, banner, organization and hostnames.
The XML format is deprecated by Shodan and consumes more space than the JSON one.
You can then view your download history in the Downloads section.
Generating reports
The website lets you generate a report based off of a search query.
The report contains graphs/ charts providing you a big picture view of how the results are distributed across the Internet. This feature is free and available to anyone.
To generate a report, click on the Create Report button from the search results page:
Name your report:
Creating a report will usually take a few minutes, you will receive an email when the report is ready with the link.
Else you can find all your previous reports on the report page.
A report is static and won’t update automatically.
Maps
The map interface to search the Shodan database works like the stats command of the CLI but displays the results in an interactive map depending on the physical location of the host.
As it won’t show more than 1000 results, you will have to zoom in and out or move around to display other results
Images
Images is a searchable gallery of screenshots from crawled devices.
Image data is gathered from 5 different sources: VNC, Remote Desktop (RDP), RTSP, Webcams and X Windows.
A has_screenshot:true filter can be used in the global search engine to keep only hosts that have a screenshot.
Exploits
Exploits is a search engine that looks for exploits across a variety of vulnerability databases at once.
Developer dashboard
Your developer dashboard shows you your credits consumption and API plan.
Network monitor
Keep track of the devices that you have exposed to the Internet. Setup notifications, launch scans and gain complete visibility into what you have connected.
The monitor dashboard let you tracks your devices, alert you if something suspicious was detected, launch scan and display what’s found on synthetic dashboard.
To begin with, add an IP, a range or a domain to monitor and choose a notification service.
Then you can manage your assets, from here you can launch scans or modify trigger rules.
You can select which kind of event will trigger an alert.
Then the dashboard shows the exposed services.
ICS radar
ICS Radar is a 3D map of Industrial Control Systems (ICS) devices found by Shodan crawlers.
Honeypot score
The service called Honeypot or not? will attribute a Honeyscore to an IP address, a probability of being a honeypot.
It’s just an abstraction of the API like the honeyscore command of the CLI:
Shodan 2000
Sodan 2000 is a Tron-like interface that randomly displays an host.
You can explore queries exported and shared by other users of the community.
The shared queries have a title, a description and tags so you can browse them easily.
To share a query, click the Share Search button on a search result page.
REST API
Shodan comes with a REST API, it can be used to build a web application service based on Shodan or create a wrapper library if none already exists in your favorite language.
The base URL of the API is: https://api.shodan.io and all API methods are rate-limited to 1 req/sec.
The API is authenticated so if you forget to provide your API key, you will get a HTTP 401 error.
Here is an example of how you can query your API Plan Information with curl:
Another query to get a host information:
Check the REST API Documentation for a complete description of all methods.
Language wrappers (libraries)
To interface your tool with the Shodan API you can use one of the wrapper libraries.
The official one is made in Python, but there are also community libraries in Ruby, PHP, Haskell, Rust, Perl, Node.js, Go, PowerShell, Java and C#.
I will give examples for those three:
Python – shodan-python
Installation
The installation is the same as for the CLI tool as the CLI tool is made upon the python library, they are packaged together.
In a virtual python environment like pyenv:
On BlackArch you can also install the following package:
Then the API key will always be initialized like that in our code:
Note: the library is working for both python 2 and 3 but we’ll use only python 3 as python 2 is deprecated.
Examples
Basic search:
Example of output:
Available ports of a host:
Example of output:
Displaying stats:
Example of output:
Note: this examples comes from the official documentation but were adapted for Python 3 and updated to better suit this article.
Ruby – shodanz
Installation
In a virtual ruby environment like rbenv:
Then the API key will always be initialized like that in our code:
For production projects you may prefer read the API key via the environment variable SHODAN_API_KEY.
Examples
Basic search:
Example of output:
Available ports of a host:
Example of ouput:
Displaying stats:
Example of output:
Async support with the stream API:
Warning: Freelancer API plan or better required for using the stream API, developer or free plan won’t work.
Note: this async example comes from the shodanz documentation.
Useful methods
Exploits API
You can find more examples here or read the shodanz API documentation.
Node.js – shodan-client
Installation
In a virtual nodejs environment like nodenv:
Then the API key will always be initialized like that in our code:
Examples
Basic search
Example of output:
Available ports of a host
Example of output:
Displaying stats
Example of output:
Plugins
Firefox
This add-on retrieves data gathered by Shodan.io of the current website you’re browsing. It displays you general information such as the Organisation but also open ports.
Chromium
The Shodan plugin tells you where the website is hosted (country, city), who owns the IP and what other services/ports are open.
The Shodan plugin for Chrome automatically checks whether Shodan has any information for the current website. Is the website also running FTP, DNS, SSH or some unusual service? With this plugin you can see all the info that Shodan has collected on a given website/domain.
Shodan Search Query Syntax
Banner and properties
To get the most out of Shodan it’s important to understand the search query syntax.
In Shodan’s vocabulary a banner is an object containing the information of a service.
In the official documentation the below example of a simplified banner is given:
Each key of the dictionnary is called a property (data, ip_str, port, etc.). Each property stores a different type of information about the service.
By default Shodan is looking only into the data property, if no filter is provided.
Search filters
You could have found the previous example banner by searching Moxa Nport Device, but if you would have searched for devices from Starhub Mobile it wouldn’t have returned the expected result. That’s because, as I said earlier, by default, Shodan only searches the data property!
To search data using other properties we must use filters.
Search filters are special keywords to tell Shodan that you wish to search specific properties.
Filters are formatted as key:value.
Some examples:
To search for devices located in the Starhub Mobile Network:
org:”Starhub Mobile”
To search for devices located in Singapore:
country:SG
And of course they can be combined:
org:”Starhub Mobile” country:SG
Properties/filters specification
Here is the complete list of properties for banners (Source: Official documentation).
General properties
asn
[String] The autonomous system number (ex. “AS4837”).
data
[String] Contains the banner information for the service.
ip
[Integer] The IP address of the host as an integer.
ip_str
[String] The IP address of the host as a string.
ipv6
[String] The IPv6 address of the host as a string. If this is present then the “ip” and “ip_str” fields wont be.
port
[Integer] The port number that the service is operating on.
timestamp
[String] The timestamp for when the banner was fetched from the device in the UTC timezone. Example: “2014-01-15T05:49:56.283713”
hostnames
[String[]] An array of strings containing all of the hostnames that have been assigned to the IP address for this device.
domains
[String[]] An array of strings containing the top-level domains for the hostnames of the device. This is a utility property in case you want to filter by TLD instead of subdomain. It is smart enough to handle global TLDs with several dots in the domain (ex. “co.uk”)
location
[Object] An object containing all of the location information for the device.
location.area_code
[Integer]The area code for the device’s location. Only available for the US.
location.city
[String] The name of the city where the device is located.
location.country_code
[String] The 2-letter country code for the device location.
location.country_code3
[String] The 3-letter country code for the device location.
location.country_name
[String] The name of the country where the device is located.
location.dma_code
[Integer] The designated market area code for the area where the device is located. Only available for the US.
location.latitude
[Double] The latitude for the geolocation of the device.
location.longitude
[Double] The longitude for the geolocation of the device.
location.postal_code
[String] The postal code for the device’s location.
location.region_code
[String] The name of the region where the device is located.
opts
[Object] Contains experimental and supplemental data for the service. This can include the SSL certificate, robots.txt and other raw information that hasn’t yet been formalized into the Banner Specification.
org
[String] The name of the organization that is assigned the IP space for this device.
isp
[String] The ISP that is providing the organization with the IP space for this device. Consider this the “parent” of the organization in terms of IP ownership.
os
[String] The operating system that powers the device.
transport
[String] Either “udp” or “tcp” to indicate which IP transport protocol was used to fetch the information
Optional Properties
uptime
[Integer] The number of minutes that the device has been online.
link
[String] The network link type. Possible values are: “Ethernet or modem”, “generic tunnel or VPN”, “DSL”, “IPIP or SIT”, “SLIP”, “IPSec or GRE”, “VLAN”, “jumbo Ethernet”, “Google”, “GIF”, “PPTP”, “loopback”, “AX.25 radio modem”.
title
[String] The title of the website as extracted from the HTML source.
html
[String] The raw HTML source for the website.
product
[String] The name of the product that generated the banner.
version
[String] The version of the product that generated the banner.
devicetype
[String] The type of device (webcam, router, etc.).
info
[String] Miscellaneous information that was extracted about the product.
cpe
[String] The relevant Common Platform Enumeration for the product or known vulnerabilities if available. For more information on CPE and the official dictionary of values visit the CPE Dictionary.
SSL Properties
ssl.cert
[Object] The parsed certificate properties that includes information such as when it was issued, the SSL extensions, the issuer, subject etc.
ssl.cipher
[Object] Preferred cipher for the SSL connection
ssl.chain
[Array] An array of certificates, where each string is a PEM-encoded SSL certificate. This includes the user SSL certificate up to its root certificate.
ssl.dhparams
[Object] The Diffie-Hellman parameters if available: “prime”, “public_key”, “bits”, “generator” and an optional “fingerprint” if we know which program generated these parameters.
ssl.versions
[Array] A list of SSL versions that are supported by the server. If a version isnt supported the value is prefixed with a “-”. Example: [“TLSv1”, “-SSLv2”] means that the server supports TLSv1 but doesnt support SSLv2.
Miscellaneous
The beta version of the website offers two useful pages:
Shodan dorks & use cases
I’ll start by showcasing some simple snippets from shodan.
Examples are given for the CLI:
Number of devices vulnerable to Heartbleed
Get a list of subdomains for a domain
Create a private firehose for your network and subscribe to it
Find the top 10 most common vulnerabilities in Switzerland
I will continue with some publicly shared queries:
D-Link Internet Camera DCS-5300 series, without authentication
FTP server with anonymous authentication enabled
Databases
Games
Industrial Control Systems
And now, some dorks from dalmoz:
ASCII video examples
Hacked Ubiquiti Networks Device
Surveillance cameras, user: admin, no password
Home routers’ storage/attached USB storage
PBX phone gateways without authentication
Lantronix ethernet adapter’s admin interface without password
Polycom video-conference system no-auth shell
VNC servers without authentication
NPort serial-to-eth / MoCA devices without password
Some PenTestIT queries:
Default Jenkins installations
SonarQube installations
IBM WebSphere version disclosure
And to finish, a collection of search queries: Awesome Shodan Search Queries
Tools using Shodan
https://developer.shodan.io/apps
https://github.com/BullsEye0/shodan-eye
https://www.rapid7.com/db/modules/auxiliary/gather/shodan_search
https://github.com/s0md3v/Striker
https://github.com/lanmaster53/recon-ng
https://github.com/smicallef/spiderfoot
https://github.com/DefensePointSecurity/threat_note
https://github.com/OWASP/Amass
https://github.com/woj-ciech/Kamerka-GUI
https://github.com/random-robbie/My-Shodan-Scripts
https://github.com/jakejarvis/awesome-shodan-queries
https://github.com/pielco11/fav-up
ShodanSploit
It allows you to use all Shodan calls on your terminal and making detailed queries.
Github repository: https://github.com/shodansploit/shodansploit
Install:
git clone https://github.com/ismailtasdelen/shodansploit.git
cd shodansploit
python shodansploit.py
docker run -t ismailtasdelen/shodansploit
Docker Run:
docker run –rm -it ismailtasdelen/shodansploit
Menu:
[1] GET > /shodan/host/{ip}
[2] GET > /shodan/host/count
[3] GET > /shodan/host/search
[4] GET > /shodan/host/search/tokens
[5] GET > /shodan/ports
[6] GET > /shodan/exploit/author
[7] GET > /shodan/exploit/cve
[8] GET > /shodan/exploit/msb
[9] GET > /shodan/exploit/bugtraq-id
[10] GET > /shodan/exploit/osvdb
[11] GET > /shodan/exploit/title
[12] GET > /shodan/exploit/description
[13] GET > /shodan/exploit/date
[14] GET > /shodan/exploit/code
[15] GET > /shodan/exploit/platform
[16] GET > /shodan/exploit/port
[17] GET > /dns/resolve
[18] GET > /dns/reverse
[19] GET > /labs/honeyscore/{ip}
[20] GET > /account/profile
[21] GET > /tools/myip
[22] GET > /tools/httpheaders
[23] GET > /api-info
[24] Exit
Fav-Up
Description:
Lookups for real IP starting from the favicon icon and using Shodan.
Install:
At least python3.6 is required due to spicy syntax.
git clone https://github.com/pielco11/fav-up.git
pip3 install -r requirements.txt
Command overview:
Examples
Favicon-file:
python3 favUp.py –favicon-file favicon.ico -sc
Favicon-url
python3 favUp.py –favicon-url https://domain.behind.cloudflare/assets/favicon.ico -sc
Web
python3 favUp.py –web domain.behind.cloudflare -sc
Module
Related info:
https://pielco11.ovh/posts/cloud-hunting/
Articles of advanced uses
Shodan alternatives
Web commercial alternatives
Onyphe – pretty like Shodan but in addition of scanning it also crawls data from passive DNS lookup, threatlist lookup and paste sites lookup. However the free version is more limited than Shodan.
ZoomEye – is also very similar to Shodan, has a great set of advanced filters that are mroe documented than Shodan’s and a ton of pre-set queries. There is also a great free API tier.
Censys – like Shodan, it also has the ability to track changes, send alerts, etc. It seems there is no free API plan, the only free option is to use the website.
thingful – a search engine that is targeting only the Internet of Things
FOFA – is like Shodan, it also has a CLI tool and a Java, Go, C and Python library.
Greynoise – is like Shodan, be there is no free API plan, only web visualizer access. Also has a python library and a CLI tool.
BinaryEdge – like Shodan there are the search engine, honeypots/sensors detector but also an uncommon feature: Torrents/DHT Monitoring. There is a free Web & API plan.
Open source self hosted alternatives
IVRE – Source > is a network recon framework, including tools for passive recon (flow analytics relying on Bro, Argus, Nfdump, fingerprint analytics based on Bro and p0f) and active recon (IVRE uses Nmap to run scans, can use ZMap as a pre-scanner; IVRE can also import XML output from Nmap and Masscan).
It has a WebUI and a CLI tool.
In addition of the open-source project, there is also a public instance hosted online.
Thanks
First I want to thanks John C. Matherly a.k.a. @achillean to have created Shodan and maintained it for 10 years.
Then I also want to thanks Porter Adams (Co-Founder of Disappear Digital) and Ismael Gonzalez (http://osint.team/ member).
Finally I want to thanks Nathaniel Fried and Peter James Hansen for their amazing work at TurgenSec.
References
My name is Alexandre ZANNI aka noraj. I’m a pentester and ethical hacker. Also I’m a staff member of the RTFM association and a developer of BlackArch Linux.
My hacker page: pwn.by/noraj