Help us shape the future of Go! Take the 2026 Go Developer Survey

shodan

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultBaseURL     = "https://api.shodan.io"
	DefaultExploitsURL = "https://exploits.shodan.io"
	DefaultTrendsURL   = "https://trends.shodan.io"
)
View Source 
const DefaultStreamURL = "https://stream.shodan.io"

Variables

This section is empty.

Functions

func CreateFacetString 

func CreateFacetString(facets []string) string

CreateFacetString converts a list of facets into a comma-separated string. E.g., ["port", "org:google"] -> "port,org:google"

func GetIP 

func GetIP(banner map[string]interface{}) string

GetIP returns the IPv6 address if present, otherwise returns the IPv4 ip_str.

func GetScreenshot 

func GetScreenshot(banner map[string]interface{}) string

GetScreenshot returns the screenshot data if present in the banner.

func HumanizeBytes 

func HumanizeBytes(byteCount int64, precision int) string

HumanizeBytes returns a human-readable representation of bytes.

func IterateFiles 

func IterateFiles(files []string, callback func(banner map[string]interface{}) error) error

IterateFiles yields banners from a slice of file paths (handles .gz and regular text files).

func WriteBanner 

func WriteBanner(w io.Writer, banner map[string]interface{}) error

WriteBanner serializes a banner as JSON and writes it with a trailing newline.

Types

type APIError 

type APIError struct {
	Message string `json:"error"`
}

APIError represents an error returned by the Shodan API.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

type Client struct {

	// Subgroup services
	Data     *DataService
	DNS      *DNSService
	Exploits *ExploitsService
	Trends   *TrendsService
	Labs     *LabsService
	Notifier *NotifierService
	Org      *OrgService
	Tools    *ToolsService
	Stream   *StreamService
	// contains filtered or unexported fields
}

Client is the wrapper around Shodan REST and Streaming APIs.

func New 

func New(apiKey string) *Client

New creates a new Shodan client.

func (*Client) AddAlertNotifier 

func (c *Client) AddAlertNotifier(ctx context.Context, aid, nid string) (map[string]interface{}, error)

AddAlertNotifier enables given notifier for an alert.

func (*Client) AlertTriggers 

func (c *Client) AlertTriggers(ctx context.Context) ([]map[string]interface{}, error)

AlertTriggers returns list of available triggers.

func (*Client) Alerts 

func (c *Client) Alerts(ctx context.Context, aid string, includeExpired bool) (interface{}, error)

Alerts lists all active alerts (if aid is empty) or returns information on a specific alert.

func (*Client) Count 

func (c *Client) Count(ctx context.Context, query string, facets string) (map[string]interface{}, error)

Count returns the total number of search results for the query.

func (*Client) CreateAlert 

func (c *Client) CreateAlert(ctx context.Context, name string, ips []string, expires int) (map[string]interface{}, error)

CreateAlert creates a network alert/private firehose.

func (*Client) DeleteAlert 

func (c *Client) DeleteAlert(ctx context.Context, aid string) (map[string]interface{}, error)

DeleteAlert deletes the alert with the given ID.

func (*Client) DisableAlertTrigger 

func (c *Client) DisableAlertTrigger(ctx context.Context, aid, trigger string) (map[string]interface{}, error)

DisableAlertTrigger disables trigger on the alert.

func (*Client) EditAlert 

func (c *Client) EditAlert(ctx context.Context, aid string, ips []string) (map[string]interface{}, error)

EditAlert edits the monitored IPs of an alert.

func (*Client) EnableAlertTrigger 

func (c *Client) EnableAlertTrigger(ctx context.Context, aid, trigger string) (map[string]interface{}, error)

EnableAlertTrigger enables trigger on the alert.

func (*Client) Host 

func (c *Client) Host(ctx context.Context, ip string, history bool, minify bool) (map[string]interface{}, error)

Host gets all available information for a single IP address. Note: the Shodan /shodan/host/{ip} endpoint only accepts one IP per request.

func (*Client) IgnoreAlertTriggerNotification 

func (c *Client) IgnoreAlertTriggerNotification(ctx context.Context, aid, trigger, ip string, port int, vulns []string) (map[string]interface{}, error)

IgnoreAlertTriggerNotification ignores trigger notifications for a specific IP and port.

func (*Client) Info 

func (c *Client) Info(ctx context.Context) (map[string]interface{}, error)

Info returns information about the current API key.

func (*Client) Ports 

func (c *Client) Ports(ctx context.Context) ([]int, error)

Ports gets a list of ports that Shodan crawls.

func (*Client) Protocols 

func (c *Client) Protocols(ctx context.Context) (map[string]string, error)

Protocols gets a list of protocols that the Shodan on-demand scanning API supports.

func (*Client) Queries 

func (c *Client) Queries(ctx context.Context, page int, sort, order string) (map[string]interface{}, error)

