shodan

package module
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Dec 15, 2024 License: MIT Imports: 16 Imported by: 5

README

Shodan API for Golang

GoDoc Build Go Report Card MIT License

Yet another one Golang implementation of Shodan REST API client. This library is inspired by amazing Nikita Safonov's go-shodan library, but has different data models and query syntax.

Features

  • Library intended to be the most comprehensive and documented out there, letting you learn about all the API methods, search filters and gathered data types using method/model comments in this repo
  • Search syntax allows you to change query without string formatting:
package main

import (
	"context"
	"github.com/shadowscatcher/shodan"
	"github.com/shadowscatcher/shodan/search"
	"github.com/shadowscatcher/shodan/search/ssl_versions"
	"log"
	"net/http"
	"os"
)

func main() {
	nginxSearch := search.Params{
		Page:1,
		Query: search.Query{
			Product: "nginx",
			ASN:  "AS14618",
			SSLOpts: search.SSLOpts{
				Cert: search.CertOptions{
					Expired: true,
				},
				Version: ssl_versions.TLSv1_2,
			},
		},
	}

	client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
	ctx := context.Background()
	result, err := client.Search(ctx, nginxSearch)
	if err != nil {
		log.Fatal(err)
	}

	for _, match := range result.Matches {
		// a lot of returned data can be used in another searches
		// it's easy because you will get response with almost all possible fields, just don't forget to check them
		if match.HTTP != nil && match.HTTP.Favicon != nil {
			//newQuery := search.Query{HTTP: search.HTTP{Favicon: search.Favicon{Hash: match.HTTP.Favicon.Hash}}}
		}
	}
	
	// later on you can change every part of search query or parameters:
	nginxSearch.Page++  // for example, increase page
	nginxSearch.Query.Port = 443 // or add new search term
	result, err = client.Search(ctx, nginxSearch)  // and reuse modified parameters object
	if err != nil {
		log.Fatal(err)
	}
}
  • Search results contain a lot of types that are ignored by most of the existing libraries, documented where possible:
for _, match := range result.Matches {
	if match.MongoDB != nil && !match.MongoDB.Authentication {
		fmt.Println("exposed mongodb:", match.IpAndPort())
		databases := match.MongoDB.ListDatabases.Databases

		fmt.Println("databases:", len(databases), "size:", match.MongoDB.ListDatabases.TotalSize)
		for _, db := range databases {
			for _, collectionName := range db.Collections {
				fmt.Println(collectionName)
			}
		}
	}
		
	if match.SSL != nil && match.SSL.Cert.Expired {
		fmt.Println("expired certificate:", match.IpAndPort())
	}
		
	if match.Elastic != nil {
		fmt.Println("exposed elastic:", match.IpAndPort())
		for indexName, index := range match.Elastic.Indices {
			fmt.Println(indexName, index.UUID)
		}
	}
}
  • The client can be configured to automatically make one second pause between requests (this interval required by Shodan's API terms of service).

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	HTTP *http.Client
	// contains filtered or unexported fields
}

Client is a type with all non-stream methods. Use GetClient to create instance

func GetClient 

func GetClient(apiKey string, client *http.Client, wait bool) (*Client, error)

GetClient creates Client instance. apiKey is required to work with API. If you want to use a proxy, configure http.Client. If you need to disable throttling, set wait to false

func (*Client) AccountProfile 

func (c *Client) AccountProfile(ctx context.Context) (result models.Profile, err error)

AccountProfile returns information about the Shodan account linked to this API key

func (*Client) AddAlertNotifier 

func (c *Client) AddAlertNotifier(ctx context.Context, alertID, notifierID string) (result models.SimpleResponse, err error)

AddAlertNotifier enables the given notifier for an alert that has triggers enabled

func (*Client) AddOrgMember 

func (c *Client) AddOrgMember(ctx context.Context, username string, notify bool) (result models.SimpleResponse, err error)

AddOrgMember adds a Shodan user to the organization and upgrades them

func (*Client) AlertInfo 

func (c *Client) AlertInfo(ctx context.Context, alertID string) (result models.AlertDetails, err error)

