packages feed

virustotal-0.1.0.0: README.md

# 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