Queries lists shared search queries.

func (*Client) QueriesSearch 

func (c *Client) QueriesSearch(ctx context.Context, query string, page int) (map[string]interface{}, error)

QueriesSearch searches saved search queries.

func (*Client) QueriesTags 

func (c *Client) QueriesTags(ctx context.Context, size int) (map[string]interface{}, error)

QueriesTags lists saved query tags.

func (*Client) RemoveAlertNotifier 

func (c *Client) RemoveAlertNotifier(ctx context.Context, aid, nid string) (map[string]interface{}, error)

RemoveAlertNotifier removes notifier for an alert.

func (*Client) Scan 

func (c *Client) Scan(ctx context.Context, ips []string, force bool) (map[string]interface{}, error)

Scan requests Shodan to scan a network. ips can be a single IP, range, CIDR list, or structured dict.

func (*Client) ScanInternet 

func (c *Client) ScanInternet(ctx context.Context, port int, protocol string) (map[string]interface{}, error)

ScanInternet starts an Internet-wide scan on a specific port and protocol.

func (*Client) ScanStatus 

func (c *Client) ScanStatus(ctx context.Context, scanID string) (map[string]interface{}, error)

ScanStatus gets the status of a previously submitted scan.

func (*Client) Scans 

func (c *Client) Scans(ctx context.Context, page int) (map[string]interface{}, error)

Scans gets a list of scans submitted.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, query string, page int, limit int, offset int, facets string, minify bool, fields []string) (map[string]interface{}, error)

Search searches the Shodan database. Use page for standard pagination. Use limit+offset for fine-grained control.

func (*Client) SearchFacets 

func (c *Client) SearchFacets(ctx context.Context) ([]string, error)

SearchFacets returns a list of search facets.

func (*Client) SearchFilters 

func (c *Client) SearchFilters(ctx context.Context) ([]string, error)

SearchFilters returns a list of search filters.

func (*Client) SearchTokens 

func (c *Client) SearchTokens(ctx context.Context, query string) (map[string]interface{}, error)

SearchTokens returns query token analysis.

func (*Client) Services 

func (c *Client) Services(ctx context.Context) (map[string]interface{}, error)

Services gets a list of services Shodan crawls.

func (*Client) SetBaseURL 

func (c *Client) SetBaseURL(urlStr string)

SetBaseURL changes the main Shodan API URL.

func (*Client) SetExploitsURL 

func (c *Client) SetExploitsURL(urlStr string)

SetExploitsURL changes the Shodan Exploits API URL.

func (*Client) SetRateLimit 

func (c *Client) SetRateLimit(d time.Duration)

SetRateLimit sets the interval duration between requests to avoid rate limits.

func (*Client) SetTrendsURL 

func (c *Client) SetTrendsURL(urlStr string)

SetTrendsURL changes the Shodan Trends API URL.

func (*Client) UnignoreAlertTriggerNotification 

func (c *Client) UnignoreAlertTriggerNotification(ctx context.Context, aid, trigger, ip string, port int) (map[string]interface{}, error)

UnignoreAlertTriggerNotification re-enables trigger notifications.

type DNSService 

type DNSService struct {
	// contains filtered or unexported fields
}

DNSService provides access to the DNS REST API.

func (*DNSService) DomainInfo 

func (s *DNSService) DomainInfo(ctx context.Context, domain string, history bool, dnsType string, page int) (map[string]interface{}, error)

DomainInfo grabs the DNS information for a domain.

type DataService 

type DataService struct {
	// contains filtered or unexported fields
}

DataService provides access to the Data REST API.

func (*DataService) ListDatasets 

func (s *DataService) ListDatasets(ctx context.Context) (interface{}, error)

ListDatasets returns a list of datasets that the user has permission to download.

func (*DataService) ListFiles 

func (s *DataService) ListFiles(ctx context.Context, dataset string) (interface{}, error)

ListFiles returns a list of files that belong to the given dataset.

type ExploitsService 

type ExploitsService struct {
	// contains filtered or unexported fields
}

ExploitsService provides access to the Exploits REST API.

func (*ExploitsService) Count 

func (s *ExploitsService) Count(ctx context.Context, query string, facets string) (map[string]interface{}, error)

Count searches the entire Shodan Exploits archive but only returns the total number of results.

func (*ExploitsService) Search 

func (s *ExploitsService) Search(ctx context.Context, query string, page int, facets string) (map[string]interface{}, error)

Search searches the entire Shodan Exploits archive.

type LabsService 

type LabsService struct {
	// contains filtered or unexported fields
}

LabsService provides access to the Labs REST API.

func (*LabsService) Honeyscore 

func (s *LabsService) Honeyscore(ctx context.Context, ip string) (float64, error)

Honeyscore calculates the probability of an IP being an ICS honeypot (0.0 to 1.0).

