diff --git a/.stylish-haskell.yaml b/.stylish-haskell.yaml
new file mode 100644
--- /dev/null
+++ b/.stylish-haskell.yaml
@@ -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
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
--- /dev/null
+++ b/CHANGELOG.md
@@ -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.
diff --git a/LICENSE b/LICENSE
new file mode 100644
--- /dev/null
+++ b/LICENSE
@@ -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.
diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -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
diff --git a/src/VirusTotal.hs b/src/VirusTotal.hs
new file mode 100644
--- /dev/null
+++ b/src/VirusTotal.hs
@@ -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)
diff --git a/test/HttpTests.hs b/test/HttpTests.hs
new file mode 100644
--- /dev/null
+++ b/test/HttpTests.hs
@@ -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)
diff --git a/test/Main.hs b/test/Main.hs
new file mode 100644
--- /dev/null
+++ b/test/Main.hs
@@ -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")
diff --git a/virustotal.cabal b/virustotal.cabal
new file mode 100644
--- /dev/null
+++ b/virustotal.cabal
@@ -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
