# virustotal-python 🐍
[](https://github.com/dbrennand/virustotal-python/actions/workflows/ci.yml)
[](https://github.com/dbrennand/virustotal-python/actions/workflows/publish.yml)
A Python library to interact with the public VirusTotal v3 and v2 APIs.
> 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.
>
> It is highly recommended that you use the VirusTotal v3 API as it is the "default and encouraged way to programmatically interact with VirusTotal".
## Installation 🛠
```bash
# PyPi
pip install virustotal-python
# Manually
pip install .
# Poetry
poetry install --no-dev
```
## Get a VirusTotal API Key 🔑
[Sign up](https://www.virustotal.com/gui/join-us) for a VirusTotal account. Then, view your VirusTotal API key.
## Getting Started
```python
import virustotal_python
with virustotal_python.Virustotal("<VirusTotal API Key>") as vtotal:
# Your code here...
# Use the (old) VirusTotal version 2 API
with virustotal_python.Virustotal(
API_KEY="<VirusTotal API Key>", API_VERSION=2
) as vtotal:
# Your code here...
# You can also set proxies and timeouts for requests made by the library
# NOTE: To use proxies, you must have the PySocks extra installed
with virustotal_python.Virustotal(
API_KEY="<VirusTotal API Key>",
PROXIES={"http": "http://10.10.1.10:3128", "https": "https://10.10.1.10:1080"},
TIMEOUT=5.0,
) as vtotal:
# Your code here...
# You can also omit the API_KEY parameter and provide your
# API key via the environment variable VIRUSTOTAL_API_KEY
# Bash: export VIRUSTOTAL_API_KEY="<VirusTotal API Key>"
# PowerShell: $Env:VIRUSTOTAL_API_KEY = "<VirusTotal API Key>"
# Then...
with virustotal_python.Virustotal() as vtotal:
# Your code here...
```
## Code Snippets
> Further usage examples can be found in [examples](examples).
### Send a file for analysis 🔎
```python
import virustotal_python
import os.path
from pprint import pprint
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"))}
with virustotal_python.Virustotal("<VirusTotal API Key>") as vtotal:
resp = vtotal.request("files", files=files, method="POST")
pprint(resp.json())
```
### Get information about a file 📁
```python
import virustotal_python
from pprint import pprint
# The ID (either SHA-256, SHA-1 or MD5 hash) identifying the file
FILE_ID = "9f101483662fc071b7c10f81c64bb34491ca4a877191d464ff46fd94c7247115"
with virustotal_python.Virustotal("<VirusTotal API Key>") as vtotal:
resp = vtotal.request(f"files/{FILE_ID}")
pprint(resp.data)
```
### Send a URL 🔗 for analysis and get the report 📄
```python
import virustotal_python
from pprint import pprint
from base64 import urlsafe_b64encode
url = "ihaveaproblem.info"
with virustotal_python.Virustotal("<VirusTotal API Key>") as vtotal:
try:
resp = vtotal.request("urls", data={"url": url}, method="POST")
# Safe encode URL in base64 format
# https://developers.virustotal.com/reference/url
url_id = urlsafe_b64encode(url.encode()).decode().strip("=")
report = vtotal.request(f"urls/{url_id}")
pprint(report.object_type)
pprint(report.data)
except virustotal_python.VirustotalError as err:
print(f"Failed to send URL: {url} for analysis and get the report: {err}")
```
### Get information about a domain:
```python
import virustotal_python
from pprint import pprint
domain = "virustotal.com"
with virustotal_python.Virustotal("<VirusTotal API Key>") as vtotal:
resp = vtotal.request(f"domains/{domain}")
pprint(resp.data)
```
## Development
[Black](https://github.com/psf/black) is used for code formatting.
### Unit Tests
Install the development dependencies using Poetry:
```bash
poetry install && poetry shell
```
To run the unit tests, run `pytest` from the root of the project:
```bash
pytest --cov=virustotal_python
```
### Publishing a new release
```bash
# Run from the master branch
export VERSION=x.x.x
git commit --allow-empty -m "Publish $VERSION"
git tag -a $VERSION -m "Version $VERSION"
git push --tags
```
## Authors & Contributors
* [**dbrennand**](https://github.com/dbrennand) - *Author*
* [**smk762**](https://github.com/smk762) - *Contributor*
## Changelog
See the [CHANGELOG](CHANGELOG.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/dbrennand/virustotal-python",
"name": "virustotal-python",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "VirusTotal,Wrapper,Public API,Library,v3,v2",
"author": "dbrennand",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f5/0f/468369150422cfd36efbbbdcabc2f006cae1db117556056f85d14153c881/virustotal_python-1.0.1.tar.gz",
"platform": null,
"description": "# virustotal-python \ud83d\udc0d\n\n\n[](https://github.com/dbrennand/virustotal-python/actions/workflows/ci.yml)\n[](https://github.com/dbrennand/virustotal-python/actions/workflows/publish.yml)\n\nA Python library to interact with the public VirusTotal v3 and v2 APIs.\n\n> 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.\n>\n> It is highly recommended that you use the VirusTotal v3 API as it is the \"default and encouraged way to programmatically interact with VirusTotal\".\n\n## Installation \ud83d\udee0\n\n```bash\n# PyPi\npip install virustotal-python\n# Manually\npip install .\n# Poetry\npoetry install --no-dev\n```\n\n## Get a VirusTotal API Key \ud83d\udd11\n\n[Sign up](https://www.virustotal.com/gui/join-us) for a VirusTotal account. Then, view your VirusTotal API key.\n\n\n\n## Getting Started\n\n```python\nimport virustotal_python\n\nwith virustotal_python.Virustotal(\"<VirusTotal API Key>\") as vtotal:\n # Your code here...\n\n# Use the (old) VirusTotal version 2 API\nwith virustotal_python.Virustotal(\n API_KEY=\"<VirusTotal API Key>\", API_VERSION=2\n) as vtotal:\n # Your code here...\n\n# You can also set proxies and timeouts for requests made by the library\n# NOTE: To use proxies, you must have the PySocks extra installed\nwith virustotal_python.Virustotal(\n API_KEY=\"<VirusTotal API Key>\",\n PROXIES={\"http\": \"http://10.10.1.10:3128\", \"https\": \"https://10.10.1.10:1080\"},\n TIMEOUT=5.0,\n) as vtotal:\n # Your code here...\n\n# You can also omit the API_KEY parameter and provide your\n# API key via the environment variable VIRUSTOTAL_API_KEY\n# Bash: export VIRUSTOTAL_API_KEY=\"<VirusTotal API Key>\"\n# PowerShell: $Env:VIRUSTOTAL_API_KEY = \"<VirusTotal API Key>\"\n# Then...\nwith virustotal_python.Virustotal() as vtotal:\n # Your code here...\n```\n\n## Code Snippets\n\n> Further usage examples can be found in [examples](examples).\n\n### Send a file for analysis \ud83d\udd0e\n\n```python\nimport virustotal_python\nimport os.path\nfrom pprint import pprint\n\nFILE_PATH = \"/path/to/file/to/scan.txt\"\n\n# Create dictionary containing the file to send for multipart encoding upload\nfiles = {\"file\": (os.path.basename(FILE_PATH), open(os.path.abspath(FILE_PATH), \"rb\"))}\n\nwith virustotal_python.Virustotal(\"<VirusTotal API Key>\") as vtotal:\n resp = vtotal.request(\"files\", files=files, method=\"POST\")\n pprint(resp.json())\n```\n\n### Get information about a file \ud83d\udcc1\n\n```python\nimport virustotal_python\nfrom pprint import pprint\n\n# The ID (either SHA-256, SHA-1 or MD5 hash) identifying the file\nFILE_ID = \"9f101483662fc071b7c10f81c64bb34491ca4a877191d464ff46fd94c7247115\"\n\nwith virustotal_python.Virustotal(\"<VirusTotal API Key>\") as vtotal:\n resp = vtotal.request(f\"files/{FILE_ID}\")\n pprint(resp.data)\n```\n\n### Send a URL \ud83d\udd17 for analysis and get the report \ud83d\udcc4\n\n```python\nimport virustotal_python\nfrom pprint import pprint\nfrom base64 import urlsafe_b64encode\n\nurl = \"ihaveaproblem.info\"\n\nwith virustotal_python.Virustotal(\"<VirusTotal API Key>\") as vtotal:\n try:\n resp = vtotal.request(\"urls\", data={\"url\": url}, method=\"POST\")\n # Safe encode URL in base64 format\n # https://developers.virustotal.com/reference/url\n url_id = urlsafe_b64encode(url.encode()).decode().strip(\"=\")\n report = vtotal.request(f\"urls/{url_id}\")\n pprint(report.object_type)\n pprint(report.data)\n except virustotal_python.VirustotalError as err:\n print(f\"Failed to send URL: {url} for analysis and get the report: {err}\")\n```\n\n### Get information about a domain:\n\n```python\nimport virustotal_python\nfrom pprint import pprint\n\ndomain = \"virustotal.com\"\n\nwith virustotal_python.Virustotal(\"<VirusTotal API Key>\") as vtotal:\n resp = vtotal.request(f\"domains/{domain}\")\n pprint(resp.data)\n```\n\n## Development\n\n[Black](https://github.com/psf/black) is used for code formatting.\n\n### Unit Tests\n\nInstall the development dependencies using Poetry:\n\n```bash\npoetry install && poetry shell\n```\n\nTo run the unit tests, run `pytest` from the root of the project:\n\n```bash\npytest --cov=virustotal_python\n```\n\n### Publishing a new release\n\n```bash\n# Run from the master branch\nexport VERSION=x.x.x\ngit commit --allow-empty -m \"Publish $VERSION\"\ngit tag -a $VERSION -m \"Version $VERSION\"\ngit push --tags\n```\n\n## Authors & Contributors\n\n* [**dbrennand**](https://github.com/dbrennand) - *Author*\n\n* [**smk762**](https://github.com/smk762) - *Contributor*\n\n## Changelog\n\nSee the [CHANGELOG](CHANGELOG.md) for details.\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library to interact with the public VirusTotal v3 and v2 APIs.",
"version": "1.0.1",
"split_keywords": [
"virustotal",
"wrapper",
"public api",
"library",
"v3",
"v2"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7777134deadd42c6e2f7b0f30fac2635",
"sha256": "c2d59b27b887163da26e7a249587e1d6e4b91f5071266ce8a053e3d5041b7de4"
},
"downloads": -1,
"filename": "virustotal_python-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7777134deadd42c6e2f7b0f30fac2635",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 7994,
"upload_time": "2022-12-10T12:12:34",
"upload_time_iso_8601": "2022-12-10T12:12:34.595514Z",
"url": "https://files.pythonhosted.org/packages/0c/cc/791d94e7a579ea6587d5fcb0ddb0d61a77815724a92c5ec6c80fa6299525/virustotal_python-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "b4ea7d32f54cc12fc18ad106053bc72a",
"sha256": "b113a48d7de7c00831c7dcc46a195d1195e262a18fe387a24b69535cdd63a275"
},
"downloads": -1,
"filename": "virustotal_python-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b4ea7d32f54cc12fc18ad106053bc72a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 7594,
"upload_time": "2022-12-10T12:12:36",
"upload_time_iso_8601": "2022-12-10T12:12:36.093428Z",
"url": "https://files.pythonhosted.org/packages/f5/0f/468369150422cfd36efbbbdcabc2f006cae1db117556056f85d14153c881/virustotal_python-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-10 12:12:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dbrennand",
"github_project": "virustotal-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "virustotal-python"
}
JSON