type NotifierService 

type NotifierService struct {
	// contains filtered or unexported fields
}

NotifierService provides access to the Notifier REST API.

func (*NotifierService) Create 

func (s *NotifierService) Create(ctx context.Context, provider string, args map[string]interface{}, description string) (map[string]interface{}, error)

Create gets the settings for the specified notifier that a user has configured.

func (*NotifierService) Edit 

func (s *NotifierService) Edit(ctx context.Context, nid string, args map[string]interface{}) (map[string]interface{}, error)

Edit edits the provider arguments for a notifier.

func (*NotifierService) Get 

func (s *NotifierService) Get(ctx context.Context, nid string) (map[string]interface{}, error)

Get gets the settings for the specified notifier.

func (*NotifierService) ListNotifiers 

func (s *NotifierService) ListNotifiers(ctx context.Context) ([]map[string]interface{}, error)

ListNotifiers returns a list of notifiers that the user has added.

func (*NotifierService) ListProviders 

func (s *NotifierService) ListProviders(ctx context.Context) ([]map[string]interface{}, error)

ListProviders returns a list of supported notification providers.

func (*NotifierService) Remove 

func (s *NotifierService) Remove(ctx context.Context, nid string) (map[string]interface{}, error)

Remove deletes the provided notifier.

type OrgService 

type OrgService struct {
	// contains filtered or unexported fields
}

OrgService provides access to the Organization REST API.

func (*OrgService) AddMember 

func (s *OrgService) AddMember(ctx context.Context, usernameOrEmail string, notify bool) (bool, error)

AddMember adds a user to the organization.

func (*OrgService) Info 

func (s *OrgService) Info(ctx context.Context) (map[string]interface{}, error)

Info returns general information about the organization the current user is a member of.

func (*OrgService) RemoveMember 

func (s *OrgService) RemoveMember(ctx context.Context, usernameOrEmail string) (bool, error)

RemoveMember removes the user from the organization.

type StreamEvent 

type StreamEvent struct {
	Data  []byte
	Error error
}

StreamEvent represents a line of data or an error received from the stream.

type StreamService 

type StreamService struct {
	// contains filtered or unexported fields
}

StreamService provides access to the Shodan Streaming API.

func (*StreamService) ASN 

func (s *StreamService) ASN(ctx context.Context, asn []string, timeout time.Duration) (<-chan StreamEvent, error)

ASN streams banners filtered by ASNs.

func (*StreamService) Alert 

func (s *StreamService) Alert(ctx context.Context, alertID string, timeout time.Duration) (<-chan StreamEvent, error)

Alert streams data for a specific alert ID or all alerts if alertID is empty.

func (*StreamService) Banners 

func (s *StreamService) Banners(ctx context.Context, timeout time.Duration) (<-chan StreamEvent, error)

Banners streams all collected banners.

func (*StreamService) Countries 

func (s *StreamService) Countries(ctx context.Context, countries []string, timeout time.Duration) (<-chan StreamEvent, error)

Countries streams banners filtered by countries.

func (*StreamService) Custom 

func (s *StreamService) Custom(ctx context.Context, query string, timeout time.Duration) (<-chan StreamEvent, error)

Custom streams banners filtered by custom query.

func (*StreamService) Ports 

func (s *StreamService) Ports(ctx context.Context, ports []string, timeout time.Duration) (<-chan StreamEvent, error)

Ports streams banners filtered by ports.

func (*StreamService) Tags 

func (s *StreamService) Tags(ctx context.Context, tags []string, timeout time.Duration) (<-chan StreamEvent, error)

Tags streams banners filtered by tags.

func (*StreamService) Vulns 

func (s *StreamService) Vulns(ctx context.Context, vulns []string, timeout time.Duration) (<-chan StreamEvent, error)

Vulns streams banners filtered by vulnerability IDs.

type ToolsService 

type ToolsService struct {
	// contains filtered or unexported fields
}

ToolsService provides access to the Tools REST API.

func (*ToolsService) MyIP 

func (s *ToolsService) MyIP(ctx context.Context) (string, error)

MyIP gets your current IP address as seen from the Internet.

type TrendsService 

type TrendsService struct {
	// contains filtered or unexported fields
}

TrendsService provides access to the Trends REST API.

func (*TrendsService) Search 

func (s *TrendsService) Search(ctx context.Context, query string, facets string) (map[string]interface{}, error)

Search searches the Shodan historical database.

func (*TrendsService) SearchFacets 

func (s *TrendsService) SearchFacets(ctx context.Context) ([]string, error)

SearchFacets returns a list of facets that can be used to get a breakdown of the top values.

func (*TrendsService) SearchFilters 

func (s *TrendsService) SearchFilters(ctx context.Context) ([]string, error)

SearchFilters returns a list of search filters that can be used in search queries.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.