Shodan.Net.ShodanClient Class Reference

Main mechanism to talk to the shodan api. This is what you should use to interact with the api More...

Inheritance diagram for Shodan.Net.ShodanClient:

Public Member Functions
	ShodanClient (string apikey)
Task< Dictionary< string, string > >	DnsLookupAsync (string hostnames)
	Look up the IP address for the provided list of hostnames. More...
Task< SearchHostResults >	SearchHosts (Action< QueryGenerator > query, Action< FacetGenerator > facet=null, int page=1, bool minify=true)
	Search Shodan 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: More...
Task< SearchHostResults >	SearchHostsCount (Action< QueryGenerator > query, Action< FacetGenerator > facet=null)
	This method behaves identical to SearchHosts(SearchQuery, FacetQuery, int, bool)" 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. More...
Task< SearchTokens >	SearchTokens (Action< QueryGenerator > query)
async Task< double >	Experimental_GetHoneyPotScoreAsync (string ip)
	Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot). More...
Task< ApiStatus >	GetApiStatusAsync ()
	Returns information about the API plan belonging to the given API key. More...
Task< Host >	GetHostAsync (string Ip, bool history=false, bool minify=false)
	Returns all services that have been found on the given host IP. More...
Task< string >	GetMyIpAsync ()
	Get your current IP address as seen from the Internet. More...
Task< List< int > >	GetPortsAsync ()
	This method returns a list of port numbers that the crawlers are looking for. More...
Task< Profile >	GetProfileAsync ()
	Returns information about the Shodan account linked to this API key. More...
Task< Dictionary< string, string > >	GetProtocolsAsync ()
	This method returns an object containing all the protocols that can be used when launching an Internet scan. More...
Task< SearchQueries >	GetQueriesAsync (int?page=null, SortOptions?sort=null, OrderOption?order=null)
	Use this method to obtain a list of search queries that users have saved in Shodan. More...
Task< SearchQueries >	SearchQueriesAsync (string query, int?page=null)
	Use this method to search the directory of search queries that users have saved in Shodan. More...
Task< ScanStatus >	GetScanStatusAsync (string id)
	Check the progress of a previously submitted scan request More...
Task< Dictionary< string, string > >	GetServicesAsync ()
	This method returns an object containing all the services that the Shodan crawlers look at. It can also be used as a quick and practical way to resolve a port number to the name of a service More...
Task< TagResult >	GetTagsAsync (int size=10)
	Use this method to obtain a list of popular tags for the saved search queries in Shodan. More...
Task< ScanPortResult >	RequestInternetPortScanAsync (int port, string protocol)
	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 Data license. To apply for access to this method as a researcher, please email jmath.nosp@m.@sho.nosp@m.dan.i.nosp@m.o with information about your project. Access is restricted to prevent abuse. More...
Task< ScanResult >	RequstScanAsync (string ips)
	Use this method to request Shodan to crawl a network Requirements: 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 More...
Task< Dictionary< string, List< string > > >	ReverseLookupAsync (string ips)
	Look up the hostnames that have been defined for the given list of IP addresses More...
void	Dispose ()

Protected Member Functions
virtual void	Dispose (bool disposing)

Detailed Description

Main mechanism to talk to the shodan api. This is what you should use to interact with the api

Member Function Documentation

Task<Dictionary<string, string> > Shodan.Net.ShodanClient.DnsLookupAsync ( string  hostnames )

inline

Look up the IP address for the provided list of hostnames.

Parameters

hostnames

Comma-separated list of hostnames; example "google.com,bing.com"

Returns

        {
            if(string.IsNullOrWhiteSpace(hostnames))
            {
                throw new ArgumentNullException(hostnames);
            }
            var url = new Uri($"{BasePath}/dns/resolve?hostnames={hostnames}&key={this.apikey}");
            return RequestHandler.MakeRequestAsync<Dictionary<string, string>>(url);
        }

async Task<double> Shodan.Net.ShodanClient.Experimental_GetHoneyPotScoreAsync ( string  ip )

inline

Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).

Parameters

ip

Returns

        {
            if(string.IsNullOrWhiteSpace(ip))
            {
                throw new ArgumentNullException(nameof(ip));
            }
            var url = new Uri($"{BasePath}/labs/honeyscore/{ip}?key={apikey}");
            var result = await RequestHandler.MakeRequestAsync<string>(url);
            double resultParsed;
            if(!double.TryParse(result, out resultParsed))
            {
                throw new ShodanException($"honeypot score returned with {result} failed to parse to double");
            }
            return resultParsed;
        }

Task<ApiStatus> Shodan.Net.ShodanClient.GetApiStatusAsync ( )

inline

Returns information about the API plan belonging to the given API key.

Returns

        {
            var url = new Uri($"{BasePath}/api-info?key={apikey}");
            return RequestHandler.MakeRequestAsync<ApiStatus>(url);
        }

Task<Host> Shodan.Net.ShodanClient.GetHostAsync ( string  Ip, bool  history = false, bool  minify = false  )

inline

Returns all services that have been found on the given host IP.