AlertInfo returns the information about a specific network alert

func (*Client) ApiInfo 

func (c *Client) ApiInfo(ctx context.Context) (result models.ApiInfo, err error)

ApiInfo returns information about the API plan belonging to the given API key

func (*Client) Count 

func (c *Client) Count(ctx context.Context, params search.Params) (result models.SearchResult, err error)

Count searches Shodan without results This method behaves identical to Search() with the only difference that this method does not return any host results, it only returns the total number of results that matched the query and any facet information that was requested. As a result this method does not consume query credits.

func (*Client) CreateAlert 

func (c *Client) CreateAlert(ctx context.Context, alert models.Alert) (result models.AlertDetails, err error)

CreateAlert allows to create a network alert for a defined IP/ netblock which can be used to subscribe to changes/events that are discovered within that range

func (*Client) CreateAlertTrigger 

func (c *Client) CreateAlertTrigger(ctx context.Context, alertID, triggerName string) (result models.SimpleResponse, err error)

CreateAlertTrigger allows to get notifications when the specified trigger is met

func (*Client) CreateNotifier 

func (c *Client) CreateNotifier(ctx context.Context, provider models.NotifierProvider) (result models.NotifierResponse, err error)

CreateNotifier creates a notifier for alert triggers. Use one of models.Create*Provider functions to easily create required provider type for your personal notifications feed.

func (*Client) CreateTriggerIgnore 

func (c *Client) CreateTriggerIgnore(ctx context.Context, alertID, triggerName, service string) (result models.SimpleResponse, err error)

CreateTriggerIgnore allows to ignore the specified service when it is matched for the trigger

func (*Client) DatasetFiles 

func (c *Client) DatasetFiles(ctx context.Context, dataset string) (result []models.DatasetFile, err error)

DatasetFiles alloows to get a list of files that are available for download from the provided dataset

func (*Client) Datasets 

func (c *Client) Datasets(ctx context.Context) (result []models.Dataset, err error)

Datasets allows to see a list of the datasets that are available for download

func (*Client) DeleteAlert 

func (c *Client) DeleteAlert(ctx context.Context, alertID string) (result interface{}, err error)

DeleteAlert allows to remove the specified network alert

func (*Client) DeleteAlertNotifier 

func (c *Client) DeleteAlertNotifier(ctx context.Context, alertID, notifierID string) (result models.SimpleResponse, err error)

DeleteAlertNotifier removes the given notifier for an alert that has triggers enabled

func (*Client) DeleteAlertTrigger 

func (c *Client) DeleteAlertTrigger(ctx context.Context, alertID, triggerName string) (result models.SimpleResponse, err error)

DeleteAlertTrigger stops notifications for the specified trigger

func (*Client) DeleteNotifier 

func (c *Client) DeleteNotifier(ctx context.Context, notifierID string) (result models.SimpleResponse, err error)

DeleteNotifier uses notifier ID to delete it from registered list

func (*Client) DeleteOrgMember 

func (c *Client) DeleteOrgMember(ctx context.Context, username string) (result models.SimpleResponse, err error)

DeleteOrgMember allows to remove and downgrade the provided member from the organization

func (*Client) DeleteTriggerIgnore 

func (c *Client) DeleteTriggerIgnore(ctx context.Context, alertID, triggerName, service string) (result models.SimpleResponse, err error)

DeleteTriggerIgnore enables notifications again for the specified trigger

func (*Client) DnsDomain 

func (c *Client) DnsDomain(ctx context.Context, query search.DomainQuery) (result models.Domain, err error)

DnsDomain returns a collection of historical NS records for domain

func (*Client) DnsResolve 

func (c *Client) DnsResolve(ctx context.Context, hostnames []string) (result map[string]string, err error)

DnsResolve looks up the IP address for the provided list of hostnames

func (*Client) DnsReverse 

func (c *Client) DnsReverse(ctx context.Context, ips []string) (result map[string][]string, err error)

DnsReverse looks up the hostnames that have been defined for the given list of IP addresses

func (*Client) EditAlert 

