virustotal (empty) → 0.1.0.0
raw patch · 8 files changed
+1017/−0 lines, 8 filesdep +aesondep +basedep +bytestring
Dependencies added: aeson, base, bytestring, http-client, http-client-tls, http-types, iproute, text, virustotal, wai, warp
Files
- .stylish-haskell.yaml +481/−0
- CHANGELOG.md +9/−0
- LICENSE +29/−0
- README.md +101/−0
- src/VirusTotal.hs +166/−0
- test/HttpTests.hs +83/−0
- test/Main.hs +94/−0
- virustotal.cabal +54/−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
+ CHANGELOG.md view
@@ -0,0 +1,9 @@+# Changelog++## 0.1.0.0 (unreleased)++- Add the initial Cabal library skeleton.+- Add IP report, analysis statistics, and community vote types with JSON parsing.+- Add response parsing tests, including unavailable attributes and invalid responses.+- Add reusable HTTPS clients and IP report requests with local input validation.+- Add redacted error handling, redirect protection, timeout, and local HTTP tests.
+ 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,101 @@+# virustotal++A small Haskell client for the VirusTotal API v3.++## Status++IP reputation HTTP requests, response types, and JSON parsing are implemented.++## Design++- Simple/Boring Haskell: ordinary records and explicit IO functions.+- Add dependencies and abstractions only when needed.+- Keep API keys out of source code and diagnostic output.+- Build one endpoint at a time.++## Build++Requires GHC 9.8.4 and Cabal.++```sh+cabal build+```++## IP reports++`IpReport` decodes the complete JSON response for `GET /api/v3/ip_addresses/{ip}`, which retrieves an+IPv4 or IPv6 address report.++The report includes:++- Community reputation score (`reputation`) and votes (`total_votes`).+- Scanner verdict counts (`last_analysis_stats`).+- Last analysis time (`last_analysis_date`).+- Country, ASN, and AS owner when available.++Community reputation and scanner verdicts are separate signals. An undetected+verdict does not establish that an IP address is harmless.++Use `Data.Aeson.eitherDecode` to decode JSON as `Either String IpReport`.+Missing or null report attributes become `Nothing`; zero values remain `Just 0`.+If statistics or votes are present, their documented count fields are required+and must be nonnegative integers. Unknown JSON fields are ignored.+The response must contain `data.id`, `data.type` equal to `ip_address`, and an+attributes object. IP IDs are retained as text without IP syntax validation.+Analysis timestamps are represented as integer Unix seconds in UTC.++## Tests++```sh+cabal test+```++Tests use synthetic responses and a local HTTP server. They do not need a real+API key or access to VirusTotal.++## Query an IP report++```haskell+{-# LANGUAGE OverloadedStrings #-}+import qualified Data.Text as Text+import System.Environment (getEnv)+import VirusTotal++main :: IO ()+main = do+ key <- Text.pack <$> getEnv "VIRUSTOTAL_API_KEY"+ client <- newClient key+ result <- getIpReport client "192.0.2.1"+ case result of+ Left err -> print err+ Right report -> print report+```++The example uses a documentation address; choose an IP you intend to query.+Reuse the client across calls. `getIpReport` validates IPv4/IPv6 syntax locally.+Keys must be nonempty visible ASCII without whitespace.++Failures are `InvalidIpAddress`, `InvalidApiKey`, `HttpError status`,+`InvalidResponse`, or `NetworkError`. HTTP errors include 401 (authentication),+403 (permission), 404 (not found), and 429 (quota or rate limit). Error values+omit response bodies and exception details to avoid exposing secrets.+A successful report must have an ID matching the queried IP address.++Requests use a 30-second response timeout, do not follow redirects, and do not+retry HTTP status errors. The caller decides when to retry. Async cancellation+propagates normally. For custom manager configuration, use+`newClientWithManager`; trusted request hooks can see the key and must not log it.++VirusTotal's endpoint documentation states that queried indicators may be+scanned and added to its community-accessible dataset. See the IP report+reference below before querying confidential indicators.++VirusTotal API v3 authenticates requests using the `x-apikey` header over HTTPS.++## References++- https://docs.virustotal.com/reference/overview+- https://docs.virustotal.com/reference/authentication+- https://docs.virustotal.com/reference/ip-info+- https://docs.virustotal.com/reference/ip-object+- https://docs.virustotal.com/reference/errors
+ src/VirusTotal.hs view
@@ -0,0 +1,166 @@+{-# LANGUAGE OverloadedStrings #-}++-- | A small client for the VirusTotal API v3.+module VirusTotal+ ( Client+ , newClient+ , newClientWithManager+ , VirusTotalError (..)+ , getIpReport+ , IpReport (..)+ , AnalysisStats (..)+ , CommunityVotes (..)+ ) where++import Control.Exception (catch)+import Data.Aeson (FromJSON (..), eitherDecode',+ withObject, (.:), (.:?))+import Data.Aeson.Types (Parser)+import Data.IP (IP)+import Data.Text (Text)+import qualified Data.Text as 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, urlEncode)+import Numeric.Natural (Natural)+import Text.Read (readMaybe)++-- | An IP address report, decoded from the complete API response envelope.+-- Unknown fields are ignored. Missing or null attributes become 'Nothing',+-- preserving the distinction between unavailable information and a zero value.+-- The ID is retained as text; this parser does not validate IP syntax.+data IpReport = IpReport+ { ipAddress :: Text+ -- ^ Report ID (IPv4 or IPv6 address).+ , ipReputation :: Maybe Integer+ -- ^ Community score: negative indicates malicious votes, positive harmless.+ -- This is separate from scanner verdict counts.+ , ipTotalVotes :: Maybe CommunityVotes+ -- ^ Unweighted community votes.+ , ipLastAnalysisStats :: Maybe AnalysisStats+ -- ^ Scanner verdict counts. Undetected means no opinion, not harmless.+ , ipLastAnalysisDate :: Maybe Integer+ -- ^ Last analysis time as Unix seconds in UTC.+ , ipCountry :: Maybe Text+ -- ^ Country code.+ , ipAsn :: Maybe Natural+ -- ^ Autonomous system number.+ , ipAsOwner :: Maybe Text+ -- ^ Autonomous system owner.+ } deriving (Eq, Show)++-- | Nonnegative scanner verdict counts. All five documented fields are+-- required when the statistics object is present; unknown fields are ignored.+data AnalysisStats = AnalysisStats+ { analysisHarmless :: Natural+ , analysisMalicious :: Natural+ , analysisSuspicious :: Natural+ , analysisTimeout :: Natural+ , analysisUndetected :: Natural+ } deriving (Eq, Show)++-- | Nonnegative, unweighted community vote counts. Both fields are required+-- when the votes object is present.+data CommunityVotes = CommunityVotes+ { votesHarmless :: Natural+ , votesMalicious :: Natural+ } deriving (Eq, Show)++instance FromJSON IpReport where+ parseJSON = withObject "IP report response" $ \response -> do+ resource <- response .: "data"+ withObject "IP address resource" (\obj -> do+ resourceType <- obj .: "type" :: Parser Text+ if resourceType /= "ip_address"+ then fail "Expected ip_address resource"+ else do+ address <- obj .: "id"+ attributes <- obj .: "attributes"+ withObject "IP address attributes" (\attrs ->+ IpReport address+ <$> attrs .:? "reputation"+ <*> attrs .:? "total_votes"+ <*> attrs .:? "last_analysis_stats"+ <*> attrs .:? "last_analysis_date"+ <*> attrs .:? "country"+ <*> attrs .:? "asn"+ <*> attrs .:? "as_owner") attributes) resource++instance FromJSON AnalysisStats where+ parseJSON = withObject "Analysis statistics" $ \obj ->+ AnalysisStats+ <$> obj .: "harmless"+ <*> obj .: "malicious"+ <*> obj .: "suspicious"+ <*> obj .: "timeout"+ <*> obj .: "undetected"++instance FromJSON CommunityVotes where+ parseJSON = withObject "Community votes" $ \obj ->+ CommunityVotes <$> obj .: "harmless" <*> obj .: "malicious"+++-- | An opaque client. Its 'Show' instance hides the API key.+data Client = Client HTTP.Manager Text++instance Show Client where+ show _ = "Client <redacted>"++-- | Create a client with a reusable TLS connection manager.+newClient :: Text -> IO Client+newClient key = do+ manager <- HTTP.newManager tlsManagerSettings+ pure (newClientWithManager manager key)++-- | Use a caller-managed connection manager. Its request hooks can inspect the+-- authentication header; use only trusted hooks and avoid logging secrets.+newClientWithManager :: HTTP.Manager -> Text -> Client+newClientWithManager = Client++-- | Failures omit response bodies and transport exception details so they+-- cannot expose the API key. HTTP errors retain their status code.+data VirusTotalError+ = InvalidIpAddress -- ^ Input is not an IPv4 or IPv6 address.+ | InvalidApiKey -- ^ API key is empty or contains non-visible ASCII characters.+ | HttpError Int -- ^ Non-200 response, including 401, 403, 404, and 429.+ | InvalidResponse -- ^ Malformed JSON, wrong response shape, or mismatched ID.+ | NetworkError -- ^ HTTP transport failure (including timeout).+ deriving (Eq, Show)++-- | Retrieve an IP reputation report using @GET /api/v3/ip_addresses/{ip}@.+-- Validates IP syntax before sending a request. Uses HTTPS and @x-apikey@,+-- a 30-second response timeout, and no redirects or automatic status retries.+-- Network failures are returned; asynchronous cancellation still propagates.+getIpReport :: Client -> Text -> IO (Either VirusTotalError IpReport)+getIpReport (Client manager key) address =+ case readMaybe (Text.unpack address) :: Maybe IP of+ Nothing -> pure (Left InvalidIpAddress)+ Just parsed+ | Text.null key || not (Text.all (\c -> c >= '!' && c <= '~') key) ->+ pure (Left InvalidApiKey)+ | otherwise -> action parsed `catch` handleHttpException+ where+ request = HTTP.defaultRequest+ { HTTP.secure = True+ , HTTP.host = "www.virustotal.com"+ , HTTP.port = 443+ , HTTP.path = "/api/v3/ip_addresses/" <> urlEncode True (Text.encodeUtf8 address)+ , HTTP.requestHeaders =+ [("Accept", "application/json"), ("x-apikey", Text.encodeUtf8 key)]+ , HTTP.redirectCount = 0+ , HTTP.responseTimeout = HTTP.responseTimeoutMicro 30000000+ , HTTP.checkResponse = \_ _ -> pure ()+ }+ action parsed = 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+ Right info | (readMaybe (Text.unpack (ipAddress info)) :: Maybe IP)+ == Just parsed -> Right info+ _ -> Left InvalidResponse++handleHttpException :: HTTP.HttpException -> IO (Either VirusTotalError a)+handleHttpException _ = pure (Left NetworkError)
+ test/HttpTests.hs view
@@ -0,0 +1,83 @@+{-# LANGUAGE OverloadedStrings #-}+module HttpTests (httpTests) where++import Control.Exception (AsyncException (..), throwIO, try)+import Control.Monad (unless)+import Data.Aeson (encode, object, (.=))+import qualified Data.ByteString.Lazy as Lazy+import qualified Network.HTTP.Client as HTTP+import qualified Network.HTTP.Types as Status+import qualified Network.Wai as Wai+import Network.Wai.Handler.Warp (testWithApplication)+import VirusTotal++httpTests :: IO ()+httpTests = do+ let application request respond = do+ check "GET" (Wai.requestMethod request == "GET")+ check "path" (Wai.pathInfo request == ["api", "v3", "ip_addresses", "2001:db8::1"])+ check "no query" (null (Wai.queryString request))+ check "API key header" (lookup "x-apikey" (Wai.requestHeaders request) == Just "test-secret")+ check "accept header" (lookup "Accept" (Wai.requestHeaders request) == Just "application/json")+ respond (Wai.responseLBS Status.status200 [] (body "2001:db8:0:0:0:0:0:1"))+ withMock application $ \client -> do+ check "client redacted" (show client == "Client <redacted>")+ result <- getIpReport client "2001:db8::1"+ check "IPv6 equivalent ID" (result == Right+ (IpReport "2001:db8:0:0:0:0:0:1" Nothing Nothing Nothing Nothing Nothing Nothing Nothing))+ withMock (\_ respond -> respond (Wai.responseLBS Status.status200 [] (body "192.0.2.1"))) $ \client -> do+ result <- getIpReport client "192.0.2.1"+ check "IPv4 success" (result == Right+ (IpReport "192.0.2.1" Nothing Nothing Nothing Nothing Nothing Nothing Nothing))+ mapM_ (\status -> responseTest status "test-secret" (Left (HttpError (Status.statusCode status))))+ [Status.status400, Status.status401, Status.status403, Status.status404,+ Status.status429, Status.status500, Status.status204]+ responseTest Status.status200 "not JSON" (Left InvalidResponse)+ responseTest Status.status200 "{}" (Left InvalidResponse)+ responseTest Status.status200 (body "192.0.2.2") (Left InvalidResponse)+ withMock (\_ respond -> respond (Wai.responseLBS Status.status302+ [("Location", "https://example.invalid/secret")] "")) $ \client -> do+ result <- getIpReport client "192.0.2.1"+ check "redirect refused" (result == Left (HttpError 302))+ manager <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \request -> do+ check "production host" (HTTP.host request == "www.virustotal.com")+ check "HTTPS" (HTTP.secure request && HTTP.port request == 443)+ throwIO (HTTP.HttpExceptionRequest request HTTP.ConnectionTimeout) }+ result <- getIpReport (newClientWithManager manager "test-secret") "192.0.2.1"+ check "network error redacted" (result == Left NetworkError)+ rejecting <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \_ -> fail "Unexpected HTTP request" }+ mapM_ (\address -> do+ invalid <- getIpReport (newClientWithManager rejecting "test-secret") address+ check "invalid IP rejected locally" (invalid == Left InvalidIpAddress))+ ["", "example.com", "192.0.2.999", "192.0.2.1/path", "::gg", "192.0.2.1?key=x"]+ mapM_ (\key -> do+ invalid <- getIpReport (newClientWithManager rejecting key) "192.0.2.1"+ check "invalid key rejected locally" (invalid == Left InvalidApiKey)) ["", "bad\r\nkey", "한글"]+ cancelling <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \_ -> throwIO ThreadKilled }+ cancelled <- try (getIpReport (newClientWithManager cancelling "test-secret") "192.0.2.1")+ :: IO (Either AsyncException (Either VirusTotalError IpReport))+ check "cancellation propagates" (cancelled == Left ThreadKilled)+ putStrLn "All HTTP tests passed."++body :: String -> Lazy.ByteString+body address = encode (object ["data" .= object+ ["type" .= ("ip_address" :: String), "id" .= address, "attributes" .= object []]])++withMock :: Wai.Application -> (Client -> IO a) -> IO a+withMock application action = testWithApplication (pure application) $ \port -> do+ manager <- HTTP.newManager HTTP.defaultManagerSettings+ { HTTP.managerModifyRequest = \request -> pure request+ { HTTP.secure = False, HTTP.host = "127.0.0.1", HTTP.port = port } }+ action (newClientWithManager manager "test-secret")++responseTest :: Status.Status -> Lazy.ByteString -> Either VirusTotalError IpReport -> IO ()+responseTest status payload expected =+ withMock (\_ respond -> respond (Wai.responseLBS status [] payload)) $ \client -> do+ actual <- getIpReport client "192.0.2.1"+ check "response handling" (actual == expected)++check :: String -> Bool -> IO ()+check label passed = unless passed (fail label)
+ test/Main.hs view
@@ -0,0 +1,94 @@+{-# LANGUAGE OverloadedStrings #-}+module Main (main) where++import Control.Monad (unless)+import Data.Aeson (Result (..), Value (..), eitherDecode',+ fromJSON, object, (.=))+import qualified Data.Aeson.KeyMap as KeyMap+import HttpTests (httpTests)+import VirusTotal++main :: IO ()+main = do+ -- Synthetic documentation-shaped response; no live API request or real target.+ accepts "complete IPv4 report" (report "192.0.2.1" attributes) expected+ accepts "IPv6 report" (report "2001:db8::1" attributes)+ expected { ipAddress = "2001:db8::1" }+ accepts "missing optional attributes" (report "192.0.2.1" (object [])) emptyReport+ accepts "null optional attributes" (report "192.0.2.1" (object+ ["reputation" .= Null, "total_votes" .= Null, "last_analysis_stats" .= Null,+ "last_analysis_date" .= Null, "country" .= Null, "asn" .= Null,+ "as_owner" .= Null])) emptyReport+ accepts "unknown attributes" (withAttr "future_field" (object [])) expected+ accepts "zero reputation is present" (withAttr "reputation" (Number 0))+ expected { ipReputation = Just 0 }+ rejects "wrong resource type" (object ["data" .= object+ ["type" .= String "domain", "id" .= String "192.0.2.1", "attributes" .= attributes]])+ rejects "missing envelope" attributes+ rejects "API error envelope" (object ["error" .= object ["code" .= String "NotFoundError"]])+ rejects "missing ID" (object ["data" .= object+ ["type" .= String "ip_address", "attributes" .= attributes]])+ rejects "missing type" (object ["data" .= object+ ["id" .= String "192.0.2.1", "attributes" .= attributes]])+ rejects "missing attributes" (object ["data" .= object+ ["id" .= String "192.0.2.1", "type" .= String "ip_address"]])+ rejects "null attributes" (report "192.0.2.1" Null)+ rejects "wrong reputation type" (withAttr "reputation" (String "-10"))+ rejects "fractional reputation" (withAttr "reputation" (Number 0.5))+ rejects "wrong country type" (withAttr "country" (Number 1))+ rejects "negative ASN" (withAttr "asn" (Number (-1)))+ rejects "fractional timestamp" (withAttr "last_analysis_date" (Number 1.5))+ rejects "incomplete statistics" (withAttr "last_analysis_stats" (object []))+ rejects "negative verdict count" (withAttr "last_analysis_stats"+ (stats (Number (-1))))+ rejects "fractional verdict count" (withAttr "last_analysis_stats"+ (stats (Number 0.5)))+ rejects "incomplete votes" (withAttr "total_votes" (object ["harmless" .= (0 :: Int)]))+ rejects "negative votes" (withAttr "total_votes" (object+ ["harmless" .= (0 :: Int), "malicious" .= (-1 :: Int)]))+ case eitherDecode' "{broken" :: Either String IpReport of+ Left _ -> pure ()+ Right _ -> fail "malformed JSON accepted"+ putStrLn "All 24 IP report parsing tests passed."+ httpTests++report :: Value -> Value -> Value+report address attrs = object ["data" .= object+ ["id" .= address, "type" .= String "ip_address", "attributes" .= attrs]]++attributes :: Value+attributes = object+ ["reputation" .= (-10 :: Int), "total_votes" .= object+ ["harmless" .= (1 :: Int), "malicious" .= (2 :: Int)],+ "last_analysis_stats" .= stats (Number 2),+ "last_analysis_date" .= (1700000000 :: Integer),+ "country" .= String "ZZ", "asn" .= (64512 :: Int),+ "as_owner" .= String "Example network"]++stats :: Value -> Value+stats malicious = object+ ["harmless" .= (3 :: Int), "malicious" .= malicious,+ "suspicious" .= (1 :: Int), "timeout" .= (0 :: Int), "undetected" .= (4 :: Int)]++withAttr :: KeyMap.Key -> Value -> Value+withAttr key value = case attributes of+ Object attrs -> report "192.0.2.1" (Object (KeyMap.insert key value attrs))+ _ -> error "Expected object fixture"++expected :: IpReport+expected = IpReport "192.0.2.1" (Just (-10)) (Just (CommunityVotes 1 2))+ (Just (AnalysisStats 3 2 1 0 4)) (Just 1700000000)+ (Just "ZZ") (Just 64512) (Just "Example network")++emptyReport :: IpReport+emptyReport = IpReport "192.0.2.1" Nothing Nothing Nothing Nothing Nothing Nothing Nothing++accepts :: String -> Value -> IpReport -> IO ()+accepts label value wanted = case fromJSON value of+ Success actual -> unless (actual == wanted) (fail (label ++ ": unexpected result"))+ Error message -> fail (label ++ ": " ++ message)++rejects :: String -> Value -> IO ()+rejects label value = case fromJSON value :: Result IpReport of+ Error _ -> pure ()+ Success _ -> fail (label ++ ": unexpectedly accepted")
+ virustotal.cabal view
@@ -0,0 +1,54 @@+cabal-version: 2.4+name: virustotal+version: 0.1.0.0+license: BSD-3-Clause+license-file: LICENSE+synopsis: A simple Haskell client for the VirusTotal API+description:+ A small VirusTotal API client using ordinary records and explicit IO functions.+ Includes IP reputation response types and JSON parsing.+ Supports IP report requests with explicit error handling.+category: Network+author: Joonkyu Park+maintainer: vpark45@gmail.com+homepage: https://github.com/nattybear/virustotal+bug-reports: https://github.com/nattybear/virustotal/issues+build-type: Simple+tested-with: GHC == 9.8.4+extra-source-files: README.md, CHANGELOG.md, .stylish-haskell.yaml++source-repository head+ type: git+ location: https://github.com/nattybear/virustotal.git++library+ exposed-modules: VirusTotal+ hs-source-dirs: src+ build-depends:+ base >= 4.19 && < 5,+ aeson >= 2.1 && < 2.3,+ text >= 2.1 && < 2.2,+ http-client >= 0.7 && < 0.8,+ http-client-tls >= 0.3 && < 0.4,+ http-types >= 0.12 && < 0.13,+ iproute >= 1.7 && < 1.8+ default-language: Haskell2010+ ghc-options: -Wall+++test-suite virustotal-test+ type: exitcode-stdio-1.0+ main-is: Main.hs+ other-modules: HttpTests+ hs-source-dirs: test+ build-depends:+ base >= 4.19 && < 5,+ aeson >= 2.1 && < 2.3,+ virustotal,+ bytestring >= 0.12 && < 0.13,+ http-client >= 0.7 && < 0.8,+ http-types >= 0.12 && < 0.13,+ wai >= 3.2 && < 3.3,+ warp >= 3.3 && < 3.5+ default-language: Haskell2010+ ghc-options: -Wall -threaded