Getting Started with APIs


Overview

Criminals in the world of cyber security are constantly adopting new strategies and tools for their advantage. Therefore, new tools and protective measures against malicious content are being developed and will continue to do so. There are various tools as well which the good guys develop and make it available for the world to use and there is no harm in integrating them into your existing configuration than to start over.

VirusTotal is widely known for analysing suspicious files and URLs to detect types of malware.When used with DNIF, it is a major contributor of application security.

In the following sections, we shall discuss, as to how one can configure and use one of the pre-built Apps, for example VirusTotal within the DNIF platform.

Steps to configure

Users need to follow the below mentioned steps in order to setup their deployment with required configurations:

  1. Login to your Data Store, Correlator, and A10 containers: You can refer our help document on connecting to your DNIF instance here.

  2. Change directory path to /dnif/<Deployment-key/

  3. Create a folder with name lookup_plugins

  4. Navigate to the folder /lookup_plugins/

  5. Execute the command, git clone https://github.com/dnif/lookup-virustotal.git virustotal to fetch the latest repo for VirusTotal API from Github.

  6. Replace the tag: <Add_your_apik_key_here> with your VirusTotal API key, within the file /dnif/<Deployment-key/lookup_plugins/virustotal/dnifconfig.yml

Using Lookup command

The lookup command enables you to search hashes, domains, URLs and IP information from VirusTotal. Few examples,

Retrieve URL scan reports

Users can easily scan for suspicious URLs, by using:

Query
_fetch $Url from threatsample limit 1
>>_lookup virustotal get_url_report $Url

Where:

  • threatsample is an event store, which comprises all the log data coming in from a Web Server.
  • $Url is the field which comprises URLs.

We shall limit the output to only 1 URL being scanned, for simplicity and ease of Understanding.

Validate URL for known bad reputation from VIRUSTOTAL

The Lookup call returns output in the following structure for available data:

Fields Description
$VTURL URL being queried
$VTPermalink Permalink of report stored in VirusTotal
$VTPositive List of scans returning positive detection
$VTNegative List of scans returning negative detection
$VTPositives Count of positive detection
$VTResponseCode If the queried url is present in VirusTotal database it returns 1 ,if absent returns 0 and if the requested item is still queued for analysis it will be -2
$VTTotal Count of positive and negative detections
$VTSystemTstamp Scan Date

Retrieve Domain reports

Users can easily scan for suspicious domains which many a times provide a crucial clue regarding suspected connect back cases for Botnets:

Query
_fetch $Domain from threatsample limit 1
>>_lookup virustotal get_domain_report $Domain

Where:

  • threatsample is an event store, which comprises all the log data coming in from a Web Server.
  • $Domain is the field which comprises a list domain names.
Validate domain for known bad reputation with VIRUSTOTAL

The Lookup call returns output in the following structure for available data

Fields Description
$VTURL List of URL processed by VirusTotal and hosted on the domain
$VTCategories Domain category assigned by VirusTotal
$VTWebsenseThreatSeekercategory Domain category assigned by Websense Threat Seeker
$VTDomainList List of domains that lie on the same DNS hierarchical level
$VTSubDomainList List of sub-domains
$VTSiteClass Site-Classification assigned by VirusTotal
$VTWebutationVerdict Webutation Domain verdict
$VTWebutationSafetyScore Webutationx Domain score
$VTForcepointThreatSeekerCategory Domain category assigned by Forcepoint Threat Seeker
$VTPassiveDNSReplication The queried domain has been seen to resolve the list of ip address
$VTResponseCode If the queried domain is present in VirusTotal database it returns 1 ,if absent returns 0 and if the requested item is still queued for analysis it will be -2
$VTWHOIS Registered domain owners and meta-data from WHOIS

Retrieve IP address reports

IP Addresses can provide a vital clue in identifying malicious sources with their ISP details:

Query
_fetch $SrcIP from threatsample limit 1
>>_lookup virustotal get_ip_report $SrcIP

Where:

  • threatsample is an event store, which comprises all the log data coming in from a Web Server.
  • $SrcIP is the field which comprises of a list IP addresses accessed.
Validate IP Address for known bad activity with VIRUSTOTAL

The Lookup call returns output in the following structure for available data:

Fields Description
$VTOwner Autonomous system owner detail
$VTURL List of latest url hosted on the queried ip address
$VTPassiveDNSReplication Domain resolved to the queried ip address
$VTASN Autonomous system number
$VTCN Country
$VTCommunicatingSamples SHA256 of files that communicate with the queried ip address
$VTDownloadedSamples SHA256 of files that downloaded from the queried ip address
$VTResponseCode If the queried domain is present in VirusTotal database it returns 1 ,if absent returns 0 and if the submitted IP address is invalid -1.

Retrieve file scan reports by MD5/SHA-1/SHA-256 hash

Monitoring file hashes is one of the integral aspects to ascertain the integrity of a required file. Sometimes, the trail of such hashes within the network, serves as a good starting for investigations for Cyber Security or Forensic Analysts.

Query
_fetch $Filehash from threatsample limit 1
>>_lookup virustotal get_filehash_report $Filehash

Where:

  • threatsample is an event store, which comprises all the log data from a UTM.
  • $Filehash is the field which comprises all the file hashes encountered.
Validate file hashes for to identify malicious files

The Lookup call returns output in the following structure for available data:

Fields Description
$VTmd5 Corresponding MD5 hash of quried hash present in VirusTotal DB
$VTsha1 Corresponding SHA-1 hash of quried hash present in VirusTotal DB
$VTsha256 Corresponding SHA-256 hash of quried hash present in VirusTotal DB
$VTPermalink Permalink of report stored in VirusTotal
$VTPositive List of scans returning positive detection
$VTNegative List of scans returning negative detection
$VTPositives Count of positive detection
$VTResponseCode If the queried url is present in VirusTotal database it returns 1 ,if absent returns 0 and if the requested item is still queued for analysis it will be -2
$VTTotal Count of positive and negative detections
$VTSystemTstamp Scan Date