{"id":22620535,"url":"https://github.com/dbrennand/virustotal-python","last_synced_at":"2025-07-30T13:09:04.407Z","repository":{"id":42209249,"uuid":"170215279","full_name":"dbrennand/virustotal-python","owner":"dbrennand","description":"A Python library to interact with the public VirusTotal v3 and v2 APIs.","archived":false,"fork":false,"pushed_at":"2024-05-26T20:05:47.000Z","size":236,"stargazers_count":70,"open_issues_count":0,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-30T23:54:40.056Z","etag":null,"topics":["malware","malware-analysis","python","python3","security","virustotal","virustotal-python","wrapper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbrennand.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-11T22:50:09.000Z","updated_at":"2025-04-25T22:19:33.000Z","dependencies_parsed_at":"2024-05-18T23:23:50.492Z","dependency_job_id":"af4d3883-8aca-4775-b90d-5623327edb7c","html_url":"https://github.com/dbrennand/virustotal-python","commit_stats":{"total_commits":155,"total_committers":4,"mean_commits":38.75,"dds":"0.16129032258064513","last_synced_commit":"68e88493a43dc5bc8fa5eb3217c1f90617d18993"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrennand%2Fvirustotal-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrennand%2Fvirustotal-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrennand%2Fvirustotal-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrennand%2Fvirustotal-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbrennand","download_url":"https://codeload.github.com/dbrennand/virustotal-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252771672,"owners_count":21801759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["malware","malware-analysis","python","python3","security","virustotal","virustotal-python","wrapper"],"created_at":"2024-12-08T22:14:14.329Z","updated_at":"2025-05-06T21:29:38.148Z","avatar_url":"https://github.com/dbrennand.png","language":"Python","readme":"# virustotal-python 🐍\n![PyPI](https://img.shields.io/pypi/v/virustotal-python.svg?style=flat-square)\n![PyPI Stats](https://img.shields.io/pypi/dm/virustotal-python?color=blue\u0026style=flat-square)\n[![CI](https://github.com/dbrennand/virustotal-python/actions/workflows/ci.yml/badge.svg)](https://github.com/dbrennand/virustotal-python/actions/workflows/ci.yml)\n[![Publish](https://github.com/dbrennand/virustotal-python/actions/workflows/publish.yml/badge.svg)](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\u003e 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\u003e\n\u003e 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 🛠\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 🔑\n\n[Sign up](https://www.virustotal.com/gui/join-us) for a VirusTotal account. Then, view your VirusTotal API key.\n\n![VirusTotal view API key](images/APIKey.png)\n\n## Getting Started\n\n```python\nimport virustotal_python\n\nwith virustotal_python.Virustotal(\"\u003cVirusTotal API Key\u003e\") as vtotal:\n    # Your code here...\n\n# Use the (old) VirusTotal version 2 API\nwith virustotal_python.Virustotal(\n    API_KEY=\"\u003cVirusTotal API Key\u003e\", 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=\"\u003cVirusTotal API Key\u003e\",\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=\"\u003cVirusTotal API Key\u003e\"\n# PowerShell: $Env:VIRUSTOTAL_API_KEY = \"\u003cVirusTotal API Key\u003e\"\n# Then...\nwith virustotal_python.Virustotal() as vtotal:\n    # Your code here...\n```\n\n## Code Snippets\n\n\u003e Further usage examples can be found in [examples](examples).\n\n### Send a file for analysis 🔎\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(\"\u003cVirusTotal API Key\u003e\") as vtotal:\n    resp = vtotal.request(\"files\", files=files, method=\"POST\")\n    pprint(resp.json())\n```\n\n### Get information about a file 📁\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(\"\u003cVirusTotal API Key\u003e\") as vtotal:\n    resp = vtotal.request(f\"files/{FILE_ID}\")\n    pprint(resp.data)\n```\n\n### Send a URL 🔗 for analysis and get the report 📄\n\n```python\nimport virustotal_python\nfrom pprint import pprint\nfrom base64 import urlsafe_b64encode\n\nurl = \"ihaveaproblem.info\"\n\nwith virustotal_python.Virustotal(\"\u003cVirusTotal API Key\u003e\") 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(\"\u003cVirusTotal API Key\u003e\") 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 \u0026\u0026 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 \u0026 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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbrennand%2Fvirustotal-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbrennand%2Fvirustotal-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbrennand%2Fvirustotal-python/lists"}