How to Track the Internet with Shodan API

Right now, there are thousands of devices connected to the internet with no authentication. Open ports, exposed dashboards, unpatched services, all visible to anyone who knows where to look. Most of their owners have no idea.

Shodan is the search engine that surfaces them. Where Google indexes web pages, Shodan crawls exposed infrastructure. If a device has an open port, it’s likely already in Shodan. This tutorial shows how to query that data programmatically through the Shodan API. It covers the same techniques used for network analysis, security research, and infrastructure mapping. For applying similar OSINT methods to smart contracts, see Google Dorks for Smart Contract Security.

Video Tutorial

Repository: shodan-api

Overview

Shodan provides APIs that allows developers and researchers to programmatically search for devices, services, and vulnerabilities across the internet. This tool demonstrates how to:

Query internet-connected devices using Shodan’s search syntax
Analyze device distributions by organization, domain, port, ASN, and country
Generate summary statistics using Shodan’s facet functionality
Work within free tier limitations using count-based searches

Architecture

The implementation consists of a single Python script that interfaces with the Shodan API. You need to signup on https://www.shodan.io to get the API key.

Configuration

The script uses environment variables for secure API key management:

import shodan
import sys
import os

# Configuration
API_KEY = os.environ["shodan_key"]

Facets allow you to get aggregated statistics about search results. The script configures facets for common analysis dimensions:

# The list of properties we want summary information on
FACETS = [
    "org",        # Organizations hosting devices
    "domain",     # Domains associated with devices
    "port",       # Open ports and services
    "asn",        # Autonomous System Numbers
    ("country", 3),  # Top 3 countries (limited to 3)
]

FACET_TITLES = {
    "org": "Top 5 Organizations",
    "domain": "Top 5 Domains",
    "port": "Top 5 Ports",
    "asn": "Top 5 Autonomous Systems",
    "country": "Top 3 Countries",
}

Facet types:

Organization: Identifies which companies or entities host the devices
Domain: Shows associated domain names
Port: Reveals open ports and running services
ASN: Autonomous System Numbers indicate network providers
Country: Geographic distribution of devices

API Interaction

The core functionality uses Shodan’s count() method, which is available on the free tier:

try:
    api = shodan.Shodan(API_KEY)

    # Generate a query string out of the command-line arguments
    query = " ".join(sys.argv[1:])

    # Free plan allows count search
    result = api.count(query, facets=FACETS)

    print("Shodan Summary Information")
    print(f"Query: {query}")
    print(f"Total Results: {result['total']}\n")

    for facet in result["facets"]:
        print(FACET_TITLES[facet])
        for term in result["facets"][facet]:
            print(f"{term['value']}: {term['count']}")
        print("")

except Exception as e:
    print(f"Error: {e}")
    sys.exit(1)

Key features:

Command-line interface: Accepts search queries as command-line arguments
Input validation: Checks for required arguments before making API calls
Error handling: Gracefully handles API errors and network issues
Formatted output: Displays results in a human-readable format

Usage Examples

Basic Queries

Search for specific services or technologies:

python shodan_search.py apache
python shodan_search.py nginx
python shodan_search.py "product:Apache"
python shodan_search.py "port:22"

Advanced Queries

Shodan supports powerful search filters:

# Search by country
python shodan_search.py "country:US apache"

# Search by organization
python shodan_search.py "org:Amazon port:443"

# Search by specific port
python shodan_search.py "port:3306 mysql"

# Combine multiple filters
python shodan_search.py "product:nginx country:DE port:80"

Common Use Cases

Security Research: Identify exposed services and potential vulnerabilities
Infrastructure Analysis: Understand technology distributions across organizations
Geographic Mapping: Analyze device distributions by country
Network Monitoring: Track changes in exposed services over time

Key Insights

Understanding Shodan Queries

Shodan uses a query syntax similar to search engines but optimized for device metadata:

Product filters: product:Apache, product:nginx
Port filters: port:22, port:443
Country filters: country:US, country:DE
Organization filters: org:Amazon, org:Google
Version filters: version:2.4.41
OS filters: os:Linux, os:Windows

Facets provide aggregated statistics without retrieving individual results, making them:

API-efficient: Count queries use fewer API credits
Privacy-friendly: No individual device information exposed
Fast: Aggregated results return quickly
Free tier compatible: Available on all Shodan plans

Limitations

Free tier restrictions: Limited to count queries; full search results require paid plans
Rate limiting: API calls are rate-limited based on subscription tier
Query complexity: Complex queries may timeout or return incomplete results
Data freshness: Results reflect Shodan’s last scan, not real-time data

Security and Ethics

When using Shodan for research:

Respect privacy: Only query for legitimate research purposes
Follow terms of service: Adhere to Shodan’s usage policies
Don’t exploit vulnerabilities: Use information responsibly
Consider disclosure: Report critical vulnerabilities through proper channels

Conclusion

The Shodan API provides powerful capabilities for internet-wide device discovery and analysis. This tool demonstrates how to leverage Shodan’s facet functionality to generate insights about internet infrastructure without requiring expensive API plans. Whether for security research, infrastructure analysis, or educational purposes, Shodan offers a unique window into the connected world.