shodan-0.1.0.0: src/Shodan.hs
{-# LANGUAGE OverloadedStrings #-}
-- | A small client for the Shodan API.
module Shodan
( Client
, newClient
, newClientWithManager
, ShodanError (..)
, getApiInfo
, countHosts
, CountResult (..)
, Facet (..)
, ApiInfo (..)
, UsageLimits (..)
) where
import Control.Exception (catch)
import Data.Aeson (FromJSON (..), Value, eitherDecode',
withObject, (.!=), (.:!), (.:))
import Data.Map.Strict (Map)
import qualified Data.Map.Strict as Map
import Data.Text (Text)
import qualified Data.Text.Encoding as Text
import qualified Network.HTTP.Client as HTTP
import Network.HTTP.Client.TLS (tlsManagerSettings)
import Network.HTTP.Types (statusCode)
-- | Reuse one client across requests. Its API key is never included in 'show'.
data Client = Client HTTP.Manager Text
instance Show Client where
show _ = "Client <redacted>"
-- | Create a client with certificate-verified HTTPS connections.
-- Pass the key from configuration or an environment variable, not a source file.
newClient :: Text -> IO Client
newClient key = do
manager <- HTTP.newManager tlsManagerSettings
pure (newClientWithManager manager key)
-- | Share an existing manager. It must support TLS for production use.
-- Custom manager hooks can inspect requests, including the key: do not log them.
newClientWithManager :: HTTP.Manager -> Text -> Client
newClientWithManager = Client
-- | Failures deliberately omit raw requests, response bodies, and exception
-- messages, since those may contain the API key. HTTP errors retain the status.
data ShodanError
= NetworkError
| HttpError Int
| InvalidResponse
deriving (Eq, Show)
-- | Retrieve @GET https://api.shodan.io/api-info@.
-- No automatic retries are performed. Redirects are returned as HTTP errors
-- rather than followed, so the key is not forwarded to another endpoint.
-- Transport failures (including timeouts) become 'NetworkError'; asynchronous
-- exceptions, such as thread cancellation, are not caught.
getApiInfo :: Client -> IO (Either ShodanError ApiInfo)
getApiInfo client = getJSON client "/api-info" []
-- | Count matching results without downloading individual banners.
-- Optional facets are not requested, but any returned facets are decoded.
-- According to Shodan's documentation this endpoint uses no query credits.
countHosts :: Client -> Text -> IO (Either ShodanError CountResult)
countHosts client query = getJSON client "/shodan/host/count" [("query", query)]
-- | Total matching results and optional breakdowns from @GET /shodan/host/count@.
data CountResult = CountResult
{ countTotal :: Integer
-- ^ Total number of matching results; must be nonnegative.
, countFacets :: Map Text [Facet]
-- ^ Buckets by facet name, for example @country@ or @port@.
-- An absent @facets@ field is read as an empty map. A present field must
-- be an object of bucket lists; @null@ and malformed entries are rejected.
} deriving (Eq, Show)
instance FromJSON CountResult where
parseJSON = withObject "CountResult" $ \o -> do
total <- o .: "total"
facets <- o .:! "facets" .!= Map.empty
if total < 0
then fail "Count total must not be negative"
else pure (CountResult total facets)
-- | One bucket in a facet breakdown, for example
-- @{"value":"Amazon.com","count":3012386}@.
-- The value is kept as JSON because facet values need not all be strings
-- (a port number, for example, is numeric). Both fields are required;
-- unknown fields are ignored. HTTP facet requests are not supported yet.
data Facet = Facet
{ facetValue :: Value
-- ^ The bucket value, preserved without converting it to text.
, facetCount :: Integer
-- ^ Number of matching results in the bucket; must be nonnegative.
} deriving (Eq, Show)
instance FromJSON Facet where
parseJSON = withObject "Facet" $ \o -> do
value <- o .: "value"
count <- o .: "count"
if count < 0
then fail "Facet count must not be negative"
else pure (Facet value count)
-- Shared transport keeps status handling and key protection consistent.
getJSON :: FromJSON a => Client -> Text -> [(Text, Text)]
-> IO (Either ShodanError a)
getJSON (Client manager key) endpoint parameters = action `catch` handleHttpException
where
request = HTTP.setQueryString
[(Text.encodeUtf8 name, Just (Text.encodeUtf8 value))
| (name, value) <- ("key", key) : parameters]
HTTP.defaultRequest
{ HTTP.secure = True
, HTTP.host = "api.shodan.io"
, HTTP.port = 443
, HTTP.path = Text.encodeUtf8 endpoint
, HTTP.requestHeaders = [("Accept", "application/json")]
, HTTP.redirectCount = 0
, HTTP.responseTimeout = HTTP.responseTimeoutMicro 30000000
, HTTP.checkResponse = \_ _ -> pure ()
}
action = do
response <- HTTP.httpLbs request manager
let status = statusCode (HTTP.responseStatus response)
pure $ if status /= 200
then Left (HttpError status)
else case eitherDecode' (HTTP.responseBody response) of
Left _ -> Left InvalidResponse
Right info -> Right info
handleHttpException :: HTTP.HttpException -> IO (Either ShodanError a)
handleHttpException _ = pure (Left NetworkError)
-- | API plan information returned by @GET /api-info@.
-- Fields follow the official response example; extra JSON fields are ignored.
data ApiInfo = ApiInfo
{ apiInfoScanCredits :: Integer
, apiInfoUsageLimits :: UsageLimits
, apiInfoPlan :: Text
, apiInfoHttps :: Bool
, apiInfoUnlocked :: Bool
, apiInfoQueryCredits :: Integer
, apiInfoMonitoredIps :: Integer
, apiInfoUnlockedLeft :: Integer
, apiInfoTelnet :: Bool
} deriving (Eq, Show)
-- | Usage limits as returned by Shodan, including signed values such as @-1@.
-- Values are preserved without assigning undocumented meanings to them.
data UsageLimits = UsageLimits
{ usageLimitsScanCredits :: Integer
, usageLimitsQueryCredits :: Integer
, usageLimitsMonitoredIps :: Integer
} deriving (Eq, Show)
instance FromJSON ApiInfo where
parseJSON = withObject "ApiInfo" $ \o ->
ApiInfo
<$> o .: "scan_credits"
<*> o .: "usage_limits"
<*> o .: "plan"
<*> o .: "https"
<*> o .: "unlocked"
<*> o .: "query_credits"
<*> o .: "monitored_ips"
<*> o .: "unlocked_left"
<*> o .: "telnet"
instance FromJSON UsageLimits where
parseJSON = withObject "UsageLimits" $ \o ->
UsageLimits
<$> o .: "scan_credits"
<*> o .: "query_credits"
<*> o .: "monitored_ips"