VirusShare API v2¶
Support for version 2 of the VirusShare API.
This API is fully documented here: https://virusshare.com/apiv2_reference
An exception is raised in the case the status code is not 200 (Success) or 204 (Rate limited).
Please add try/except clauses around calls to this library to properly handle errors in requesting data. This was not implemented within the library to allow greater flexibility in how you would like to handle errors.
-
class
libvxshare.apiv2.VirusShare(api_key=None, requests_per_minute=4)¶ Class containing methods to support querying the VirusShare API including rate limiting operations.
-
file_download(hash_value)¶ Download a sample by hash value.
It is highly recommended to use self.file_exists to confirm the file is found within the dataset before requesting a report.
This leverages the /download endpoint, which returns a byte stream containing a password protected zip file archive.
- Parameters
hash_value – A string hash value. May be one of md5, sha1, sha224, sha256, sha384, or sha512.
- Returns
Byte content of the zip file containing the sample.
-
file_exists(hash_value)¶ Quickly confirm whether the file exists in the data set or not.
This leverages the /quick endpoint, and will return a 0 if the file is not found, a 1 if the file is found and has a detection, and 2 if the file is found and benign.
- Parameters
hash_value – A string hash value. May be one of md5, sha1, sha224, sha256, sha384, or sha512.
- Returns
Dictionary containing response from VirusShare, plus metadata fields about whether the file exists or was detected.
-
file_report(hash_value)¶ Gather a report about a file in the dataset.
It is highly recommended to use self.file_exists to confirm the file is found within the dataset before requesting a report.
This leverages the /file endpoint, which returns a JSON document with key-value mappings of the metadata associated with this entry. An example response is shown in the main documentation here: https://virusshare.com/apiv2_reference.
- Parameters
hash_value – A string hash value. May be one of md5, sha1, sha224, sha256, sha384, or sha512.
- Returns
Dictionary containing response from VirusShare, plus metadata fields about the request
-
file_source(hash_value, convert_timestamps=False)¶ Gather information about where the sample was sourced from.
It is highly recommended to use self.file_exists to confirm the file is found within the dataset before requesting a report.
This leverages the /source endpoint, which returns a JSON document with key-value mappings of the metadata associated with this entry. The main data point of interest is located in the urllist field. An example response is shown in the main documentation here: https://virusshare.com/apiv2_reference.
- Parameters
hash_value – A string hash value. Must by SHA256
convert_timestamps – Whether or not to convert timestamps to datetime objects. Will add datetime field.
- Returns
Dictionary containing response from VirusShare, plus metadata fields about the request
-