shodan

README

Features • Workflow • Installation • Usage • Bug Bounty • Library • Contribution

This is a fast and concurrent Go implementation of the Shodan command line tool. It allows you to search the Shodan database, extract specific fields, and check IP addresses directly from your terminal. This tool was built to learn the Go programming language and to help with automation.

Background

The original Shodan command line application is written in Python. This Go version was created to provide a single compiled binary that runs without any Python dependency issues. It offers much faster execution and integrates smoothly into reconnaissance pipelines.

Why Go for Bug Bounty

Security researchers and bug bounty hunters require tools that are fast and easy to chain together.

• No Dependencies Python tools often break due to virtual environment issues or missing libraries. This Go tool compiles into a single binary that you can copy to any server.
• Speed and Concurrency Go handles network requests concurrently with very low memory usage. This allows you to query large sets of hosts or domains quickly.
• Pipeline Integration You can pipe inputs directly into this tool. This makes it easy to combine with other popular security tools.

Features

• Flat Flag Structure Allows you to place command and option flags in any order.
• Format Options Provides pretty terminal outputs, grep friendly tsv lines, or raw JSON data.
• Dynamic Property Extraction Extracts specific nested fields from banners using dot notation.
• Output Compression Saves query results directly into compressed files.
• Honeypot Evaluation Calculates the probability of an IP address being a honeypot.

Workflow

graph TD
    classDef target fill:#1a1c1e,stroke:#30363d,stroke-width:2px,color:#fff;
    classDef engine fill:#1f242c,stroke:#ffbc00,stroke-width:2px,color:#fff;
    classDef success fill:#1b2a1a,stroke:#2ea44f,stroke-width:2px,color:#fff;
    classDef alert fill:#341a1a,stroke:#da3637,stroke-width:2px,color:#fff;

    Input["Target Input"]:::target
    Parser["Flat Flag Parser"]:::engine
    API["Shodan API Client"]:::engine
    Pretty["Pretty Terminal Output"]:::success
    TSV["TSV File Output"]:::success
    JSON["Raw JSON Export"]:::success

    Input --> Parser
    Parser --> API
    API --> Pretty
    API --> TSV
    API --> JSON

Installation

Install the tool using the command below

go install -v github.com/R0X4R/shodan@latest

Usage

Before running any queries, you must initialize the application with your API key

shodan -init YOUR_SHODAN_API_KEY

Reference Flags

Command Flags

Flag	Description
-init	Save and validate the Shodan API key
-myip	Get your current public IP address
-info	Show Shodan account credits and status
-host	Get details for a specific IP address
-count	Count the total results for a query
-search	Search the Shodan database
-domain	Get DNS records for a domain
-stream	Stream live Shodan data (use -stream-type to pick variant)
-honeyscore	Check if an IP is a honeypot
-stats	Summarize query statistics
-version	Print the version of the tool

Option Flags

Flag	Shorthand	Default	Description
-limit	-l	100	Number of results to return (max per page)
-page	None	1	Page number of search results (100 results per page)
-offset	None	0	Offset into results (use with -limit for fine-grained pagination)
-minify	-m	false	Minify output
-fields	-f	None	Properties to show in search/stream results (comma-separated)
-separator	-s	\t	Separator between properties in search/stream output
-history	-H	false	Include historical records/data
-type	-t	None	Filter DNS records by type (A, AAAA, CNAME, etc.)
-details	-D	false	Lookup host details for IPs in domain DNS results
-save	-S	false	Save results into a gzip-compressed JSON file
-ipv6	-6	false	Use IPv6 for -myip check
-facets	-fac	None	List of facets for stats/count/search (default for -stats: country,org)
-filename	-O	None	Save -stats results to a CSV file of the provided name
-timeout	None	0	Stop streaming after N seconds
-format	None	pretty	Output format choice of pretty, tsv, or json
-no-color	-nc	false	Disable colored terminal output
-delay	None	1000	Delay between API requests in milliseconds (0 for no delay)
-stream-type	None	banners	Stream variant: banners, alert, asn, countries, custom, ports, tags, vulns
-stream-filter	None	None	Filter value for stream variant (e.g. ASN list, port list, alert ID)

Bug Bounty Automation

You can easily pipe output from other tools into Shodan. Here are some examples of how to build automation chains

Retrieve IP Addresses for a Target Domain

Find subdomains and extract their IP addresses

shodan -search Ssl.cert.subject.CN:"example.com" -fields ip_str

43.129.159.37
23.2.232.121
38.180.126.110
23.61.208.67
23.42.211.19
...

Get Open Ports for Resolved Hosts

Perform quick checks on a target IP address

shodan -host 146.235.16.165 -format tsv

Export Search Stats to CSV

Collect quick statistics about your target

shodan -stats "tesla.com" -facets country -limit 5 -filename target_stats

Using as a Library

You can import this package to build your own security tools in Go.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/R0X4R/shodan/pkg"
)

func main() {
	client := shodan.New("YOUR_SHODAN_API_KEY")

	// Get public IP address
	ip, err := client.Tools.MyIP(context.Background())
	if err != nil {
		log.Fatalf("Error: %v", err)
	}
	fmt.Printf("IP is %s\n", ip)
}

Contribution

Contributions are welcome. Feel free to open a pull request or submit issues to improve the code.