packages feed

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 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+  ]