shodan: A simple Haskell client for the Shodan API

[ bsd3, library, network, program ] [ Propose Tags ] [ Report a vulnerability ]

A small Shodan API client using ordinary records and explicit IO functions. Supports API plan information, search result counts, paginated searches, and domain DNS information, with JSON response types for facet statistics. Includes executable examples and local HTTP tests.


[Skip to Readme]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.2.0.0, 0.3.0.0, 0.4.0.0
Change log CHANGELOG.md
Dependencies aeson (>=2.1 && <2.3), base (>=4.19 && <5), containers (>=0.6 && <0.8), http-client (>=0.7 && <0.8), http-client-tls (>=0.3 && <0.4), http-types (>=0.12 && <0.13), shodan, text (>=2.1 && <2.2) [details]
Tested with ghc ==9.8.4
License BSD-3-Clause
Author Joonkyu Park
Maintainer vpark45@gmail.com
Uploaded by JoonkyuPark at 2026-11-20T15:39:30Z
Category Network
Home page https://github.com/nattybear/shodan
Bug tracker https://github.com/nattybear/shodan/issues
Source repo head: git clone https://github.com/nattybear/shodan.git
Distributions
Executables shodan-domain, shodan-search, shodan-count, shodan-api-info
Downloads 10 total (10 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for shodan-0.4.0.0

[back to package description]

shodan

A small Haskell client for the Shodan API.

Licensed under the BSD 3-Clause License.

Current version: 0.4.0.0. See the changelog for additions and the SearchMatch constructor change requiring a PVP major bump.

This project supports GET /api-info (ApiInfo and UsageLimits), GET /shodan/host/count (CountResult), and one-page GET /shodan/host/search (SearchResult), plus one-page GET /dns/domain/{domain} (DomainInfo). The API-info example fields and the count response's total field are required; unknown fields are ignored. Numeric values use Integer; count totals must be nonnegative.

Usage

The executable example in examples/api-info/Main.hs reads the API key from SHODAN_API_KEY, calls /api-info, and prints the plan and remaining query/scan credits. In Bash, enter the key without displaying it or putting it in a command:

read -r -s -p "Shodan API key: " SHODAN_API_KEY
printf '\n'
export SHODAN_API_KEY
cabal run shodan-api-info

Missing or blank keys are rejected before making a request. Errors go to stderr with a nonzero exit status; the key is not printed. This command calls the live Shodan API when a key is present.

To use the library in your own program:

import qualified Data.Text as Text
import Shodan
import System.Environment (getEnv)

main :: IO ()
main = do
  key <- Text.pack <$> getEnv "SHODAN_API_KEY"
  client <- newClient key
  result <- getApiInfo client
  case result of
    Left err -> print err
    Right info -> print (apiInfoPlan info, apiInfoQueryCredits info)

Reuse the client for multiple calls. newClient creates a TLS manager with certificate verification. newClientWithManager lets applications share their own TLS-capable http-client manager.

getApiInfo returns IO (Either ShodanError ApiInfo). Errors distinguish transport failures (NetworkError), non-200 HTTP statuses (HttpError status), and invalid successful responses (InvalidResponse). Raw requests, response bodies, and exception messages are omitted from errors to avoid exposing the key. Showing a Client also hides its key. Custom manager hooks can access the request and must not log the key.

Each request has a 30-second response timeout. Redirects are not followed and there are no automatic retries. Thread cancellation is allowed to propagate.

Count matching results

With SHODAN_API_KEY set, run:

cabal run shodan-count -- 'port:443 country:KR'

Pass the query as one argument, quoting it when it contains spaces. The example prints only the total count. Missing/blank queries or keys are rejected; API errors are printed to stderr with a nonzero exit status.

The library function is:

countHosts :: Client -> Text -> IO (Either ShodanError CountResult)

Read the total with countTotal. For individual search results, use searchHosts as described below. Optional facet requests are not supported yet. According to the official count endpoint documentation, this call uses no query credits.

Facet response type

Facet represents a single statistics bucket such as {"value":"Amazon.com","count":3012386}. Its FromJSON instance is available for standalone parsing and is used by CountResult:

data CountResult = CountResult
  { countTotal  :: Integer
  , countFacets :: Map Text [Facet]
  }

countFacets groups buckets by name, such as country or port. Use Data.Map.Strict.lookup "country" (countFacets result) to read a breakdown. An absent facets field or an empty object produces an empty map. A present facets field must be an object of lists: nulls, incorrect shapes, and invalid buckets are rejected. Bucket order in each list is preserved.

countHosts still sends only the query and key; requesting facets over HTTP will be added separately.

  • facetValue :: Value preserves the JSON value, including strings, numbers, and explicit nulls, without coercing it to text.
  • facetCount :: Integer stores a nonnegative result count.

Both fields are required. Unknown fields are ignored, while missing fields, invalid counts, and non-object buckets are rejected.

Version 0.2.0.0 adds one-page searches:

searchHosts :: Client -> Text -> Int -> IO (Either ShodanError SearchResult)

The page number starts at 1. Values below 1 return Left InvalidPage before any request. Each call retrieves exactly the requested page; additional pages are not fetched automatically. Shodan requires pages past 100 to be requested in order.

With SHODAN_API_KEY set, the executable accepts a query and an optional page (default 1):

cabal run shodan-search -- 'product:nginx country:KR'
cabal run shodan-search -- 'product:nginx country:KR' 2

These commands call Shodan and can use query credits: a filtered query or any page after the first uses a credit under the official API policy. The example prints the total across all pages, the selected page number, the returned service count, and a table of IP, port, product, version, and ASN. Missing product/version/ASN values are displayed as -.

SearchMatch describes one matching service with matchIp, matchPort, matchProduct, matchVersion, and matchAsn. IP text and an integer port from 0 through 65535 are required. Product, version, and ASN are optional: missing or null values become Nothing, while other non-text values are rejected. IP syntax is not validated. Unknown banner fields are ignored.

SearchResult contains searchTotal, searchMatches, and searchFacets. The total covers all pages, while the matches describe one page and preserve service order (multiple services may share an IP). Total and matches are required; the total is a nonnegative Integer. Facets follow the same parsing rules as CountResult.

Search metadata is also available through matchTimestamp :: Maybe Text, matchHostnames :: Maybe [Text], matchDomains :: Maybe [Text], and matchAlpn :: Maybe [Text]. The timestamp is the UTC banner collection time, preserved as text without date validation. Hostnames are based on reverse DNS; these lists do not enumerate all websites hosted on an IP.

matchAlpn reads the nested ssl.alpn list (for example h2, http/1.1). It records Shodan's observation, not the protocol used for our API request. Missing ALPN data does not establish that HTTP/2 or HTTP/3 is unsupported. See the banner specification and TLS fields.

All four metadata fields allow absent or null values as Nothing. Missing or null ssl also produces Nothing for ALPN. A present non-null ssl must be an object; non-text timestamps and lists containing non-text elements are rejected. List order is preserved, and Just [] is distinct from missing data. The CLI adds COLLECTED_UTC, HOSTNAMES, DOMAINS, and ALPN columns. Lists use commas, empty lists display [], and missing values display -.

matchCertificateNames :: Maybe [Text] extracts DNS names from the leaf certificate's ssl.cert.extensions entry named subjectAltName (SAN). The search example displays them in CERTIFICATE_NAMES. Wildcards such as *.example.com and list order are preserved; IP, URI, and email SAN entries are omitted. These are certificate name candidates, not verified DNS mappings, live sites, or a complete subdomain inventory. No DNS lookup or extra API call is made, and the certificate common name is not used as a fallback.

Missing/null certificate or extensions, or no SAN extension, yields Nothing (displayed as -). A present SAN containing no DNS names yields Just [] (displayed as []). The parser handles DER bytes represented as JSON text and literal Python-style byte escapes, as in the official Shodan example. Invalid extension structure, non-text SAN data, and malformed DER reject the response. Other extension contents are ignored. This reads names only; it does not validate certificate signatures, expiry, or domain-name syntax.

Optional facet requests and field selection are not supported yet. Search tests use local JSON fixtures and a mock HTTP server, and do not consume Shodan query credits. A one-page live search has also succeeded manually.

Domain DNS information

Retrieve one page of Shodan's observed subdomains and DNS records:

getDomainInfo :: Client -> Text -> Int -> IO (Either ShodanError DomainInfo)

With SHODAN_API_KEY set, run:

cabal run shodan-domain -- example.com
cabal run shodan-domain -- example.com 2

The optional page defaults to 1. Shodan documents pages of 100 DNS records, but live responses can contain more; use domainMore, not the record count, to decide whether another page is available. According to the official DNS API documentation, each lookup uses one query credit. No extra pages or retries are automatic. Check domainMore before requesting the next page. This endpoint queries Shodan's stored DNS information, not a live DNS lookup, and cannot guarantee that every subdomain is known or that a mapping is still current.

DomainInfo contains domainName, domainTags, domainRecords, domainSubdomains (relative names as returned), and domainMore. Each DnsRecord contains dnsSubdomain, dnsType, dnsValue, and dnsLastSeen. All response fields are required; missing/null fields and wrong JSON types are rejected, while unknown fields are ignored. List order and wildcards are preserved. DNS types, values, and timestamps remain text without syntax validation or IP-only assumptions. An empty record subdomain means the apex domain. The CLI prints fully qualified record names, types, values, and last-seen timestamps, plus relative subdomains and the More flag.

Supply an ASCII domain name (punycode for international names), without a URL or trailing dot. Labels must have 1–63 letters, digits, or hyphens, without a leading/trailing hyphen; the whole name must be at most 253 characters. Invalid names return Left InvalidDomain and pages below 1 return Left InvalidPage, before any HTTP request. The API key is handled through the same client and redacted errors as the other endpoints.

This first implementation uses the API defaults: no history and no DNS record-type filter. /dns/resolve and /dns/reverse are not implemented. Automated DNS parsing and HTTP tests use fixtures and a local server; no query credits are needed. A live domain lookup has also succeeded manually.

Build

The initial development compiler is GHC 9.8.4.

cabal build
cabal test

Approach

  • Use ordinary records, sum types, and explicit IO functions.
  • Add dependencies and language extensions only when needed.
  • Keep API keys out of logs and error messages.
  • Implement one endpoint at a time, beginning with GET /api-info.

Formatting

Use stylish-haskell 0.14.6.0 with the checked-in .stylish-haskell.yaml. To install it with GHC 9.8:

cabal install stylish-haskell-0.14.6.0 --flags=-ghc-lib --constraint='ghc-lib-parser-ex +no-ghc-lib'

With the Cabal executable directory on PATH, run from the project directory:

stylish-haskell -i src/Shodan.hs test/*.hs examples/api-info/Main.hs
stylish-haskell -i examples/count/Main.hs
stylish-haskell -i examples/search/Main.hs examples/domain/Main.hs
cabal test

Files

  • shodan.cabal: package and library settings.
  • cabal.project: local Cabal project settings.
  • CHANGELOG.md: release history and compatibility notes.
  • src/Shodan.hs: client, errors, response records, and JSON parsing.
  • examples/api-info/Main.hs: executable example using an environment variable.
  • examples/count/Main.hs: count-query executable using the same environment variable.
  • examples/search/Main.hs: one-page search executable with an optional page argument.
  • test/Main.hs: response parsing and HTTP tests against a local mock server.
  • examples/domain/Main.hs: one-page domain DNS lookup executable.
  • test/DnsTests.hs: domain and DNS record parsing tests.
  • test/SearchTests.hs: search-response JSON parsing tests.

No API key is needed to build or test. Automated tests do not call Shodan. They check request encoding, successful responses, HTTP errors, invalid JSON, redirect handling, a simulated transport failure, and count responses (including zero, large totals, malformed responses, and query encoding). Live authenticated HTTPS calls to /api-info and /shodan/host/count have also succeeded manually; live calls are not part of the automated test suite.

Standalone facet parsing tests also cover the documented organization example, numeric and null values, zero and large counts, lists of buckets, unknown fields, and malformed or invalid buckets.