Skip to content

ytonui/VirusTotalApi

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VirusTotal public and private APIv2 Full support - VT APIv3 on the way :)

This script was made public into the official VT API documentation page. https://www.virustotal.com/en/documentation/public-api/

Before using the tool you must set your api key in one of this file or you can start without creating it and you will be prompted to provide the data:

  • Home Directory:

    • ~.vtapi, ~vtapi.conf
  • or current directory where vt script placed

    • .vtapi, vtapi.conf
  • ~.vtapi file content:

[vt]
apikey=your-apikey-here
type=public
intelligence=False
#coma separated engine list, can be empty
engines=
timeout=60
# as for weblogin, this only required for rule management
username=
password=
  • your type of api access, if private: type=private, if public, you can leave it empty, it will be automatically recognized as public
  • if you have access to VT Intelligence, you need set intelligence=True

Dependencies:

  • requests
  • texttable
  • python-dateutil

These can be installed via PIP or a package manager. Example of installing all dependencies using pip:

pip install -r requirements.txt
  • Thanks to @kellewic and @urbanski
  • Special thanks to @Seifreed for testing and reporting bugs

Example of usage as library can be found here

Few public API functions taken from Chris Clark script
And finally has been added full public and private API support by Andriy Brukhovetskyy (doomedraven)

Small manual with examples http://www.doomedraven.com/2013/11/script-virustotal-public-and-private.html

  • BEAR IN MIND THIS IS AN OLD EXAMPLE, use -h for current help
vt -h
usage: value [-h] [-fi] [-udb USERDB] [-fs] [-f] [-fr] [-u] [-ur] [-d] [-i]
             [-w] [-s] [-si] [-et] [-rai] [-itu] [-cw] [-dep] [-eo] [-snr]
             [-srct] [-tir] [-wir] [-rbgi] [-rbi] [-agi] [-dbc] [-ac] [-gc]
             [--get-comments-before DATE] [-v] [-j] [--csv] [-rr] [-rj] [-V]
             [-r] [--delete] [--date DATE] [--period PERIOD] [--repeat REPEAT]
             [--notify-url NOTIFY_URL] [--notify-changes-only] [-wh] [-wht]
             [-pdns] [--asn] [-aso] [--country] [--subdomains]
             [--domain-siblings] [-cat] [-alc] [-alk] [-opi] [--drweb-cat]
             [-adi] [-wdi] [-tm] [-wt] [-bd] [-wd] [-du] [--pcaps] [--samples]
             [-dds] [-uds] [-dc] [-uc] [-drs] [-urs] [-pe]
             [-esa SAVE_ATTACHMENT] [-peo] [-bh] [-bn] [-bp] [-bs] [-dl]
             [-nm NAME] [-dt DOWNLOAD_THREADS] [--pcap] [--clusters]
             [--distribution-files] [--distribution-urls] [--before BEFORE]
             [--after AFTER] [--reports] [--limit LIMIT] [--allinfo] [--rules]
             [--list] [--create FILE] [--update FILE] [--retro FILE]
             [--delete_rule DELETE_RULE] [--share]
             [--update_ruleset UPDATE_RULESET] [--disable DISABLE]
             [--enable ENABLE]
             [value [value ...]]

Scan/Search/ReScan/JSON parse

positional arguments:
  value                 Enter the Hash, Path to File(s) or Url(s)

