Shodan API Client

A lightweight Python command-line interface for interacting with the Shodan API. This tool provides easy access to Shodan's search capabilities, IP lookups, CVE vulnerability information, and account management features.

Features

• Host Search - Search Shodan's database for devices and services
• IP Lookup - Get detailed information about specific IP addresses
• CVE Lookup - Retrieve vulnerability information from Shodan's CVE database
• API Info - Check your Shodan API account status and credits
• My IP - Quickly discover your public IP address

Requirements

• Python 3.7+
• requests library
• Shodan API key

Installation

1. Clone this repository:

git clone https://github.com/yourusername/shodan-http-client.git
cd shodan-http-client

2. Install dependencies:

pip install requests

3. Set up your Shodan API key as an environment variable:

export SHODAN_API_KEY="<YOUR_API_KEY>"

Get your API key from https://account.shodan.io/. If you plan to use Shodan extensively, upgrade to the "dev" plan, totally worth it!

Usage

Search Shodan

# Search for Apache servers in Austin, TX
python main.py --search "apache city:Austin"

Example Output:

Total Results: 10242
IP: 67.208.43.190:80
Product: Apache httpd
Organization: Ntirety, Inc.
----------------------------------------
IP: 168.107.59.199:8080
Product: Apache httpd
Organization: Oracle Corporation
----------------------------------------
IP: 67.208.40.128:2082
Product: Unknown
Organization: Ntirety, Inc.
----------------------------------------
IP: 67.208.42.198:443
Product: Apache httpd
Organization: Ntirety, Inc.
----------------------------------------
IP: 64.20.241.39:3554
Product: Unknown
Organization: zColo
----------------------------------------
IP: 198.180.200.5:443
Product: Apache httpd
Organization: Haas Group International, LLC

IP Lookup

Get detailed information about a specific IP address:

python main.py --iplookup "<IP_ADDRESS>"

Output includes:

• Organization information
• Operating system
• Open ports
• Associated services

Example Output:

IP: 45.79.222.20
Organization: Linode
Operating System: Linux
Open port: 22

CVE Vulnerability Lookup

Query vulnerability information from Shodan's CVE database:

# Check a known Log4j vulnerability
python main.py --cve "CVE-2021-44228"

Example Output:

Looking up vuln for CVE-2021-44228
========================================================================================
CVE Summary: Apache Log4j2 2.0-beta9 through 2.15.0 <truncated>...
========================================================================================
Reference: http://packetstormsecurity.com/files/165225/Apache-Log4j2-2.14.1-Remote-Code-Execution.html

Check API Information

View your Shodan API account details and remaining credits:

python main.py --apiinfo

Output includes:

• API plan type
• Scan credits remaining
• Query credits remaining
• Number of monitored IPs

Get Your Public IP

Quickly retrieve your public IP address:

python main.py --myip

Command-Line Arguments

The CLI is built using Python's argparse module for clean argument parsing:

parser = argparse.ArgumentParser()
parser.add_argument("--myip", action="store_true")
parser.add_argument("--apiinfo", action="store_true")
parser.add_argument("--search", default="")
parser.add_argument("--iplookup", default="")
parser.add_argument("--cve", default="")
parser.add_argument("--page", type=int, default=1)

Argument	Type	Description
--search	string	Search query for Shodan
--iplookup	string	IP address to lookup
--cve	string	CVE identifier to query
--apiinfo	flag	Display API account information
--myip	flag	Display your public IP
--page	integer	Page number for paginated results (default: 1)

Project Structure

shodan-http-client/
├── main.py           # CLI entry point and argument parsing
├── shodanapi.py      # Shodan API interaction methods
├── pyproject.toml    # Project configuration
└── README.md         # This file

Notes

• Requires a valid Shodan API key set as the SHODAN_API_KEY environment variable
• Free API keys have usage limits - check your plan with --apiinfo
• CVE lookups use the public CVE database endpoint (no API key required)

Future Enhancements

• Enhanced error handling and validation
• Containerization with Docker
• JSON output format option (entire results in JSON)
• Integration with Shodan's additional method endpoints (DNS, Directory, etc.)