virustotal: A simple Haskell client for the VirusTotal API

[ bsd3, library, network ] [ Propose Tags ] [ Report a vulnerability ]

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.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0
Change log CHANGELOG.md
Dependencies aeson (>=2.1 && <2.3), base (>=4.19 && <5), http-client (>=0.7 && <0.8), http-client-tls (>=0.3 && <0.4), http-types (>=0.12 && <0.13), iproute (>=1.7 && <1.8), text (>=2.1 && <2.2) [details]
Tested with ghc ==9.8.4
License BSD-3-Clause
Author Joonkyu Park
Maintainer vpark45@gmail.com
Uploaded by JoonkyuPark at 2026-11-22T15:32:51Z
Category Network
Home page https://github.com/nattybear/virustotal
Bug tracker https://github.com/nattybear/virustotal/issues
Source repo head: git clone https://github.com/nattybear/virustotal.git
Distributions
Downloads 0 total (0 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for virustotal-0.1.0.0

[back to package description]

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.

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

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

{-# 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