A Python library to interact with the public VirusTotal v2 and v3 APIs.
Project description
virustotal-python 🐍
A Python library to interact with the public VirusTotal v2 and v3 APIs.
[!NOTE]
This library is intended to be used with the public VirusTotal APIs. However, it could be used to interact with premium API endpoints as well.
Dependencies and installation
[!NOTE]
This library should work with Python versions >= 3.7.
[dev-packages]
black = "*"
twine = "*"
pytest = "*"
[packages]
requests = {extras = ["socks"],version = "*"}
Install virustotal-python
using either:
pip3 install virustotal-python
,pipenv install
,pip3 install -r requirements.txt
,python setup.py install
.
Usage examples
[!NOTE]
See the examples directory for several usage examples.
Furthermore, check
virustotal_python/virustotal.py
for docstrings containing full parameter descriptions.
Authenticate using your VirusTotal API key:
![NOTE]
To obtain a VirusTotal API key, sign up for a VirusTotal account.
Then, view your VirusTotal API key.
from virustotal_python import Virustotal # v2 example vtotal = Virustotal(API_KEY="Insert API key here.") # v3 example vtotal = Virustotal(API_KEY="Insert API key here.", API_VERSION="v3") # You can provide True to the `COMPATIBILITY_ENABLED` parameter to preserve the old response format of virustotal-python versions prior to 0.1.0 vtotal = Virustotal(API_KEY="Insert API key here.", API_VERSION="v3", COMPATIBILITY_ENABLED=True) # You can also set proxies and timeouts for requests made by the library vtotal = Virustotal( API_KEY="Insert API key here.", API_VERSION="v3", PROXIES={"http": "http://10.10.1.10:3128", "https": "http://10.10.1.10:1080"}, TIMEOUT=5.0) # As of version 0.1.1, the Virustotal class can be invoked as a Context Manager! ## v2 example with Virustotal(API_KEY="Insert API key here.") as vtotal: # Your code here ## v3 example with Virustotal(API_KEY="Insert API key here.", API_VERSION="v3") as vtotal: # Your code here
Additionally, it is possible to provide an API key via the environment variable VIRUSTOTAL_API_KEY
.
Bash example:
export VIRUSTOTAL_API_KEY="Insert API key here."
PowerShell example:
$Env:VIRUSTOTAL_API_KEY = "Insert API key here."
Now, initialise the Virustotal
class:
from virustotal_python import Virustotal # v2 example vtotal = Virustotal() # v3 example vtotal = Virustotal(API_VERSION="v3")
Send a file for analysis:
import os.path from pprint import pprint # Declare PATH to file FILE_PATH = "/path/to/file/to/scan.txt" # Create dictionary containing the file to send for multipart encoding upload files = {"file": (os.path.basename(FILE_PATH), open(os.path.abspath(FILE_PATH), "rb"))} # v2 example resp = vtotal.request("file/scan", files=files, method="POST") # The v2 API returns a response_code # This property retrieves it from the JSON response print(resp.response_code) # Print JSON response from the API pprint(resp.json()) # v3 example resp = vtotal.request("files", files=files, method="POST") # The v3 API returns the JSON response inside the 'data' key # https://developers.virustotal.com/v3.0/reference#api-responses # This property retrieves the structure inside 'data' from the JSON response pprint(resp.data) # Or if you provided COMPATIBILITY_ENABLED=True to the Virustotal class pprint(resp["json_resp"])
Retrieve information about a file:
from pprint import pprint # The ID (either SHA-256, SHA-1 or MD5) identifying the file FILE_ID = "9f101483662fc071b7c10f81c64bb34491ca4a877191d464ff46fd94c7247115" # v2 example resp = vtotal.request("file/report", {"resource": FILE_ID}) print(resp.response_code) pprint(resp.json()) # v3 example resp = vtotal.request(f"files/{FILE_ID}") pprint(resp.data)
Send a URL for analysis, retrieve the analysis report and catch any potential exceptions that may occur (Non 200 HTTP status codes):
from virustotal_python import VirustotalError from pprint import pprint from base64 import urlsafe_b64encode url = "ihaveaproblem.info" # v2 example try: # Send a URL to VirusTotal for analysis resp = vtotal.request("url/scan", params={"url": url}, method="POST") url_resp = resp.json() # Obtain scan_id scan_id = url_resp["scan_id"] # Request report for URL analysis analysis_resp = vtotal.request("url/report", params={"resource": scan_id}) print(analysis_resp.response_code) pprint(analysis_resp.json()) except VirustotalError as err: print(f"An error occurred: {err}\nCatching and continuing with program.") # v3 example try: # Send URL to VirusTotal for analysis resp = vtotal.request("urls", data={"url": url}, method="POST") # URL safe encode URL in base64 format # https://developers.virustotal.com/v3.0/reference#url url_id = urlsafe_b64encode(url.encode()).decode().strip("=") # Obtain the analysis results for the URL using the url_id analysis_resp = vtotal.request(f"urls/{url_id}") pprint(analysis_resp.object_type) pprint(analysis_resp.data) except VirustotalError as err: print(f"An error occurred: {err}\nCatching and continuing with program.")
Retrieve information about a domain:
from pprint import pprint domain = "virustotal.com" # v2 example resp = vtotal.request("domain/report", params={"domain": domain}) print(resp.response_code) pprint(resp.json()) # v3 example resp = vtotal.request(f"domains/{domain}") pprint(resp.data)
Running the tests
To run the tests, perform the following steps:
-
Ensure pytest is installed using:
pip install pytest
-
Export your API key to the environment variable
VIRUSTOTAL_API_KEY
(instructions above). -
From the root directory of the project run
pytest -s .\virustotal_python\tests.py
Changelog
-
0.1.2 - Update dependencies for security vulnerability. Fixed an issue with some tests failing.
-
0.1.1 - Added Context Manager support and tests. Updated dependencies and license year.
-
0.1.0 - Added support for the VirusTotal v3 API. Library redesign (new usage, examples, tests and more.) See #24.
-
0.0.9 - Update dependencies for security vulnerability.
-
0.0.8 - Updated dependencies, removed method
file_rescan
-
0.0.7 - Added tests. Updated dependencies, Updated examples and README,
url_report
paramscan
now acceptstype(int)
, no longertype(str)
-
0.0.6 - Fixed usage example and dependencies in README.md, Setup github.io website, updated requirements.txt.
-
0.0.5 - Added Proxy support. Via HTTP(S) or using SOCKS: See #8.
-
0.0.4 - README.md updated; dependencies updated.
-
0.0.3 - Updated dependencies for urllib3 security vulnerability.
-
0.0.2 - Changes to file_rescan(), file_report(), url_scan(), url_report() to improve ease of use of the wrapper. See issue #2. Examples updated for changes.
-
0.0.1 - Initial release of virustotal-python. Covered all endpoints of the Virustotal public API.
Authors -- Contributors
- dbrennand - Author
License
This project is licensed under the MIT License - see the LICENSE for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size virustotal-python-0.1.2.tar.gz (13.3 kB) | File type Source | Python version None | Upload date | Hashes View |