virustotal-0.1.0.0: src/VirusTotal.hs
{-# 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)