performing-ip-reputation-analysis-with-shodan

name	performing-ip-reputation-analysis-with-shodan
description	Analyze IP address reputation using the Shodan API to identify open ports, running services, known vulnerabilities, and hosting context for threat intelligence enrichment and incident triage.
domain	cybersecurity
subdomain	threat-intelligence
tags	["shodan","ip-reputation","enrichment","threat-intelligence","reconnaissance","vulnerability","api","internet-scanning"]
version	1.0
author	mahipal
license	Apache-2.0

Performing IP Reputation Analysis with Shodan

Overview

Shodan is the world's first search engine for internet-connected devices, continuously scanning the IPv4 and IPv6 address space to catalog open ports, running services, SSL certificates, and known vulnerabilities. This skill covers using the Shodan API and InternetDB free API to enrich IP addresses from security alerts, assess threat levels based on exposed services and vulnerabilities, identify hosting infrastructure patterns, and integrate IP reputation data into SOC triage and threat intelligence workflows.

Prerequisites

• Python 3.9+ with shodan library (pip install shodan)
• Shodan API key (free tier: limited queries; paid plans for higher limits and streaming)
• Understanding of TCP/UDP ports, common services, and CVE identifiers
• Familiarity with ASN, CIDR notation, and IP geolocation concepts
• Network security knowledge for interpreting scan results

Key Concepts

Shodan Data Model

Each IP record in Shodan contains: open ports and protocols, banner data (service responses), SSL/TLS certificate details, known CVE vulnerabilities, hostname(s) and reverse DNS, ASN and ISP information, geographic location, operating system fingerprint, and historical scan data showing changes over time.

InternetDB API

Shodan's free InternetDB API (internetdb.shodan.io) provides quick IP lookups without authentication, returning open ports, hostnames, tags, CPEs, and known vulnerabilities. This is useful for high-volume enrichment where the full Shodan API would hit rate limits.

Reputation Scoring

IP reputation is assessed by combining: number and type of open ports (unusual ports indicate compromise), vulnerable services (unpatched software with known CVEs), hosting type (residential, cloud, VPN/proxy, bulletproof hosting), historical activity (past associations with malware, scanning, spam), and geographic context (countries known for specific threat activity).

Practical Steps

Step 1: Basic IP Enrichment with Shodan API

import shodan
import json
from datetime import datetime

class ShodanEnricher:
    def __init__(self, api_key):
        self.api = shodan.Shodan(api_key)
        self.info = self.api.info()
        print(f"[+] Shodan API initialized. Credits: {self.info.get('scan_credits', 0)}")

    def enrich_ip(self, ip_address):
        """Full enrichment of an IP address via Shodan."""
        try:
            host = self.api.host(ip_address)
            enrichment = {
                "ip": ip_address,
                "organization": host.get("org", ""),
                "asn": host.get("asn", ""),
                "isp": host.get("isp", ""),
                "country": host.get("country_name", ""),
                "country_code": host.get("country_code", ""),
                "city": host.get("city", ""),
                "latitude": host.get("latitude"),
                "longitude": host.get("longitude"),
                : host.get(, ),
                : host.get(, []),
                : host.get(, []),
                : host.get(, []),
                : host.get(, []),
                : host.get(, []),
                : host.get(, ),
                : [],
            }

             service  host.get(, []):
                svc = {
                    : service.get(, ),
                    : service.get(, ),
                    : service.get(, ),
                    : service.get(, ),
                    : service.get(, {}).get(, ),
                    : service.get(, )[:],
                }
                   service:
                    svc[] = service[].get(, {}).get(, {})
                    svc[] = service[].get(, {}).get(, {})
                    svc[] = service[].get(, {}).get(, )
                enrichment[].append(svc)

            
            enrichment[] = ._calculate_reputation(enrichment)
            (
                  
                  )
             enrichment

         shodan.APIError  e:
            ()
             

     ():
        
        score = 
        factors = []

        
        vuln_count = (data.get(, []))
         vuln_count > :
            score += 
            factors.append()
         vuln_count > :
            score += 
            factors.append()
         vuln_count > :
            score += 
            factors.append()

        
        suspicious_ports = {, , , , , , ,
                           , , , , , }
        open_ports = (data.get(, []))
        sus_found = open_ports.intersection(suspicious_ports)
         sus_found:
            score += 
            factors.append()

        
        malicious_tags = {, , , , }
        tags = (data.get(, []))
        mal_tags = tags.intersection(malicious_tags)
         mal_tags:
            score += 
            factors.append()

        
        port_count = (data.get(, []))
         port_count > :
            score += 
            factors.append()

        level = (
              score >= 
               score >= 
               score >= 
             
        )

         {: score, : level, : factors}

     ():
        
         requests
        resp = requests.get(, timeout=)
         resp.status_code == :
            data = resp.json()
            (
                  
                  )
             data
         

