Skip to main content

How to Track the Internet with Shodan API

Shodan is a search engine for Internet-connected devices. Unlike traditional search engines that index websites, Shodan indexes devices, services, and infrastructure exposed to the internet. This tutorial demonstrates how to use the Shodan API to query and analyze internet-connected devices, providing insights into network infrastructure, security postures, and technology distributions.

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"]

Facet Configuration​

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​

  1. Security Research: Identify exposed services and potential vulnerabilities
  2. Infrastructure Analysis: Understand technology distributions across organizations
  3. Geographic Mapping: Analyze device distributions by country
  4. 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

Facet Analysis​

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.

Repository: shodan-api

Read more from Cryptogrammar​