func (c *Client) EditAlert(ctx context.Context, alertID string, filter models.Filter) (result models.AlertDetails, err error)

EditAlert allows to edit the IPs that should be monitored by the alert

func (*Client) EditNotifier 

func (c *Client) EditNotifier(ctx context.Context, notifierID string, provider models.NotifierProvider) (result models.SimpleResponse, err error)

EditNotifier allows to change existing notifier provider

func (*Client) ExploitCount 

func (c *Client) ExploitCount(ctx context.Context, params search.ExploitParams) (result models.ExploitResult, err error)

ExploitCount behaves identical to the exploits "/search" method with the difference that it doesn't return any results

func (*Client) ExploitSearch 

func (c *Client) ExploitSearch(ctx context.Context, params search.ExploitParams) (result models.ExploitResult, err error)

ExploitSearch allows to search across a variety of data sources for exploits and use facets to get summary information

func (*Client) Facets 

func (c *Client) Facets(ctx context.Context) (result []string, err error)

Facets returns a list of facets that can be used to get a breakdown of the top values for a property

func (*Client) Filters 

func (c *Client) Filters(ctx context.Context) (result []string, err error)

Filters returns a list of search filters that can be used in the search query

func (*Client) GetNotifier 

func (c *Client) GetNotifier(ctx context.Context, notifierID string) (result models.NotifierDescriptor, err error)

GetNotifier returns registered notifier descriptor by notifier ID

func (*Client) GetScan 

func (c *Client) GetScan(ctx context.Context, scanID string) (result models.Scan, err error)

GetScan checks the progress of a previously submitted scan request

func (*Client) Honeyscore 

func (c *Client) Honeyscore(ctx context.Context, ip string) (result float32, err error)

Honeyscore calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot)

func (*Client) Host 

func (c *Client) Host(ctx context.Context, params search.HostParams) (result models.Host, err error)

Host returns all services that have been found on the given host IP

func (*Client) HttpHeaders 

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

HttpHeaders shows the HTTP headers that your client sends when connecting to a webserver

func (*Client) ListAlerts 

func (c *Client) ListAlerts(ctx context.Context) (result []models.AlertDetails, err error)

ListAlerts returns a listing of all the network alerts that are currently active on the account

func (*Client) ListNotifierProviders 

func (c *Client) ListNotifierProviders(ctx context.Context) (result map[models.NotifierProviderType]models.ProviderRequirements, err error)

ListNotifierProviders returns a collection of required fields for all existing notifier provider types

func (*Client) ListNotifiers 

func (c *Client) ListNotifiers(ctx context.Context) (result models.NotifierList, err error)

ListNotifiers returns a collection of registered notifiers

func (*Client) ListScans 

func (c *Client) ListScans(ctx context.Context, page uint) (result models.ScanList, err error)

ListScans returns a list of all your scans

func (*Client) ListTriggers 

func (c *Client) ListTriggers(ctx context.Context) (result []models.Trigger, err error)

ListTriggers returns a list of all the triggers that can be enabled on network alerts

func (*Client) MyIP 

func (c *Client) MyIP(ctx context.Context) (result string, err error)

MyIP allows to get your current IP address as seen from the Internet

func (*Client) Org 

func (c *Client) Org(ctx context.Context) (result models.Org, err error)

Org allows to get information about your organization such as the list of its members, upgrades, authorized domains and more

func (*Client) Ports 

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

Ports returns a list of port numbers that the crawlers are looking for

func (*Client) Protocols 

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

Protocols returns a map containing all the protocols that can be used when launching an Internet scan

func (*Client) QueryList 

func (c *Client) QueryList(ctx context.Context, page uint, sort, order string) (result models.SearchQueries, err error)

QueryList use this method to obtain a list of search queries that users have saved in Shodan. page (optional): Page number to iterate over results; each page contains 10 items. sort (optional): Sort the list based on a property. Possible values are: votes, timestamp. order (optional): Whether to sort the list in ascending or descending order. Possible values are: asc, desc.

func (*Client) QuerySearch 

func (c *Client) QuerySearch(ctx context.Context, query string, page uint) (result models.SearchQueries, err error)

