shodan (empty) → 0.1.0.0
raw patch · 8 files changed
+1228/−0 lines, 8 filesdep +aesondep +basedep +bytestring
Dependencies added: aeson, base, bytestring, containers, http-client, http-client-tls, http-types, shodan, text, wai, warp
Files
- .stylish-haskell.yaml +481/−0
- LICENSE +29/−0
- README.md +162/−0
- examples/api-info/Main.hs +30/−0
- examples/count/Main.hs +25/−0
- shodan.cabal +74/−0
- src/Shodan.hs +176/−0
- test/Main.hs +251/−0
+ .stylish-haskell.yaml view
@@ -0,0 +1,481 @@+# stylish-haskell configuration file+# ==================================++# The stylish-haskell tool is mainly configured by specifying steps. These steps+# are a list, so they have an order, and one specific step may appear more than+# once (if needed). Each file is processed by these steps in the given order.+steps:+ # Convert some ASCII sequences to their Unicode equivalents. This is disabled+ # by default.+ # - unicode_syntax:+ # # In order to make this work, we also need to insert the UnicodeSyntax+ # # language pragma. If this flag is set to true, we insert it when it's+ # # not already present. You may want to disable it if you configure+ # # language extensions using some other method than pragmas. Default:+ # # true.+ # add_language_pragma: true++ # Format module header+ #+ # Currently, this option is not configurable and will format all exports and+ # module declarations to minimize diffs+ #+ # - module_header:+ # # How many spaces use for indentation in the module header.+ # indent: 4+ #+ # # Should export lists be sorted? Sorting is only performed within the+ # # export section, as delineated by Haddock comments.+ # sort: true+ #+ # # See `separate_lists` for the `imports` step.+ # separate_lists: true+ #+ # # When to break the "where".+ # # Possible values:+ # # - exports: only break when there is an explicit export list.+ # # - single: only break when the export list counts more than one export.+ # # - inline: only break when the export list is too long. This is+ # # determined by the `columns` setting. Not applicable when the export+ # # list contains comments as newlines will be required.+ # # - always: always break before the "where".+ # break_where: exports+ #+ # # Where to put open bracket+ # # Possible values:+ # # - same_line: put open bracket on the same line as the module name, before the+ # # comment of the module+ # # - next_line: put open bracket on the next line, after module comment+ # open_bracket: next_line++ # Format record definitions. This is disabled by default.+ #+ # You can control the layout of record fields. The only rules that can't be configured+ # are these:+ #+ # - "|" is always aligned with "="+ # - "," in fields is always aligned with "{"+ # - "}" is likewise always aligned with "{"+ #+ # - records:+ # # How to format equals sign between type constructor and data constructor.+ # # Possible values:+ # # - "same_line" -- leave "=" AND data constructor on the same line as the type constructor.+ # # - "indent N" -- insert a new line and N spaces from the beginning of the next line.+ # equals: "indent 2"+ #+ # # How to format first field of each record constructor.+ # # Possible values:+ # # - "same_line" -- "{" and first field goes on the same line as the data constructor.+ # # - "indent N" -- insert a new line and N spaces from the beginning of the data constructor+ # first_field: "indent 2"+ #+ # # How many spaces to insert between the column with "," and the beginning of the comment in the next line.+ # field_comment: 2+ #+ # # How many spaces to insert before "deriving" clause. Deriving clauses are always on separate lines.+ # deriving: 2+ #+ # # How many spaces to insert before "via" clause counted from indentation of deriving clause+ # # Possible values:+ # # - "same_line" -- "via" part goes on the same line as "deriving" keyword.+ # # - "indent N" -- insert a new line and N spaces from the beginning of "deriving" keyword.+ # via: "indent 2"+ #+ # # Sort typeclass names in the "deriving" list alphabetically.+ # sort_deriving: true+ #+ # # Whether or not to break enums onto several lines+ # #+ # # Default: false+ # break_enums: false+ #+ # # Whether or not to break single constructor data types before `=` sign+ # #+ # # Default: true+ # break_single_constructors: true+ #+ # # Whether or not to curry constraints on function.+ # #+ # # E.g: @allValues :: Enum a => Bounded a => Proxy a -> [a]@+ # #+ # # Instead of @allValues :: (Enum a, Bounded a) => Proxy a -> [a]@+ # #+ # # Default: false+ # curried_context: false++ # Align the right hand side of some elements. This is quite conservative+ # and only applies to statements where each element occupies a single+ # line.+ # Possible values:+ # - always - Always align statements.+ # - adjacent - Align statements that are on adjacent lines in groups.+ # - never - Never align statements.+ # All default to always.+ - simple_align:+ cases: always+ top_level_patterns: always+ records: always+ multi_way_if: always++ # Import cleanup+ - imports:+ # There are different ways we can align names and lists.+ #+ # - global: Align the import names and import list throughout the entire+ # file.+ #+ # - file: Like global, but don't add padding when there are no qualified+ # imports in the file.+ #+ # - group: Only align the imports per group (a group is formed by adjacent+ # import lines).+ #+ # - none: Do not perform any alignment.+ #+ # Default: global.+ align: global++ # The following options affect only import list alignment.+ #+ # List align has following options:+ #+ # - after_alias: Import list is aligned with end of import including+ # 'as' and 'hiding' keywords.+ #+ # > import qualified Data.List as List (concat, foldl, foldr, head,+ # > init, last, length)+ #+ # - with_alias: Import list is aligned with start of alias or hiding.+ #+ # > import qualified Data.List as List (concat, foldl, foldr, head,+ # > init, last, length)+ #+ # - with_module_name: Import list is aligned `list_padding` spaces after+ # the module name.+ #+ # > import qualified Data.List as List (concat, foldl, foldr, head,+ # init, last, length)+ #+ # This is mainly intended for use with `pad_module_names: false`.+ #+ # > import qualified Data.List as List (concat, foldl, foldr, head,+ # init, last, length, scanl, scanr, take, drop,+ # sort, nub)+ #+ # - new_line: Import list starts always on new line.+ #+ # > import qualified Data.List as List+ # > (concat, foldl, foldr, head, init, last, length)+ #+ # - repeat: Repeat the module name to align the import list.+ #+ # > import qualified Data.List as List (concat, foldl, foldr, head)+ # > import qualified Data.List as List (init, last, length)+ #+ # Default: after_alias+ list_align: after_alias++ # Right-pad the module names to align imports in a group:+ #+ # - true: a little more readable+ #+ # > import qualified Data.List as List (concat, foldl, foldr,+ # > init, last, length)+ # > import qualified Data.List.Extra as List (concat, foldl, foldr,+ # > init, last, length)+ #+ # - false: diff-safe+ #+ # > import qualified Data.List as List (concat, foldl, foldr, init,+ # > last, length)+ # > import qualified Data.List.Extra as List (concat, foldl, foldr,+ # > init, last, length)+ #+ # Default: true+ pad_module_names: true++ # Long list align style takes effect when import is too long. This is+ # determined by 'columns' setting.+ #+ # - inline: This option will put as much specs on same line as possible.+ #+ # - new_line: Import list will start on new line.+ #+ # - new_line_multiline: Import list will start on new line when it's+ # short enough to fit to single line. Otherwise it'll be multiline.+ #+ # - multiline: One line per import list entry.+ # Type with constructor list acts like single import.+ #+ # > import qualified Data.Map as M+ # > ( empty+ # > , singleton+ # > , ...+ # > , delete+ # > )+ #+ # Default: inline+ long_list_align: inline++ # Align empty list (importing instances)+ #+ # Empty list align has following options+ #+ # - inherit: inherit list_align setting+ #+ # - right_after: () is right after the module name:+ #+ # > import Vector.Instances ()+ #+ # Default: inherit+ empty_list_align: inherit++ # List padding determines indentation of import list on lines after import.+ # This option affects 'long_list_align'.+ #+ # - <integer>: constant value+ #+ # - module_name: align under start of module name.+ # Useful for 'file' and 'group' align settings.+ #+ # Default: 4+ list_padding: 4++ # Separate lists option affects formatting of import list for type+ # or class. The only difference is single space between type and list+ # of constructors, selectors and class functions.+ #+ # - true: There is single space between Foldable type and list of it's+ # functions.+ #+ # > import Data.Foldable (Foldable (fold, foldl, foldMap))+ #+ # - false: There is no space between Foldable type and list of it's+ # functions.+ #+ # > import Data.Foldable (Foldable(fold, foldl, foldMap))+ #+ # Default: true+ separate_lists: true++ # Space surround option affects formatting of import lists on a single+ # line. The only difference is single space after the initial+ # parenthesis and a single space before the terminal parenthesis.+ #+ # - true: There is single space associated with the enclosing+ # parenthesis.+ #+ # > import Data.Foo ( foo )+ #+ # - false: There is no space associated with the enclosing parenthesis+ #+ # > import Data.Foo (foo)+ #+ # Default: false+ space_surround: false++ # Post qualify option moves any qualifies found in import declarations+ # to the end of the declaration. This also adjust padding for any+ # unqualified import declarations.+ #+ # - true: Qualified as <module name> is moved to the end of the+ # declaration.+ #+ # > import Data.Bar+ # > import Data.Foo qualified as F+ #+ # - false: Qualified remains in the default location and unqualified+ # imports are padded to align with qualified imports.+ #+ # > import Data.Bar+ # > import qualified Data.Foo as F+ #+ # Default: false+ post_qualify: false++ # Automatically group imports based on their module names, with+ # a blank line separating each group. Groups are ordered in+ # alphabetical order.+ #+ # By default, this groups by the first part of each module's+ # name (Control.* will be grouped together, Data.*... etc), but+ # this can be configured with the group_patterns setting.+ #+ # When enabled, this rewrites existing blank lines and groups.+ #+ # - true: Group imports by the first part of the module name.+ #+ # > import Control.Applicative+ # > import Control.Monad+ # > import Control.Monad.MonadError+ # >+ # > import Data.Functor+ #+ # - false: Keep import groups as-is (still sorting and+ # formatting the imports within each group)+ #+ # > import Control.Monad+ # > import Data.Functor+ # >+ # > import Control.Applicative+ # > import Control.Monad.MonadError+ #+ # Default: false+ group_imports: false++ # A list of rules specifying how to group modules and how to+ # order the groups.+ #+ # Each rule has a match field; the rule only applies to module+ # names matched by this pattern. Patterns are POSIX extended+ # regular expressions; see the documentation of Text.Regex.TDFA+ # for details:+ # https://hackage.haskell.org/package/regex-tdfa-1.3.1.2/docs/Text-Regex-TDFA.html+ #+ # Rules are processed in order, so only the *first* rule that+ # matches a specific module will apply. Any module names that do+ # not match a single rule will be put into a single group at the+ # end of the import block.+ #+ # Example: group MyApp modules first, with everything else in+ # one group at the end.+ #+ # group_rules:+ # - match: "^MyApp\\>"+ #+ # > import MyApp+ # > import MyApp.Foo+ # >+ # > import Control.Monad+ # > import MyApps+ # > import Test.MyApp+ #+ # A rule can also optionally have a sub_group pattern. Imports+ # that match the rule will be broken up into further groups by+ # the part of the module name matched by the sub_group pattern.+ #+ # Example: group MyApp modules first, then everything else+ # sub-grouped by the first part of the module name.+ #+ # group_rules:+ # - match: "^MyApp\\>"+ # - match: "."+ # sub_group: "^[^.]+"+ #+ # > import MyApp+ # > import MyApp.Foo+ # >+ # > import Control.Applicative+ # > import Control.Monad+ # >+ # > import Data.Map+ #+ # A pattern only needs to match part of the module name, which+ # could be in the middle. You can use ^pattern to anchor to the+ # beginning of the module name, pattern$ to anchor to the end+ # and ^pattern$ to force a full match. Example:+ #+ # - "Test\\." would match "Test.Foo" and "Foo.Test.Lib"+ # - "^Test\\." would match "Test.Foo" but not "Foo.Test.Lib"+ # - "\\.Test$" would match "Foo.Test" but not "Foo.Test.Lib"+ # - "^Test$" would *only* match "Test"+ #+ # You can use \\< and \\> to anchor against the beginning and+ # end of words, respectively. For example:+ #+ # - "^Test\\." would match "Test.Foo" but not "Test" or "Tests"+ # - "^Test\\>" would match "Test.Foo" and "Test", but not+ # "Tests"+ #+ # The default is a single rule that matches everything and+ # sub-groups based on the first component of the module name.+ #+ # Default: [{ "match" : ".*", "sub_group": "^[^.]+" }]+ group_rules:+ - match: ".*"+ sub_group: "^[^.]+"++ # Language pragmas+ - language_pragmas:+ # We can generate different styles of language pragma lists.+ #+ # - vertical: Vertical-spaced language pragmas, one per line.+ #+ # - compact: A more compact style.+ #+ # - compact_line: Similar to compact, but wrap each line with+ # `{-# LANGUAGE #-}'.+ #+ # - vertical_compact: Similar to vertical, but use only one language pragma.+ #+ # Default: vertical.+ style: vertical++ # Align affects alignment of closing pragma brackets.+ #+ # - true: Brackets are aligned in same column.+ #+ # - false: Brackets are not aligned together. There is only one space+ # between actual import and closing bracket.+ #+ # Default: true+ align: true++ # stylish-haskell can detect redundancy of some language pragmas. If this+ # is set to true, it will remove those redundant pragmas. Default: true.+ remove_redundant: true++ # Language prefix to be used for pragma declaration, this allows you to+ # use other options non case-sensitive like "language" or "Language".+ # If a non correct String is provided, it will default to: LANGUAGE.+ language_prefix: LANGUAGE++ # Replace tabs by spaces. This is disabled by default.+ # - tabs:+ # # Number of spaces to use for each tab. Default: 8, as specified by the+ # # Haskell report.+ # spaces: 8++ # Remove trailing whitespace+ - trailing_whitespace: {}++ # Squash multiple spaces between the left and right hand sides of some+ # elements into single spaces. Basically, this undoes the effect of+ # simple_align but is a bit less conservative.+ # - squash: {}++# A common setting is the number of columns (parts of) code will be wrapped+# to. Different steps take this into account.+#+# Set this to null to disable all line wrapping.+#+# Default: 80.+columns: 80++# By default, line endings are converted according to the OS. You can override+# preferred format here.+#+# - native: Native newline format. CRLF on Windows, LF on other OSes.+#+# - lf: Convert to LF ("\n").+#+# - crlf: Convert to CRLF ("\r\n").+#+# Default: native.+newline: native++# Sometimes, language extensions are specified in a cabal file or from the+# command line instead of using language pragmas in the file. stylish-haskell+# needs to be aware of these, so it can parse the file correctly.+#+# No language extensions are enabled by default.+# language_extensions:+ # - TemplateHaskell+ # - QuasiQuotes++# Attempt to find the cabal file in ancestors of the current directory, and+# parse options (currently only language extensions) from that.+#+# Default: true+cabal: true
+ LICENSE view
@@ -0,0 +1,29 @@+BSD 3-Clause License++Copyright (c) 2026, Joonkyu Park+All rights reserved.++Redistribution and use in source and binary forms, with or without+modification, are permitted provided that the following conditions are met:++1. Redistributions of source code must retain the above copyright notice, this+ list of conditions and the following disclaimer.++2. Redistributions in binary form must reproduce the above copyright notice,+ this list of conditions and the following disclaimer in the documentation+ and/or other materials provided with the distribution.++3. Neither the name of the copyright holder nor the names of its contributors+ may be used to endorse or promote products derived from this software+ without specific prior written permission.++THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ README.md view
@@ -0,0 +1,162 @@+# shodan++A small Haskell client for the [Shodan API](https://developer.shodan.io/api).++Licensed under the [BSD 3-Clause License](LICENSE).++This project currently supports `GET /api-info` (`ApiInfo` and `UsageLimits`)+and `GET /shodan/host/count` (`CountResult`). 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:++```sh+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:++```haskell+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:++```sh+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:++```haskell+countHosts :: Client -> Text -> IO (Either ShodanError CountResult)+```++Read the total with `countTotal`. Optional facet requests and individual search+results are not supported yet. According to the [official count endpoint+documentation](https://developer.shodan.io/api), 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`:++```haskell+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.++## Build++The initial development compiler is GHC 9.8.4.++```sh+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:++```sh+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:++```sh+stylish-haskell -i src/Shodan.hs test/Main.hs examples/api-info/Main.hs+stylish-haskell -i examples/count/Main.hs+cabal test+```++## Files++- `shodan.cabal`: package and library settings.+- `cabal.project`: local Cabal project settings.+- `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.+- `test/Main.hs`: response parsing and HTTP tests against a local mock server.++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.
+ examples/api-info/Main.hs view
@@ -0,0 +1,30 @@+module Main (main) where++import Data.Char (isSpace)+import qualified Data.Text as Text+import Shodan (ApiInfo (..), ShodanError (..), getApiInfo,+ newClient)+import System.Environment (lookupEnv)+import System.Exit (die)++main :: IO ()+main = do+ configuredKey <- lookupEnv "SHODAN_API_KEY"+ case configuredKey of+ Nothing -> die "Set the SHODAN_API_KEY environment variable before running."+ Just key+ | all isSpace key -> die "SHODAN_API_KEY must not be empty or whitespace."+ | otherwise -> do+ client <- newClient (Text.pack key)+ result <- getApiInfo client+ case result of+ Left err -> die (errorMessage err)+ Right info -> do+ putStrLn ("Plan: " ++ Text.unpack (apiInfoPlan info))+ putStrLn ("Query credits: " ++ show (apiInfoQueryCredits info))+ putStrLn ("Scan credits: " ++ show (apiInfoScanCredits info))++errorMessage :: ShodanError -> String+errorMessage NetworkError = "Could not reach Shodan (connection failure or timeout)."+errorMessage (HttpError status) = "Shodan returned HTTP " ++ show status ++ "."+errorMessage InvalidResponse = "Shodan returned an unexpected response."
+ examples/count/Main.hs view
@@ -0,0 +1,25 @@+module Main (main) where++import Data.Char (isSpace)+import qualified Data.Text as Text+import Shodan (CountResult (..), countHosts, newClient)+import System.Environment (getArgs, lookupEnv)+import System.Exit (die)++main :: IO ()+main = do+ arguments <- getArgs+ query <- case arguments of+ [value] | not (all isSpace value) -> pure (Text.pack value)+ _ -> die "Usage: shodan-count 'QUERY'"+ configuredKey <- lookupEnv "SHODAN_API_KEY"+ case configuredKey of+ Nothing -> die "Set the SHODAN_API_KEY environment variable before running."+ Just key+ | all isSpace key -> die "SHODAN_API_KEY must not be empty or whitespace."+ | otherwise -> do+ client <- newClient (Text.pack key)+ result <- countHosts client query+ case result of+ Left err -> die ("Shodan count failed: " ++ show err)+ Right count -> print (countTotal count)
+ shodan.cabal view
@@ -0,0 +1,74 @@+cabal-version: 2.4+name: shodan+version: 0.1.0.0+license: BSD-3-Clause+license-file: LICENSE+synopsis: A simple Haskell client for the Shodan API+description:+ A small Shodan API client using ordinary records and explicit IO functions.+ Supports API plan information and search result counts, with JSON response+ types for facet statistics. Includes executable examples and local HTTP tests.+category: Network+author: Joonkyu Park+maintainer: vpark45@gmail.com+homepage: https://github.com/nattybear/shodan+bug-reports: https://github.com/nattybear/shodan/issues+tested-with: GHC == 9.8.4+build-type: Simple+extra-source-files: README.md, .stylish-haskell.yaml++source-repository head+ type: git+ location: https://github.com/nattybear/shodan.git++library+ exposed-modules: Shodan+ hs-source-dirs: src+ build-depends:+ base >= 4.19 && < 5,+ aeson >= 2.1 && < 2.3,+ containers >= 0.6 && < 0.8,+ http-client >= 0.7 && < 0.8,+ http-client-tls >= 0.3 && < 0.4,+ http-types >= 0.12 && < 0.13,+ text >= 2.1 && < 2.2+ default-language: Haskell2010+ ghc-options: -Wall++executable shodan-api-info+ main-is: Main.hs+ hs-source-dirs: examples/api-info+ build-depends:+ base >= 4.19 && < 5,+ shodan,+ text >= 2.1 && < 2.2+ default-language: Haskell2010+ ghc-options: -Wall -threaded++executable shodan-count+ main-is: Main.hs+ hs-source-dirs: examples/count+ build-depends:+ base >= 4.19 && < 5,+ shodan,+ text >= 2.1 && < 2.2+ default-language: Haskell2010+ ghc-options: -Wall -threaded++test-suite shodan-test+ type: exitcode-stdio-1.0+ main-is: Main.hs+ hs-source-dirs: test+ build-depends:+ base >= 4.19 && < 5,+ aeson >= 2.1 && < 2.3,+ bytestring >= 0.12 && < 0.13,+ containers >= 0.6 && < 0.8,+ http-client >= 0.7 && < 0.8,+ http-types >= 0.12 && < 0.13,+ shodan,+ text >= 2.1 && < 2.2,+ wai >= 3.2 && < 3.3,+ warp >= 3.3 && < 3.5+ default-language: Haskell2010+ ghc-options: -Wall -threaded
+ src/Shodan.hs view
@@ -0,0 +1,176 @@+{-# 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"
+ test/Main.hs view
@@ -0,0 +1,251 @@+{-# LANGUAGE OverloadedStrings #-}++module Main (main) where++import Control.Exception (AsyncException (..), throwIO, try)+import Control.Monad (unless)+import Data.Aeson (Result (..), Value (..),+ eitherDecode', encode, fromJSON,+ object, (.=))+import qualified Data.Aeson.KeyMap as KeyMap+import qualified Data.ByteString.Lazy as Lazy+import qualified Data.Map.Strict as Map+import qualified Data.Text as Text+import qualified Data.Text.Encoding as TextEncoding+import qualified Network.HTTP.Client as HTTP+import qualified Network.HTTP.Types as HTTPTypes+import qualified Network.Wai as Wai+import Network.Wai.Handler.Warp (testWithApplication)+import Shodan++main :: IO ()+main = do+ let expected = ApiInfo 100000 (UsageLimits (-1) (-1) (-1))+ "stream-100" False True 100000 19 100000 False+ case fromJSON example of+ Success actual -> check "official example" (actual == expected)+ Error message -> fail message+ case fromJSON (change (KeyMap.insert "future_field" Null)) of+ Success actual -> check "unknown fields" (actual == expected)+ Error message -> fail message+ rejects "missing plan" (change (KeyMap.delete "plan"))+ rejects "null credits" (change (KeyMap.insert "query_credits" Null))+ rejects "wrong boolean type" (change (KeyMap.insert "https" (String "false")))+ rejects "fractional credits" (change (KeyMap.insert "scan_credits" (Number 1.5)))+ rejects "invalid nested limits" (change (KeyMap.insert "usage_limits" (object [])))+ rejects "non-object response" (Array mempty)+ facetTests+ countParsingTests+ httpTests+ countTests+ putStrLn "All response parsing and HTTP tests passed."++facetTests :: IO ()+facetTests = do+ -- The organization bucket is from the official count endpoint example.+ let cases =+ [ ("official facet", "{\"value\":\"Amazon.com\",\"count\":3012386}",+ Facet (String "Amazon.com") 3012386)+ , ("numeric value", "{\"value\":443,\"count\":12}", Facet (Number 443) 12)+ , ("explicit null value", "{\"value\":null,\"count\":2}", Facet Null 2)+ , ("zero count", "{\"value\":\"KR\",\"count\":0}", Facet (String "KR") 0)+ , ("large count", "{\"value\":\"KR\",\"count\":100000000000000000000}",+ Facet (String "KR") 100000000000000000000)+ , ("unknown field", "{\"value\":\"KR\",\"count\":1,\"future\":true}",+ Facet (String "KR") 1)+ , ("null value preserved", "{\"value\":null,\"count\":1}", Facet Null 1)+ ]+ mapM_ (\(label, body, expected) ->+ check label (eitherDecode' body == Right expected)) cases+ let invalidCases =+ [ ("missing value", "{\"count\":1}")+ , ("missing count", "{\"value\":\"KR\"}")+ , ("null count", "{\"value\":\"KR\",\"count\":null}")+ , ("string count", "{\"value\":\"KR\",\"count\":\"1\"}")+ , ("fractional count", "{\"value\":\"KR\",\"count\":1.5}")+ , ("negative count", "{\"value\":\"KR\",\"count\":-1}")+ , ("non-object facet", "[]")+ , ("malformed facet JSON", "not JSON")+ , ("negative count", "{\"value\":\"KR\",\"count\":-1}")+ , ("non-object facet", "[]")+ , ("malformed facet", "not JSON")+ ]+ mapM_ (\(label, body) -> case eitherDecode' body :: Either String Facet of+ Left _ -> pure ()+ Right _ -> fail (label ++ ": unexpectedly accepted")) invalidCases+ let buckets = "[{\"value\":\"US\",\"count\":2},{\"value\":\"KR\",\"count\":1}]"+ check "facet list" (eitherDecode' buckets ==+ Right [Facet (String "US") 2, Facet (String "KR") 1])++httpTests :: IO ()+httpTests = do+ let key = "test key+&?=한글"+ application request respond = do+ check "GET method" (Wai.requestMethod request == "GET")+ check "request path" (Wai.pathInfo request == ["api-info"])+ check "encoded key" (Wai.queryString request ==+ [("key", Just (TextEncoding.encodeUtf8 key))])+ check "accept header" (lookup "Accept" (Wai.requestHeaders request) ==+ Just "application/json")+ respond (Wai.responseLBS HTTPTypes.status200 [] (encode example))+ withMockClient key application $ \client -> do+ check "client key redacted" (not (key `Text.isInfixOf` Text.pack (show client)))+ result <- getApiInfo client+ check "HTTP success" (result == (case fromJSON example of+ Success info -> Right info+ Error _ -> Left InvalidResponse))+ checkResponse "unauthorized" HTTPTypes.status401 "{\"error\":\"test-key\"}"+ (Left (HttpError 401))+ checkResponse "rate limited" HTTPTypes.status429 "not JSON"+ (Left (HttpError 429))+ checkResponse "server error" HTTPTypes.status500 "<html>unavailable</html>"+ (Left (HttpError 500))+ checkResponse "malformed JSON" HTTPTypes.status200 "not JSON"+ (Left InvalidResponse)+ checkResponse "wrong response shape" HTTPTypes.status200 "{}"+ (Left InvalidResponse)+ checkResponse "unexpected success status" HTTPTypes.status204 ""+ (Left (HttpError 204))+ let redirect _ respond = respond (Wai.responseLBS HTTPTypes.status302+ [("Location", "https://example.invalid/never-follow")] "")+ withMockClient "test-key" redirect $ \client -> do+ result <- getApiInfo client+ check "redirect not followed" (result == Left (HttpError 302))+ -- Inject an http-client transport exception without relying on external DNS.+ manager <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \request -> throwIO+ (HTTP.HttpExceptionRequest request HTTP.ConnectionTimeout)+ }+ result <- getApiInfo (newClientWithManager manager "test-key")+ check "network failure" (result == Left NetworkError)+ cancellingManager <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \_ -> throwIO ThreadKilled }+ cancelled <- try (getApiInfo (newClientWithManager cancellingManager "test-key"))+ :: IO (Either AsyncException (Either ShodanError ApiInfo))+ check "thread cancellation propagates" (cancelled == Left ThreadKilled)++countParsingTests :: IO ()+countParsingTests = do+ let country = [Facet (String "KR") 60, Facet (String "US") 40]+ expected = CountResult 100 (Map.fromList+ [("country", country), ("port", [Facet (Number 443) 80])])+ response = "{\"total\":100,\"facets\":{\"country\":[{\"value\":\"KR\",\"count\":60},{\"value\":\"US\",\"count\":40}],\"port\":[{\"value\":443,\"count\":80}]},\"matches\":[]}"+ check "count grouped facets" (eitherDecode' response == Right expected)+ check "count absent facets" (eitherDecode' "{\"total\":100}" ==+ Right (CountResult 100 Map.empty))+ check "count empty facets" (eitherDecode' "{\"total\":0,\"facets\":{}}" ==+ Right (CountResult 0 Map.empty))+ check "count empty bucket list" (eitherDecode'+ "{\"total\":0,\"facets\":{\"country\":[]}}" ==+ Right (CountResult 0 (Map.singleton "country" [])))+ mapM_ (\(label, body) -> case eitherDecode' body :: Either String CountResult of+ Left _ -> pure ()+ Right _ -> fail label)+ [ ("null facets", "{\"total\":1,\"facets\":null}")+ , ("array facets", "{\"total\":1,\"facets\":[]}")+ , ("non-list buckets", "{\"total\":1,\"facets\":{\"country\":{}}}")+ , ("null buckets", "{\"total\":1,\"facets\":{\"country\":null}}")+ , ("missing bucket count", "{\"total\":1,\"facets\":{\"country\":[{\"value\":\"KR\"}]}}")+ , ("negative bucket count", "{\"total\":1,\"facets\":{\"port\":[{\"value\":443,\"count\":-1}]}}")+ ]++countTests :: IO ()+countTests = do+ let key = "count-test-key"+ query = "http.title:\"한글 + & ?\" country:KR"+ application request respond = do+ check "count GET" (Wai.requestMethod request == "GET")+ check "count path" (Wai.pathInfo request == ["shodan", "host", "count"])+ check "count query encoding" (Wai.queryString request ==+ [("key", Just (TextEncoding.encodeUtf8 key)),+ ("query", Just (TextEncoding.encodeUtf8 query))])+ respond (Wai.responseLBS HTTPTypes.status200 []+ "{\"total\":19592093,\"matches\":[]}")+ withMockClient key application $ \client -> do+ actual <- countHosts client query+ check "count success" (actual == Right (CountResult 19592093 Map.empty))+ countResponse "zero count" HTTPTypes.status200 "{\"total\":0}"+ (Right (CountResult 0 Map.empty))+ countResponse "large count and unknown fields" HTTPTypes.status200+ "{\"total\":100000000000000000000,\"facets\":{},\"future\":true}"+ (Right (CountResult 100000000000000000000 Map.empty))+ mapM_ (\body -> countResponse "invalid count" HTTPTypes.status200 body+ (Left InvalidResponse))+ [ "{}", "{\"total\":null}", "{\"total\":\"12\"}"+ , "{\"total\":1.5}", "{\"total\":-1}", "[]", "invalid JSON"+ ]+ countResponse "count unauthorized" HTTPTypes.status401 "{\"error\":\"Invalid key\"}"+ (Left (HttpError 401))+ countResponse "count rate limited" HTTPTypes.status429 "not JSON"+ (Left (HttpError 429))++countResponse :: String -> HTTPTypes.Status -> Lazy.ByteString+ -> Either ShodanError CountResult -> IO ()+countResponse label status body expected = do+ let application _ respond = respond (Wai.responseLBS status [] body)+ withMockClient "count-test-key" application $ \client -> do+ actual <- countHosts client "port:443"+ check label (actual == expected)++checkResponse :: String -> HTTPTypes.Status -> Lazy.ByteString+ -> Either ShodanError ApiInfo -> IO ()+checkResponse label status body expected = do+ let application _ respond = respond (Wai.responseLBS status [] body)+ withMockClient "test-key" application $ \client -> do+ actual <- getApiInfo client+ check label (actual == expected)++-- Redirect only the test transport to a local server; production always uses+-- the fixed HTTPS endpoint. Validate the original destination before rewriting.+withMockClient :: Text.Text -> Wai.Application -> (Client -> IO ()) -> IO ()+withMockClient key application run = testWithApplication (pure application) $ \port -> do+ manager <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \request -> do+ check "finite timeout" (HTTP.responseTimeout request ==+ HTTP.responseTimeoutMicro 30000000)+ -- http-client can apply the hook more than once to the same request.+ if not (HTTP.secure request) && HTTP.host request == "127.0.0.1"+ && HTTP.port request == port+ then pure request+ else do+ check "HTTPS endpoint" (HTTP.secure request &&+ HTTP.host request == "api.shodan.io" && HTTP.port request == 443)+ pure request+ { HTTP.secure = False+ , HTTP.host = "127.0.0.1"+ , HTTP.port = port+ , HTTP.proxy = Nothing+ }+ }+ run (newClientWithManager manager key)++check :: String -> Bool -> IO ()+check label passed = unless passed (fail label)++rejects :: String -> Value -> IO ()+rejects label value = case fromJSON value :: Result ApiInfo of+ Error _ -> pure ()+ Success _ -> fail (label ++ ": unexpectedly accepted")++change :: (KeyMap.KeyMap Value -> KeyMap.KeyMap Value) -> Value+change f = case example of+ Object o -> Object (f o)+ _ -> example++-- Source: https://developer.shodan.io/api, GET /api-info response example.+example :: Value+example = object+ [ "scan_credits" .= (100000 :: Integer)+ , "usage_limits" .= object+ [ "scan_credits" .= (-1 :: Integer)+ , "query_credits" .= (-1 :: Integer)+ , "monitored_ips" .= (-1 :: Integer)+ ]+ , "plan" .= String "stream-100"+ , "https" .= False+ , "unlocked" .= True+ , "query_credits" .= (100000 :: Integer)+ , "monitored_ips" .= (19 :: Integer)+ , "unlocked_left" .= (100000 :: Integer)+ , "telnet" .= False+ ]