enricher = ShodanEnricher()
result = enricher.enrich_ip()
(json.dumps(result, indent=, default=))

Step 2: Batch IP Reputation Check

import time

def batch_ip_reputation(enricher, ip_list, output_file="ip_reputation.json"):
    """Check reputation for a list of IP addresses."""
    results = []
    for i, ip in enumerate(ip_list):
        result = enricher.enrich_ip(ip)
        if result:
            results.append(result)
        if (i + 1) % 10 == 0:
            print(f"  [{i+1}/{len(ip_list)}] Processed")
            time.sleep(1)  # Rate limiting

    # Sort by reputation score (highest risk first)
    results.sort(key=lambda x: x.get("reputation", {}).get("score", 0), reverse=True)

    with open(output_file, "w") as f:
        json.dump(results, f, indent=2, default=str)

    # Summary
    levels = {"critical": 0, "high": 0, "medium": 0, "low": 0}
    for r in results:
        level = r.get("reputation", {}).get("level", "low")
        levels[level] += 1

    ()
    ()
     level, count  levels.items():
        ()

     results

suspicious_ips = [, , ]
results = batch_ip_reputation(enricher, suspicious_ips)

Step 3: Infrastructure Correlation

def correlate_infrastructure(enricher, ip_address):
    """Find related infrastructure based on shared attributes."""
    host_data = enricher.enrich_ip(ip_address)
    if not host_data:
        return {}

    correlations = {
        "same_org": [],
        "same_asn": [],
        "shared_ssl": [],
    }

    # Search for same organization
    org = host_data.get("organization", "")
    if org:
        try:
            results = enricher.api.search(f'org:"{org}"', limit=20)
            for match in results.get("matches", []):
                correlations["same_org"].append({
                    "ip": match.get("ip_str", ""),
                    "port": match.get("port", 0),
                    "product": match.get("product", ""),
                })
        except shodan.APIError:
            pass

    # Search for same SSL certificate
    for service in host_data.get("services", []):
        ssl_subject = service.get("ssl_subject", {})
        if ssl_subject:
            cn = ssl_subject.get("CN", "")
             cn:
                :
                    results = enricher.api.search(, limit=)
                       results.get(, []):
                        correlations[].append({
                            : .get(, ),
                            : cn,
                        })
                 shodan.APIError:
                    

    ()
    ()
    ()
     correlations

Validation Criteria

• Shodan API queried successfully with proper authentication
• IP enrichment returns ports, services, vulnerabilities, and geolocation
• Reputation scoring classifies IPs by threat level
• Batch enrichment handles rate limiting correctly
• Infrastructure correlation identifies related hosts
• InternetDB free API used for high-volume lookups

References

• Shodan Developer API
• Shodan InternetDB API
• Shodan Python Library
• Query.ai: Leveraging Shodan for Security Research
• Torq: Shodan IP Enrichment Workflow
• Recorded Future: Shodan Integration