Parameters

Ip	Host IP address
history	True if all historical banners should be returned (default: False)
minify	True to only return the list of ports and the general host information, no banners. (default: False)

Returns

        {
            if(string.IsNullOrWhiteSpace(Ip))
            {
                throw new ArgumentNullException(nameof(Ip));
            }
            var builder = new UriBuilder($"{BasePath}/shodan/host/{Ip}")
            {
                Query = $"key={this.apikey}&history={history.ToString()}&minify={minify.ToString()}"
            };

            return RequestHandler.MakeRequestAsync<Host>(builder.Uri);
        }

Task<string> Shodan.Net.ShodanClient.GetMyIpAsync ( )

inline

Get your current IP address as seen from the Internet.

Returns

        {
            var url = new Uri($"{BasePath}/tools/myip?key={this.apikey}");
            return RequestHandler.MakeRequestAsync<string>(url);
        }

Task<List<int> > Shodan.Net.ShodanClient.GetPortsAsync ( )

inline

This method returns a list of port numbers that the crawlers are looking for.

Returns

        {
            var builder = new Uri($"{BasePath}/shodan/ports?key={this.apikey}");
            return RequestHandler.MakeRequestAsync<List<int>>(builder);
        }

Task<Profile> Shodan.Net.ShodanClient.GetProfileAsync ( )

inline

Returns information about the Shodan account linked to this API key.

Returns

        {
            var url = new Uri($"{BasePath}/account/profile?key={apikey}");
            return RequestHandler.MakeRequestAsync<Profile>(url);
        }

Task<Dictionary<string, string> > Shodan.Net.ShodanClient.GetProtocolsAsync ( )

inline

This method returns an object containing all the protocols that can be used when launching an Internet scan.

Returns

        {
            var url = new Uri($"{BasePath}/shodan/protocols?key={this.apikey}");
            return RequestHandler.MakeRequestAsync<Dictionary<string, string>>(url);
        }

Task<SearchQueries> Shodan.Net.ShodanClient.GetQueriesAsync ( int?  page = null, SortOptions?  sort = null, OrderOption?  order = null  )

inline

Use this method to obtain a list of search queries that users have saved in Shodan.

Parameters

page	Page number to iterate over results; each page contains 10 items
sort	Sort the list based on a property. Possible values are: votes, timestamp
order	Whether to sort the list in ascending or descending order. Possible values are: asc, desc

Returns

        {
            var url = new UriBuilder($"{BasePath}/shodan/query")
            {
                Query = $"key={apikey}"
            };
            if(sort.HasValue)
            {
                var sortName = Enum.GetName(typeof(SortOptions), sort.Value);
                url.Query = $"{url.Query}&sort={sortName}";
            }
            if(order.HasValue)
            {
                var orderName = Enum.GetName(typeof(OrderOption), order.Value);
                url.Query = $"{url.Query}&order={orderName}";
            }
            return RequestHandler.MakeRequestAsync<SearchQueries>(url.Uri);
        }

Task<ScanStatus> Shodan.Net.ShodanClient.GetScanStatusAsync ( string  id )

inline

Check the progress of a previously submitted scan request

Parameters

id	the unique scan ID that was returned by RequstScanAsync(string)

Returns

        {
            if(string.IsNullOrWhiteSpace(id))
            {
                throw new ArgumentNullException(nameof(id));
            }
            var url = new Uri($"{BasePath}/shodan/scan/{id}");
            return RequestHandler.MakeRequestAsync<ScanStatus>(url);
        }

Task<Dictionary<string, string> > Shodan.Net.ShodanClient.GetServicesAsync ( )

inline

This method returns an object containing all the services that the Shodan crawlers look at. It can also be used as a quick and practical way to resolve a port number to the name of a service

Returns

        {
            var url = new Uri($"{BasePath}/shodan/services?key={this.apikey}");
            return RequestHandler.MakeRequestAsync<Dictionary<string, string>>(url);
        }

Task<TagResult> Shodan.Net.ShodanClient.GetTagsAsync ( int  size = 10 )

inline

Use this method to obtain a list of popular tags for the saved search queries in Shodan.

Parameters

size	The number of tags to return

Returns

        {
            var url = new UriBuilder($"{BasePath}/shodan/query/tags")
            {
                Query = $"key={apikey}&size={size}"
            };
            return RequestHandler.MakeRequestAsync<TagResult>(url.Uri);
        }

Task<ScanPortResult> Shodan.Net.ShodanClient.RequestInternetPortScanAsync ( int  port, string  protocol  )

inline

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 Data license. To apply for access to this method as a researcher, please email jmath.nosp@m.@sho.nosp@m.dan.i.nosp@m.o with information about your project. Access is restricted to prevent abuse.

Parameters

port	The port that Shodan should crawl the Internet for.
protocol	The name of the protocol that should be used to interrogate the port. See GetProtocolsAsync for a list of supported protocols.