optional arguments:
  -h, --help            show this help message and exit
  -fi, --file-info      Get PE file info, all data extracted offline, for work
                        you need have installed PEUTILS library
  -udb USERDB, --userdb USERDB
                        Path to your userdb file, works with --file-info
                        option only
  -fs, --file-search    File(s) search, this option, don't upload file to
                        VirusTotal, just search by hash, support linux name
                        wildcard, example: /home/user/*malware*, if file was
                        scanned, you will see scan info, for full scan report
                        use verbose mode, and dump if you want save already
                        scanned samples
  -f, --file-scan       File(s) scan, support linux name wildcard, example:
                        /home/user/*malware*, if file was scanned, you will
                        see scan info, for full scan report use verbose mode,
                        and dump if you want save already scanned samples
  -fr, --file-scan-recursive
                        Recursive dir walk, use this instead of --file-scan if
                        you want recursive
  -u, --url-scan        Url scan, support space separated list, Max 4 urls (or
                        25 if you have private api), but you can provide more
                        urls, for example with public api, 5 url - this will
                        do 2 requests first with 4 url and other one with only
                        1, or you can specify file filename with one url per
                        line
  -ur, --url-report     Url(s) report, support space separated list, Max 4 (or
                        25 if you have private api) urls, you can use --url-
                        report --url-scan options for analyzing url(s) if they
                        are not in VT data base, read preview description
                        about more then max limits or file with urls
  -d, --domain-info     Retrieves a report on a given domain (PRIVATE API
                        ONLY! including the information recorded by
                        VirusTotal's Passive DNS infrastructure)
  -i, --ip-info         A valid IPv4 address in dotted quad notation, for the
                        time being only IPv4 addresses are supported.
  -w, --walk            Work with domain-info, will walk through all detected
                        ips and get information, can be provided ip parameters
                        to get only specific information
  -s, --search          A md5/sha1/sha256 hash for which you want to retrieve
                        the most recent report. You may also specify a scan_id
                        (sha256-timestamp as returned by the scan API) to
                        access a specific report. You can also specify a space
                        separated list made up of a combination of hashes and
                        scan_ids Public API up to 4 items/Private API up to 25
                        items, this allows you to perform a batch request with
                        one single call.
  -si, --search-intelligence
                        Search query, help can be found here -
                        https://www.virustotal.com/intelligence/help/
  -et, --email-template
                        Table format template for email
  -ac, --add-comment    The actual review, you can tag it using the "#"
                        twitter-like syntax (e.g. #disinfection #zbot) and
                        reference users using the "@" syntax (e.g.
                        @VirusTotalTeam). supported hashes MD5/SHA1/SHA256
  -gc, --get-comments   Either a md5/sha1/sha256 hash of the file or the URL
                        itself you want to retrieve
  --get-comments-before DATE
                        A datetime token that allows you to iterate over all
                        comments on a specific item whenever it has been
                        commented on more than 25 times. Token format
                        20120725170000 or 2012-07-25 17 00 00 or 2012-07-25
                        17:00:00
  -v, --verbose         Turn on verbosity of VT reports
  -j, --dump            Dumps the full VT report to file (VTDL{md5}.json), if
                        you (re)scan many files/urls, their json data will be
                        dumped to separated files
  --csv                 Dumps the AV's detections to file (VTDL{scan_id}.csv)
  -rr, --return-raw     Return raw json, in case if used as library and want
                        parse in other way
  -rj, --return-json    Return json with parts activated, for example -p for
                        passive dns, etc
  -V, --version         Show version and exit

All information related:
  -rai, --report-all-info
                        If specified and set to one, the call will return
                        additional info, other than the antivirus results, on
                        the file being queried. This additional info includes
                        the output of several tools acting on the file (PDFiD,
                        ExifTool, sigcheck, TrID, etc.), metadata regarding
                        VirusTotal submissions (number of unique sources that
                        have sent the file in the past, first seen date, last
                        seen date, etc.), and the output of in-house
                        technologies such as a behavioural sandbox.
  -itu, --ITW-urls      In the wild urls
  -cw, --compressedview
                        Contains information about extensions, file_types,
                        tags, lowest and highest datetime, num children
                        detected, type, uncompressed_size, vhash, children
  -dep, --detailed-email-parents
                        Contains information about emails, as Subject, sender,
                        receiver(s), full email, and email hash to download it
  -eo, --email-original
                        Will retrieve original email and process it
  -snr, --snort         Get Snort results
  -srct, --suricata     Get Suricata results
  -tir, --traffic-inspection
                        Get Traffic inspection info
  -wir, --wireshark-info
                        Get Wireshark info
  -rbgi, --rombios-generator-info
                        Get RomBios generator info
  -rbi, --rombioscheck-info
                        Get RomBiosCheck info
  -agi, --androidguard-info
                        Get AndroidGuard info
  -dbc, --debcheck-info
                        Get DebCheck info, also include ios IPA

Rescan options:
  -r, --rescan          Allows you to rescan files in VirusTotal's file store
                        without having to resubmit them, thus saving
                        bandwidth, support space separated list, MAX 25
                        hashes, can be local files, hashes will be generated
                        on the fly, support linux wildmask
  --delete              A md5/sha1/sha256 hash for which you want to delete
                        the scheduled scan
  --date DATE           A Date in one of this formats (example: 20120725170000
                        or 2012-07-25 17 00 00 or 2012-07-25 17:00:00) in
                        which the rescan should be performed. If not specified
                        the rescan will be performed immediately.
  --period PERIOD       Period in days in which the file should be rescanned.
                        If this argument is provided the file will be
                        rescanned periodically every period days, if not, the
                        rescan is performed once and not repeated again.
  --repeat REPEAT       Used in conjunction with period to specify the number
                        of times the file should be rescanned. If this
                        argument is provided the file will be rescanned the
                        given amount of times, if not, the file will be
                        rescanned indefinitely.

File scan/Rescan shared options:
  --notify-url NOTIFY_URL
                        An URL where a POST notification should be sent when
                        the scan finishes.
  --notify-changes-only
                        Used in conjunction with --notify-url. Indicates if
                        POST notifications should be sent only if the scan
                        results differ from the previous one.

Domain/IP shared verbose mode options, by default just show resolved IPs/Passive DNS:
  -wh, --whois          Whois data
  -wht, --whois-timestamp
                        Whois timestamp
  -pdns, --resolutions  Passive DNS resolves
  --asn                 ASN number
  -aso, --as-owner      AS details
  --country             Country
  --subdomains          Subdomains
  --domain-siblings     Domain siblings
  -cat, --categories    Categories
  -alc, --alexa-cat     Alexa category
  -alk, --alexa-rank    Alexa rank
  -opi, --opera-info    Opera info
  --drweb-cat           Dr.Web Category
  -adi, --alexa-domain-info
                        Just Domain option: Show Alexa domain info
  -wdi, --wot-domain-info
                        Just Domain option: Show WOT domain info
  -tm, --trendmicro     Just Domain option: Show TrendMicro category info
  -wt, --websense-threatseeker
                        Just Domain option: Show Websense ThreatSeeker
                        category
  -bd, --bitdefender    Just Domain option: Show BitDefender category
  -wd, --webutation-domain
                        Just Domain option: Show Webutation domain info
  -du, --detected-urls  Just Domain option: Show latest detected URLs
  --pcaps               Just Domain option: Show all pcaps hashes
  --samples             Will activate -dds -uds -dc -uc -drs -urs
  -dds, --detected-downloaded-samples
                        Domain/Ip options: Show latest detected files that
                        were downloaded from this ip
  -uds, --undetected-downloaded-samples
                        Domain/Ip options: Show latest undetected files that
                        were downloaded from this domain/ip
  -dc, --detected-communicated
                        Domain/Ip Show latest detected files that communicate
                        with this domain/ip
  -uc, --undetected-communicated
                        Domain/Ip Show latest undetected files that
                        communicate with this domain/ip
  -drs, --detected-referrer-samples
                        Undetected referrer samples
  -urs, --undetected-referrer-samples
                        Undetected referrer samples

Process emails:
  -pe, --parse-email    Parse email, can be string or file
  -esa SAVE_ATTACHMENT, --save-attachment SAVE_ATTACHMENT
                        Save email attachment, path where to store
  -peo, --parse-email-outlook
                        Parse outlook .msg, can be string or file

Behaviour options:
  -bh, --behaviour      The md5/sha1/sha256 hash of the file whose dynamic
                        behavioural report you want to retrieve. VirusTotal
                        runs a distributed setup of Cuckoo sandbox machines
                        that execute the files we receive. Execution is
                        attempted only once, upon first submission to
                        VirusTotal, and only Portable Executables under 10MB
                        in size are ran. The execution of files is a best
                        effort process, hence, there are no guarantees about a
                        report being generated for a given file in our
                        dataset. a file did indeed produce a behavioural
                        report, a summary of it can be obtained by using the
                        file scan lookup call providing the additional HTTP
                        POST parameter allinfo=1. The summary will appear
                        under the behaviour-v1 property of the additional_info
                        field in the JSON report.This API allows you to
                        retrieve the full JSON report of the files execution
                        as outputted by the Cuckoo JSON report encoder.
  -bn, --behavior-network
                        Show network activity
  -bp, --behavior-process
                        Show processes
  -bs, --behavior-summary
                        Show summary

Download options:
  -dl, --download       The md5/sha1/sha256 hash of the file you want to
                        download or txt file with .txt extension, with hashes,
                        or hash and type, one by line, for example: hash,pcap
                        or only hash. Will save with hash as name, can be
                        space separated list of hashes to download
  -nm NAME, --name NAME
                        Name with which file will saved when download it
  -dt DOWNLOAD_THREADS, --download-threads DOWNLOAD_THREADS
                        Number of simultaneous downloaders

Additional options:
  --pcap                The md5/sha1/sha256 hash of the file whose network
                        traffic dump you want to retrieve. Will save as
                        hash.pcap
  --clusters            A specific day for which we want to access the
                        clustering details, example: 2013-09-10
  --distribution-files  Timestamps are just integer numbers where higher
                        values mean more recent files. Both before and after
                        parameters are optional, if they are not provided the
                        oldest files in the queue are returned in timestamp
                        ascending order.
  --distribution-urls   Timestamps are just integer numbers where higher
                        values mean more recent urls. Both before and after
                        parameters are optional, if they are not provided the
                        oldest urls in the queue are returned in timestamp
                        ascending order.

Distribution options:
  --before BEFORE       File/Url option. Retrieve files/urls received before
                        the given timestamp, in timestamp descending order.
  --after AFTER         File/Url option. Retrieve files/urls received after
                        the given timestamp, in timestamp ascending order.
  --reports             Include the files' antivirus results in the response.
                        Possible values are 'true' or 'false' (default value
                        is 'false').
  --limit LIMIT         File/Url option. Retrieve limit file items at most
                        (default: 1000).
  --allinfo             will include the results for each particular URL scan
                        (in exactly the same format as the URL scan retrieving
                        API). If the parameter is not specified, each item
                        returned will only contain the scanned URL and its
                        detection ratio.

Rules management options:
  --rules               Manage VTI hunting rules, REQUIRED for rules management
  --list                List names/ids of Yara rules stored on VT
  --create FILE         Add a Yara rule to VT (File Name used as RuleName
  --update FILE         Update a Yara rule on VT (File Name used as RuleName
                        and must include RuleName
  --retro FILE          Submit Yara rule to VT RetroHunt (File Name used as
                        RuleName and must include RuleName
  --delete_rule DELETE_RULE
                        Delete a Yara rule from VT (By Name)
  --share               Shares rule with user
  --update_ruleset UPDATE_RULESET
                        Ruleset name to update
  --disable DISABLE     Disable a Yara rule from VT (By Name)
  --enable ENABLE       Enable a Yara rule from VT (By Name)

Mention of tool:

License

FOSSA Status

Huge thanks to jetbrains for opensource license!

About

VirusTotal Full api

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 99.9%
  • Dockerfile 0.1%