Background
Just before Christmas in the black Friday deals I managed to pickup the lifetime membership to Shodan for £5.99. I recently had some spare time so I wanted to have play and this blog outlines the. how you can use python to setup network alerts via Shodan API.
Intro
Where search engines like Bing or Google are concerned with returning information relating to websites and their content. Shodan is essentially a search engine that allows you to retrieve information for devices connected to the internet. It is extremely powerful and allows you to query device information such as banners, ports, protocols and metadata associated with internet connected devices.
Shodan has three main mechanisms for retrieving device information in a programmatic way:
Clients – python, ruby, PHP, C#, Haskell, Go, Java, NodeJS, Perl, PowerShell and Rust;
REST API (https://api.shodan.io); and
Streaming API (https://stream.shodan.io).
This bog will only cover the use of the Python client to setup and receive network alerts.
Pre-requisites
Installation of Python – generally pre-installed on OSX, unix and linux. On Windows it can be installed from https://www.python.org/downloads/.
Once python is installed the following commands must be run on Windows:
Install Shodan:
C:UsersShodan>pip install shodan
Setup and initialise your own Shodan API key:
C:UsersShodan>shodan init {YOUR API KEY}
Creating a real-time network monitoring service
Create and configure a network alert:
C:UsersShodan>shodan alert create “My Site” 0.0.0.0/24 (replace 0.0.0.0/0 with your actual IP range and subnet mask)
List your alerts. The below command will show all the alerts you have setup via the API. The alert ID is key for when you want to make changes to your alerts such as configuring alert triggers.
C:UsersShodan>shodan alert list
View alert triggers. The next command will show the available alert triggers. These can be used to configure an alert such as the existence of ports associated with vulnerable services or expired SSL certificates.
C:UsersShodan>shodan alert triggers
Configure alert triggers. As mentioned above alert triggers can be added to an alert to monitor and alert on certain conditions. Common triggers include alerting on malware and configuration changes such as the emergence of new ports and ICS or IOT devices exposed directly to the internet. The following triggers are available by default:
Any –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) any
Malware –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) malware
Industrial Control System (ICS) –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) industrial_control_system
Internet Scanner –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) internet_scanner
IOT –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) iot
Unauthenticated Database –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) – open_database
Expired SSL Certificate –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) ssl_expired
Uncommon Services –
C:UsersShodan>shodan alert enable {YOUR ALERT ID) uncommon
View alert information:
C:UsersShodan>shodan alert info. {YOUR ALERT ID)
Retrieve a real-time alert stream associated with your alert ID. This command enables a real-time alert stream to be ingested or subscribed to by logging, security and other automation tooling.
C:UsersShodan>shodan stream – alert JQAJ9WE4XJPYBFG0
Once you have setup alerts and configured triggers you will receive email alerts to the email address associated with your Shodan API account. It is possible to create scripts that can subscribe to alert feeds and then generate emails using a local mail server of your choosing. This blog really just scratches the surface and I would encourage you to play around with the Shodan python modules.
If you would like to remove an alert you can use:
C:UsersShodan>shodan alert remove {YOUR ALERT ID)
Summary
I couldn’t believe how easy it was to setup and configure real-time alerting using python and the Shodan API. This is a brilliant way to monitor your internet facing infrastructure for vulnerabilities, unexpected changes or presence of IoT or ICS devices.