QuerySearch allows to search the directory of search queries that users have saved in Shodan

func (*Client) QueryTags 

func (c *Client) QueryTags(ctx context.Context, size uint) (result models.QueryTags, err error)

QueryTags allows to obtain a list of popular tags for the saved search queries in Shodan

func (*Client) ScanInternet 

func (c *Client) ScanInternet(ctx context.Context, port uint16, protocol string) (result models.Scan, err error)

ScanInternet use this method to request Shodan to crawl the Internet for a specific port. This method is restricted to security researchers and companies with a Shodan Enterprise Data license. To apply for access to this method as a researcher, please email jmath@shodan.io with information about your project. Access is restricted to prevent abuse.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, params search.Params) (result models.SearchResult, err error)

Search using the same query syntax as the website and use facets to get summary information for different properties This method may use API query credits depending on usage. If any of the following criteria are met, your account will be deducated 1 query credit: * The search query contains a filter. * Accessing results past the 1st page using the "page". For every 100 results past the 1st page 1 query credit is deducted.

func (*Client) SearchTokens 

func (c *Client) SearchTokens(ctx context.Context, params search.Params) (result models.Tokens, err error)

SearchTokens allows to break the search query into tokens This method lets you determine which filters are being used by the query string and what parameters were provided to the filters.

func (*Client) Services 

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

Services returns a map containing all the services Shodan can detect

func (*Client) SubmitScan 

func (c *Client) SubmitScan(ctx context.Context, ips []string, force bool) (result models.Scan, err error)

SubmitScan requests Shodan to crawl an IP/netblock This method uses API scan credits: 1 IP consumes 1 scan credit. You must have a paid API plan (either one-time payment or subscription) in order to use this method

type StreamClient 

type StreamClient struct {
	HTTP *http.Client
	// StreamResponseHook allows you to intercept response before stream reading. If it returns an error, method exits
	ResponseHook func(response *http.Response, err error) error
	// contains filtered or unexported fields
}

StreamClient is a client with all stream-related methods. Use GetStreamClient to create instance

func GetStreamClient 

func GetStreamClient(key string, client *http.Client) (*StreamClient, error)

GetStreamClient creates StreamClient instance. If you want to use a proxy, configure http.Client.

func (*StreamClient) ASN 

func (s *StreamClient) ASN(ctx context.Context, asns []string) (chan models.Service, error)

ASN stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain ASNs

func (*StreamClient) Alert 

func (s *StreamClient) Alert(ctx context.Context, alertID string) (chan models.Service, error)

Alert stream allows to subscribe to banners discovered on the IP range defined in a specific network alert

func (*StreamClient) Alerts 

func (s *StreamClient) Alerts(ctx context.Context) (chan models.Service, error)

Alerts stream allows to subscribe to banners discovered on all IP ranges described in the network alert

func (*StreamClient) Banners 

func (s *StreamClient) Banners(ctx context.Context) (chan models.Service, error)

Banners stream provides ALL of the data that Shodan collects. Use this stream if you need access to everything and/or want to store your own Shodan database locally. If you only care about specific ports, please use the Ports stream

func (*StreamClient) Countries 

func (s *StreamClient) Countries(ctx context.Context, countries []string) (chan models.Service, error)

Countries stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain countries

func (*StreamClient) Ports 

func (s *StreamClient) Ports(ctx context.Context, ports []int) (chan models.Service, error)

Ports stream only returns banner data for the list of specified ports. This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in a specific list of ports.

func (*StreamClient) Tags 

func (s *StreamClient) Tags(ctx context.Context, tags []string) (chan models.Service, error)

Tags is a filtered version of the "banners" stream to only return banners that match the tags of interest

func (*StreamClient) Vulns added in v1.0.2 

func (s *StreamClient) Vulns(ctx context.Context, vulns []string) (chan models.Service, error)

Vulns is a filtered version of the "banners" stream to only return banners that match the vulnerabilities of interest

Source Files

View all Source files

Directories

Path Synopsis
services
tags
exploit_types
link_types
ssl_versions
triggers

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.