{"id":13581989,"url":"https://github.com/VirusTotal/vt-cli","last_synced_at":"2025-04-06T10:33:12.273Z","repository":{"id":33697784,"uuid":"133561480","full_name":"VirusTotal/vt-cli","owner":"VirusTotal","description":"VirusTotal Command Line Interface","archived":false,"fork":false,"pushed_at":"2024-08-14T08:15:15.000Z","size":354,"stargazers_count":896,"open_issues_count":10,"forks_count":84,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-03-31T07:03:56.987Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://virustotal.github.io/vt-cli/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirusTotal.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-15T19:08:20.000Z","updated_at":"2025-03-26T19:26:31.000Z","dependencies_parsed_at":"2024-01-02T09:38:45.286Z","dependency_job_id":"f110f9bb-0095-4258-a918-6d96cf707c26","html_url":"https://github.com/VirusTotal/vt-cli","commit_stats":{"total_commits":181,"total_committers":15,"mean_commits":"12.066666666666666","dds":0.2320441988950276,"last_synced_commit":"2068b9576ed883be75e4260bf8bd81130ef7f55b"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirusTotal%2Fvt-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirusTotal%2Fvt-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirusTotal%2Fvt-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirusTotal%2Fvt-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirusTotal","download_url":"https://codeload.github.com/VirusTotal/vt-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470564,"owners_count":20944146,"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":[],"created_at":"2024-08-01T15:02:22.105Z","updated_at":"2025-04-06T10:33:10.045Z","avatar_url":"https://github.com/VirusTotal.png","language":"Go","readme":"# VirusTotal CLI\n\nWelcome to the VirusTotal CLI, a tool designed for those who love both VirusTotal and command-line interfaces. With this tool you can do everything you'd normally do using VirusTotal's web page, including:\n\n* Retrieve information about a [file](doc/vt_file.md), [URL](doc/vt_url.md), [domain name](doc/vt_domain.md), [IP address](doc/vt_ip.md), etc.\n* [Search](doc/vt_search.md) for files and URLs using VirusTotal Intelligence query syntax.\n* [Download files](doc/vt_download.md).\n* [Manage your LiveHunt YARA rules](doc/vt_hunting_ruleset.md).\n* [Launch Retrohunt jobs](doc/vt_retrohunt_start.md) and [get their results](doc/vt_retrohunt_matches.md).\n\nAnd much [more](doc/vt.md)...\n\n## See it in action\n\n[![asciicast](https://asciinema.org/a/179696.png)](https://asciinema.org/a/179696)\n\n## Getting started\n\nAs this tool uses the [VirusTotal API](https://docs.virustotal.com/reference) under the hood, you will need a VirusTotal API key. By [signing up](https://www.virustotal.com/#/join-us) with VirusTotal you will receive a free API key however, free API keys have a limited amount of requests per minute, and they don't have access to some premium features like searches and file downloads. If you are interested in using those premium features please [contact us](https://www.virustotal.com/gui/contact-us/).\n\n### Installing the tool\n\nThere are two ways of installing the tool: by using one of our pre-compiled binaries or by building it by yourself.\n\n#### Pre-compiled binaries\n\nThe pre-compiled binaries can be found on [the releases page](https://github.com/VirusTotal/vt-cli/releases). There are binaries for Windows, Linux and Mac OS X. To use them, just download the file, decompress it and place it in a directory where you think is more convenient to use.\n\n#### Manual building\n\nTo compile the program you'll need [Go 1.14.x or higher installed in your system](https://go.dev/doc/install) and type the following commands:\n\n```sh\n$ git clone https://github.com/VirusTotal/vt-cli\n$ cd vt-cli\n$ make install\n```\n\nNOTE: in order to use the `vt` binary, make sure the `GOBIN` is part of your `PATH` env variable:\n\n```sh\n$ export GOBIN=`go env GOPATH`/bin\n$ export PATH=$PATH:$GOBIN\n```\n\n##### Mac OS\n\nFor Mac OS users, there's a [brew formula](https://formulae.brew.sh/formula/virustotal-cli) available. Please note this is not maintained by VirusTotal.\n\n```sh\n$ brew install virustotal-cli\n```\n\n##### Windows\n\nFor Windows users, there's a [Winget manifest](https://github.com/microsoft/winget-pkgs/tree/master/manifests/v/VirusTotal/vt-cli) available. Please note this is not maintained by VirusTotal.\n\n```powershell\nwinget install VirusTotal.vt-cli\n```\n\nChocolatey is [also supported](https://community.chocolatey.org/packages/vt-cli) (Also not maintained by VirusTotal):\n\n```powershell\nchoco install vt-cli\n```\n\n### A note on Window's console\n\nIf you plan to use `vt-cli` in Windows on a regular basis we highly recommend you avoid the standard Windows console and use [Cygwin](https://www.cygwin.com/) instead. The Windows console is *very* slow when printing large amounts of text (as `vt-cli` usually does) while Cygwin performs much better. Additionally, you can benefit from Cygwin's support for command auto-completion, a handy feature that the Windows console doesn't offer. In order to take advantage of auto-completion make sure to include the `bash-completion` package while installing Cygwin.\n\n### Configuring your API key\n\nOnce you have installed the vt-cli tool you may want to configure it with your API key. This is not strictly necessary, as you can provide your API key every time you invoke the tool by using the `--apikey` option (`-k` in short form), but that's a bit of a hassle if you are going to use the tool frequently (and we bet you'll do!). For configuring your API key just type:\n\n```sh\n$ vt init\n```\n\nThis command will ask for your API key, and save it to a config file in your home directory (~/.vt.toml). You can also specify your API key using the  `VTCLI_APIKEY` environment variable. If you specify your API key in multiple ways, the `--apikey` option will have the highest precedence, followed by the `VTCLI_APIKEY` environment variable, the API key in the configuration file will be used as the last resort.\n\n### Use with a proxy\n\nIf you are behind an HTTP proxy you can tell `vt-cli` which is the address of your proxy server in multiple ways. One is using the `--proxy` option, like in:\n\n```sh\n$ vt --proxy http://myproxy.com:1234 \u003ccommand\u003e\n```\n\nYou can also use the `VTCLI_PROXY` environment variable, or add the following line to the config file:\n\n```sh\nproxy=\"http://myproxy.com:1234\"\n```\n\n### Setup Bash completion\n\nIf you are going to use this tool frequently you may want to have command auto-completion. It saves both precious time and keystrokes. Notice however that you must configure your API as described in the previous section *before* following the steps listed below. The API is necessary for determining the commands that you will have access to.\n\n* Linux:\n\n  ```sh\n  $ vt completion bash \u003e /etc/bash_completion.d/vt\n  ```\n\n* Mac OS X:\n\n  ```sh\n  $ brew install bash-completion\n  $ vt completion bash \u003e $(brew --prefix)/etc/bash_completion.d/vt\n  ```\n\n  Add the  following lines to `~/.bash_profile`:\n\n  ```sh\n  if [ -f $(brew --prefix)/etc/bash_completion ]; then\n  . $(brew --prefix)/etc/bash_completion\n  fi\n  ```\n\n* Cygwin:\n\n  Make sure the `bash-completion` package is installed (Cygwin doesn't install it by default) and type:\n\n  ```sh\n  $ vt completion bash \u003e /usr/share/bash-completion/completions/vt\n  ```\n\n:heavy_exclamation_mark: You may need to restart your shell in order for autocompletion to start working.\n\n### Setup ZSH completion\n\nThe output script from `vt completion zsh` needs to be put somewhere under the `$fpath` directory. For example, `.oh-my-zsh/completions` directory:\n\n```shellsession\n$ mkdir /Users/$USERNAME/.oh-my-zsh/completions\n$ vt completion zsh \u003e /Users/$USERNAME/.oh-my-zsh/completions/_vt\n```\n\nRestart the shell.\n\n## Usage examples\n\n* Get information about a file:\n\n  ```sh\n  $ vt file 8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85\n  ```\n\n* Get information about a file in JSON format:\n\n  ```sh\n  $ vt file 8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85 --format json\n  ```\n\n* Get a specific analysis report for a file:\n\n  ```sh\n  $ # File analysis IDs can be given as `f-\u003cfile_SHA256_hash\u003e-\u003cUNIX timestamp\u003e`...\n  $ vt analysis f-8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85-1546309359\n  $ # ...or as a Base64 encoded string, retrieved from the `vt scan file` command:\n  $ vt scan file test.txt\n  test.txt MDJiY2FiZmZmZmQxNmZlMGZjMjUwZjA4Y2FkOTVlMGM6MTU0NjQ1NDUyMA==\n  $ vt analysis MDJiY2FiZmZmZmQxNmZlMGZjMjUwZjA4Y2FkOTVlMGM6MTU0NjQ1NDUyMA==\n  - _id: \"MDJiY2FiZmZmZmQxNmZlMGZjMjUwZjA4Y2FkOTVlMGM6MTU0NjQ1NDUyMA==\"\n    _type: \"analysis\"\n    date: 1546454520  # 2019-01-02 13:42:00 -0500 EST\n    stats:\n      failure: 0\n      harmless: 0\n      malicious: 0\n      suspicious: 0\n      timeout: 0\n      type-unsupported: 0\n      undetected: 0\n    status: \"queued\"\n  ```\n\n* Download files given a list of hashes in a text file, one hash per line:\n\n  ```sh\n  $ cat /path/list_of_hashes.txt | vt download -\n  ```\n\n* Get information about a URL:\n\n  ```sh\n  $ vt url http://www.virustotal.com\n  ```\n\n* Get the IP address that served a URL:\n\n  ```sh\n  $ vt url last_serving_ip_address http://www.virustotal.com\n  ```\n\n* Search for files:\n\n  ```sh\n  $ vt search \"positives:5+ type:pdf\"\n  ```\n  \n* Scan a file:\n\n  ```sh\n  $ vt scan file \u003cyourfile\u003e\n  \u003cyourfile\u003e ZDZiOTcxY2JhNDE0MWU5ZWRjN2JjNGQ2NTdhN2VjODU6MTU3MDE3Mjg1NQ==\n  $ vt analysis ZDZiOTcxY2JhNDE0MWU5ZWRjN2JjNGQ2NTdhN2VjODU6MTU3MDE3Mjg1NQ==\n  - _id: \"ZDZiOTcxY2JhNDE0MWU5ZWRjN2JjNGQ2NTdhN2VjODU6MTU3MDE3Mjg1NQ==\"\n    _type: \"analysis\"\n    date: 1570172855  # 2019-10-04 09:07:35 +0200 CEST\n    stats:\n      failure: 0\n      harmless: 0\n      malicious: 0\n      suspicious: 0\n      timeout: 0\n      type-unsupported: 0\n      undetected: 0\n    status: \"queued\"\n  ```\n\n* Export detections and tags of files from a search in CSV format:\n\n  ```sh\n  $ vt search \"positives:5+ type:pdf\" -i sha256,last_analysis_stats.malicious,tags --format csv\n  ```\n\n* Export detections and tags of files from a search in JSON format:\n\n  ```sh\n  $ vt search \"positives:5+ type:pdf\" -i sha256,last_analysis_stats.malicious,tags --format json\n  ```\n\n## Getting only what you want\n\nWhen you ask for information about a file, URL, domain, IP address or any other object in VirusTotal, you get a lot of data (by default in YAML format) that is usually more than what you need. You can narrow down the information shown by the vt-cli tool by using the `--include` and `--exclude` command-line options (`-i` and `-x` in short form).\n\nThese options accept patterns that are matched against the fields composing the data, and allow you to include only a subset of them, or exclude any field that is not interesting for you. Let's see how it works using the data we have about `http://www.virustotal.com` as an example:\n\n```sh\n$ vt url http://www.virustotal.com\n- _id: 1db0ad7dbcec0676710ea0eaacd35d5e471d3e11944d53bcbd31f0cbd11bce31\n  _type: \"url\"\n  first_submission_date: 1275391445  # 2010-06-01 13:24:05 +0200 CEST\n  last_analysis_date: 1532442650  # 2018-07-24 16:30:50 +0200 CEST\n  last_analysis_results:\n    ADMINUSLabs:\n      category: \"harmless\"\n      engine_name: \"ADMINUSLabs\"\n      result: \"clean\"\n    AegisLab WebGuard:\n      category: \"harmless\"\n      engine_name: \"AegisLab WebGuard\"\n      result: \"clean\"\n    AlienVault:\n      category: \"harmless\"\n      engine_name: \"AlienVault\"\n      result: \"clean\"\n  last_http_response_code: 200\n  last_http_response_content_length: 7216\n  last_http_response_content_sha256: \"7ed66734d9fb8c5a922fffd039c1cd5d85f8c2bb39d14803983528437852ba94\"\n  last_http_response_headers:\n    age: \"26\"\n    cache-control: \"public, max-age=60\"\n    content-length: \"7216\"\n    content-type: \"text/html\"\n    date: \"Tue, 24 Jul 2018 14:30:24 GMT\"\n    etag: \"\\\"bGPKJQ\\\"\"\n    expires: \"Tue, 24 Jul 2018 14:31:24 GMT\"\n    server: \"Google Frontend\"\n    x-cloud-trace-context: \"131ac6cb5e2cdb7970d54ee42fd5ce4a\"\n    x-frame-options: \"DENY\"\n  last_submission_date: 1532442650  # 2018-07-24 16:30:50 +0200 CEST\n  private: false\n  reputation: 1484\n  times_submitted: 213227\n  total_votes:\n    harmless: 660\n    malicious: 197\n```\n\nNotice that the returned data usually follows a hierarchical structure, with some top-level fields that may contain subfields which in turn can contain their own subfields. In the example above `last_http_response_headers` has subfields `age`, `cache-control`, `content-length` and so on, while `total_votes` has `harmless` and `malicious`. For referring to a particular field within the hierarchy we can use a path, similar to how we identify a file in our computers, but in this case, we are going to use a dot character (.) as the separator for path components, instead of the slashes (or backslashes) used by most file systems. The following ones are valid paths for our example structure:\n\n* `last_http_response_headers.age`\n* `total_votes.harmless`\n* `last_analysis_results.ADMINUSLabs.category`\n* `last_analysis_results.ADMINUSLabs.engine_name`\n\nThe filters accepted by both `--include` and `--exclude` are paths in which we can use `*` and `**` as placeholders for one and many path elements respectively. For example `foo.*` matches `foo.bar` but not `foo.bar.baz`, while `foo.**` matches `foo.bar`, `foo.bar.baz` and `foo.bar.baz.qux`. In the other hand, `foo.*.qux` matches `foo.bar.qux` and `foo.baz.qux` but not `foo.bar.baz.qux`, while `foo.**.qux` matches\n`foo.bar.baz.qux` and any other path starting with `foo` and ending with `qux`.\n\nFor cherry-picking only the fields you want, you should use `--include` followed by a path pattern as explained above. You can also include more than one pattern either by using the `--include` argument multiple times, or by using it with a comma-separated list of patterns. The following two options are equivalent:\n\n```sh\n$ vt url http://www.virustotal.com --include=reputation --include=total_votes.*\n$ vt url http://www.virustotal.com --include=reputation,total_votes.*\n```\n\nHere you have different examples with their outputs (assuming that `vt url http://www.virustotal.com` returns the structure shown above):\n\n```sh\n$ vt url http://www.virustotal.com --include=last_http_response_headers.server\n- last_http_response_headers:\n    server: \"Google Frontend\"\n```\n\n```sh\n$ vt url http://www.virustotal.com --include=last_http_response_headers.*\n- last_http_response_headers:\n    age: \"26\"\n    cache-control: \"public, max-age=60\"\n    content-length: \"7216\"\n    content-type: \"text/html\"\n    date: \"Tue, 24 Jul 2018 14:30:24 GMT\"\n    etag: \"\\\"bGPKJQ\\\"\"\n    expires: \"Tue, 24 Jul 2018 14:31:24 GMT\"\n    server: \"Google Frontend\"\n    x-cloud-trace-context: \"131ac6cb5e2cdb7970d54ee42fd5ce4a\"\n    x-frame-options: \"DENY\"\n```\n\n```sh\n$ vt url http://www.virustotal.com --include=last_analysis_results.**\n- last_analysis_results:\n    ADMINUSLabs:\n      category: \"harmless\"\n      engine_name: \"ADMINUSLabs\"\n      result: \"clean\"\n    AegisLab WebGuard:\n      category: \"harmless\"\n      engine_name: \"AegisLab WebGuard\"\n      result: \"clean\"\n    AlienVault:\n      category: \"harmless\"\n      engine_name: \"AlienVault\"\n      result: \"clean\"\n```\n\n```sh\n$ vt url http://www.virustotal.com --include=last_analysis_results.*.result\n- last_analysis_results:\n    ADMINUSLabs:\n      result: \"clean\"\n    AegisLab WebGuard:\n      result: \"clean\"\n    AlienVault:\n      result: \"clean\"\n```\n\n```sh\n$ vt url http://www.virustotal.com --include=**.result\n- last_analysis_results:\n    ADMINUSLabs:\n      result: \"clean\"\n    AegisLab WebGuard:\n      result: \"clean\"\n    AlienVault:\n      result: \"clean\"\n```\n\nAlso notice that `_id` and `_type` are also field names and therefore you can use them in your filters:\n\n```sh\n$ vt url http://www.virustotal.com --include=_id,_type,**.result\n- _id: \"1db0ad7dbcec0676710ea0eaacd35d5e471d3e11944d53bcbd31f0cbd11bce31\"\n  _type: \"file\"\n  last_analysis_results:\n    ADMINUSLabs:\n      result: \"clean\"\n    AegisLab WebGuard:\n      result: \"clean\"\n    AlienVault:\n      result: \"clean\"\n```\n\nThe `--exclude` option works similarly to `--include` but instead of including the matching fields in the output, it includes everything except the matching fields. You can use this option when you want to keep most of the fields, but leave out a few of them that are not interesting. If you use `--include` and `--exclude` simultaneously `--include` enters in action first, including only the fields that match the `--include` patterns, while `--exclude` comes in after that, removing any remaining field that matches the `--exclude` patterns.\n","funding_links":[],"categories":["Go","Malware Analysis"],"sub_categories":["Virus/Anti-Virus"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirusTotal%2Fvt-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVirusTotal%2Fvt-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirusTotal%2Fvt-cli/lists"}