Returns

        {
            var url = new Uri($"{BasePath}/shodan/scan/internet?key={this.apikey}");
            using(var data = new FormUrlEncodedContent(new List<KeyValuePair<string, string>>() {
                new KeyValuePair<string, string>("port", port.ToString()),
                new KeyValuePair<string, string>("protocol", protocol)
            }))
            {
                return RequestHandler.MakeRequestAsync<ScanPortResult>(url, data, RequestType.POST);
            }
        }

Task<ScanResult> Shodan.Net.ShodanClient.RequstScanAsync ( string  ips )

inline

Use this method to request Shodan to crawl a network Requirements: 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

Parameters

ips

Returns

        {
            if(string.IsNullOrWhiteSpace(ips))
            {
                throw new ArgumentNullException(nameof(ips));
            }
            if(!ips.Split(',').Any())
            {
                throw new ArgumentOutOfRangeException($"{ips} must have one valid record");
            }
            var url = new Uri($"{BasePath}/shodan/scan?key={this.apikey}");
            using(var data = new FormUrlEncodedContent(new KeyValuePair<string, string>[] { new KeyValuePair<string, string>("ips", ips) }))
            {
                return RequestHandler.MakeRequestAsync<ScanResult>(url, data, RequestType.POST);
            }
        }

Task<Dictionary<string, List<string> > > Shodan.Net.ShodanClient.ReverseLookupAsync ( string  ips )

inline

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

Parameters

ips	Comma-separated list of IP addresses; example "74.125.227.230,204.79.197.200"

Returns

        {
            if(string.IsNullOrWhiteSpace(ips))
            {
                throw new ArgumentNullException(ips);
            }
            var url = new Uri($"{BasePath}/dns/reverse?ips={ips}&key={this.apikey}");
            return RequestHandler.MakeRequestAsync<Dictionary<string, List<string>>>(url);
        }

Task<SearchHostResults> Shodan.Net.ShodanClient.SearchHosts ( Action< QueryGenerator >  query, Action< FacetGenerator >  facet = null, int  page = 1, bool  minify = true  )

inline

Search Shodan 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:

1. The search query contains a filter.
2. Accessing results past the 1st page using the "page". For every 100 results past the 1st page 1 query credit is deducted.

Parameters

query	lambda to generate a query. Shodan search query. The provided string is used to search the database of banners in Shodan, with the additional option to provide filters inside the search query using a "filter:value" format.
facet	static class to define facets.
page	The page number to page through results 100 at a time (default: 1)
minify	True or False; whether or not to truncate some of the larger fields (default: True)

Returns

        {
            if(query == null)
            {
                throw new ArgumentNullException(nameof(query));
            }
            var queryGenerator = new QueryGenerator();
            query.Invoke(queryGenerator);
            var queryResult = queryGenerator.Generate();
            var url = new UriBuilder($"{BasePath}/shodan/host/search")
            {
                Query = $"key={apikey}&query={queryResult}&minify={minify.ToString()}"
            };
            if(facet != null)
            {
                var facetGenerator = new FacetGenerator();
                facet.Invoke(facetGenerator);
                url.Query = $"{url.Query}&facets={facetGenerator.GenerateFacets()}";
            }
            if(page > 1)
            {
                url.Query = $"{url.Query}&page={page}";
            }
            return RequestHandler.MakeRequestAsync<SearchHostResults>(url.Uri);
        }

Task<SearchHostResults> Shodan.Net.ShodanClient.SearchHostsCount ( Action< QueryGenerator >  query, Action< FacetGenerator >  facet = null  )

inline

This method behaves identical to SearchHosts(SearchQuery, FacetQuery, int, bool)" 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.

Parameters

query
facet

Returns

        {
            if(query == null)
            {
                throw new ArgumentNullException(nameof(query));
            }
            var queryGenObj = new QueryGenerator();
            query.Invoke(queryGenObj);

            var url = new UriBuilder($"{BasePath}/shodan/host/count")
            {
                Query = $"key={apikey}&query={queryGenObj.Generate()}"
            };
            if(facet != null)
            {
                var facetGenObj = new FacetGenerator();
                facet.Invoke(facetGenObj);

                url.Query = $"{url.Query}&facets={facetGenObj.GenerateFacets()}";
            }

            return RequestHandler.MakeRequestAsync<SearchHostResults>(url.Uri);
        }

Task<SearchQueries> Shodan.Net.ShodanClient.SearchQueriesAsync ( string  query, int?  page = null  )

inline

Use this method to search the directory of search queries that users have saved in Shodan.

Parameters

query	What to search for in the directory of saved search queries.
page	Page number to iterate over results; each page contains 10 items

Returns

        {
            if(string.IsNullOrWhiteSpace(query))
            {
                throw new ArgumentNullException(query);
            }
            var url = new UriBuilder($"{BasePath}/shodan/query/search")
            {
                Query = $"key={apikey}&query={query}"
            };
            if(page != null)
            {
                url.Query = $"{url.Query}&page={page}";
            }
            return RequestHandler.MakeRequestAsync<SearchQueries>(url.Uri);
        }

---

The documentation for this class was generated from the following file:

• src/Shodan.Net/ShodanClient.cs