VirusTotal integration

ThreatLockDown detects malicious files through an integration with VirusTotal, a powerful platform aggregating multiple antivirus products and an online scanning engine. Combining this tool with our FIM module provides an effective way of inspecting monitored files for malicious content.

About VirusTotal

VirusTotal is an online service that analyzes files and URLs to detect viruses, worms, trojans, and other malicious content using antivirus engines and website scanners.

VirusTotal is a free service with numerous useful features. We highlight the following ones relevant to our purpose:

  • VirusTotal stores all the analyses it performs, allowing users to search for file hashes. By sending the hash to the VirusTotal engine, you can know if VirusTotal has already scanned that specific file, and you can analyze its report.

  • VirusTotal also provides an API that allows access to the information generated by VirusTotal without needing to utilize the HTML website interface. This API is subject to its Terms of Service, which we briefly discuss in the following section.

Terms of Service

VirusTotal's Terms of Service specify the two ways users may use the VirusTotal API:

Public API

This method uses a free API with many of VirusTotal's functionalities. However, it has some significant limitations, such as:

  • Request rate limitations, which you can find on VirusTotal’s website.

  • Low priority access for requests done by this API to the VirusTotal engine.

Private API

VirusTotal also provides a premium Private API where the request rates allowed are only limited by the user's Terms of Service. Apart from that, it provides high-priority access for requests, along with additional advantages.

To find out more about VirusTotal, its Terms of Service, and using its API, please visit their website.

How it works

This integration uses the VirusTotal API to detect malicious content within the files and directories monitored by the File Integrity Monitoring capability of Wazuh. This integration functions as described below:

  1. ThreatLockDown FIM looks for any file addition, change, or deletion on the monitored folders. This module has the hash of these files stored and triggers alerts when it detects any changes.

  2. If enabled, ThreatLockDown triggers the VirusTotal integration when an FIM alert occurs. From this alert, the integration extracts the hash field of the file.

  3. The integration then makes an HTTP POST request to the VirusTotal database using the VirusTotal API. This call sends the extracted file hash to compare it with the information in the VirusTotal database.

  4. The integration receives a JSON response, which is the result of the request. The response triggers one of the following ThreatLockDown alerts:

    • Error: Check credentials.

    • Error: Public API request rate limit reached.

    • Alert: No records in VirusTotal database.

    • Alert: No positives found.

    • Alert: X engines detected this file. X is the number of antivirus engines.

ThreatLockDown logs the triggered alert in the /var/ossec/logs/integrations.log file and stores it in the /var/ossec/logs/alerts/alerts.log file with all other alerts.

Find examples of these alerts in the VirusTotal integration alerts section below.

Use case: Scanning a file

Getting started

Follow the instructions from Integration with external APIs to enable the Integrator module and configure the VirusTotal integration.

Below is an example of settings you must add to the /var/ossec/etc/ossec.conf file on the ThreatLockDown server:

<integration>
  <name>virustotal</name>
  <api_key>API_KEY</api_key> <!-- Replace with your VirusTotal API key -->
  <group>syscheck</group>
  <alert_format>json</alert_format>
</integration>

Using FIM to monitor a directory

For this use case, we show how to monitor the folder /media/user/software on Linux endpoints.

  1. Add the following to the <syscheck> section of the configuration file. You can configure these options in the ThreatLockDown server and the ThreatLockDown agent /var/ossec/etc/ossec.conf file. You can also configure this capability remotely using the centralized configuration options provided by the agent.conf file. The list of all FIM configuration options is available in the syscheck section of the documentation. In our example, we configured the options below on the ThreatLockDown server.

    <syscheck>
      <directories check_all="yes" realtime="yes">/media/user/software</directories>
    </syscheck>
    
  2. After applying the configuration, you must restart the ThreatLockDown manager:

    # systemctl restart wazuh-manager
    

After restarting, FIM applies the new configuration and monitors the folder you specify in near real time.

Test the configuration

Now, you can download a malicious file on the endpoint in the monitored folder.

Warning

Download the Eicar file here for testing purposes only. We recommend testing in a sandbox, not in a production environment.

$ sudo curl -Lo /media/user/software/suspicious-file.exe https://secure.eicar.org/eicar.com

When FIM detects a new file in the monitored directory, ThreatLockDown generates the alert below:

{
   "timestamp":"2022-11-17T19:17:42.694+0200",
   "rule":{
      "level":5,
      "description":"File added to the system.",
      "id":"554",
      "firedtimes":2,
      "mail":false,
      "groups":[
         "ossec",
         "syscheck",
         "syscheck_entry_added",
         "syscheck_file"
      ],
      "pci_dss":[
         "11.5"
      ],
      "gpg13":[
         "4.11"
      ],
      "gdpr":[
         "II_5.1.f"
      ],
      "hipaa":[
         "164.312.c.1",
         "164.312.c.2"
      ],
      "nist_800_53":[
         "SI.7"
      ],
      "tsc":[
         "PI1.4",
         "PI1.5",
         "CC6.1",
         "CC6.8",
         "CC7.2",
         "CC7.3"
      ]
   },
   "agent":{
      "id":"010",
      "name":"Ubuntu",
      "ip":"10.0.2.15"
   },
   "manager":{
      "name":"localhost.localdomain"
   },
   "id":"1668705462.50453",
   "full_log":"File '/media/user/software/suspicious-file.exe' added\nMode: realtime\n",
   "syscheck":{
      "path":"/media/user/software/suspicious-file.exe",
      "mode":"realtime",
      "size_after":"0",
      "perm_after":"rw-r--r--",
      "uid_after":"0",
      "gid_after":"0",
      "md5_after":"d41d8cd98f00b204e9800998ecf8427e",
      "sha1_after":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "sha256_after":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "uname_after":"root",
      "gname_after":"root",
      "mtime_after":"2022-11-17T19:17:42",
      "inode_after":1704505,
      "event":"added"
   },
   "decoder":{
      "name":"syscheck_new_entry"
   },
   "location":"syscheck"
}

From this alert, the integrator module extracts the hash fields, and sends the request to VirusTotal for comparison.

Note

Find more information about how to use File Integrity Monitoring for different types of scans in its documentation.

VirusTotal integration alerts

When the integrator module sends a request to VirusTotal, as noted above, the response triggers an alert depending on the situation. Below are examples and explanations of these alerts:

The API credentials are incorrect:

{
   "timestamp":"2022-11-17T19:17:43.637+0200",
   "rule":{
      "level":3,
      "description":"VirusTotal: Error: Check credentials",
      "id":"87102",
      "firedtimes":3,
      "mail":false,
      "groups":[
         "virustotal"
      ],
      "gdpr":[
         "IV_35.7.d",
         "IV_32.2"
      ]
   },
   "agent":{
      "id":"000",
      "name":"localhost.localdomain"
   },
   "manager":{
      "name":"localhost.localdomain"
   },
   "id":"1668705463.51155",
   "decoder":{
      "name":"json"
   },
   "data":{
      "virustotal":{
         "error":"403",
         "description":"Error: Check credentials"
      },
      "integration":"virustotal"
   },
   "location":"virustotal"
}

This error means that the API key set in the configuration is invalid.

The API has reached the set rate limit:

{
   "timestamp":"2022-11-17T19:22:13.236+0200",
   "rule":{
      "level":3,
      "description":"VirusTotal: Error: Public API request rate limit reached",
      "id":"87101",
      "firedtimes":2,
      "mail":false,
      "groups":[
         "virustotal"
      ]
   },
   "agent":{
      "id":"000",
      "name":"localhost.localdomain"
   },
   "manager":{
      "name":"localhost.localdomain"
   },
   "id":"1668705733.90632",
   "decoder":{
      "name":"json"
   },
   "data":{
      "virustotal":{
         "error":"204",
         "description":"Error: Public API request rate limit reached"
      },
      "integration":"virustotal"
   },
   "location":"virustotal"
}

VirusTotal triggers this error when a user has reached the request rate limit. See the Terms of Service for more information on this limitation.

While the two previous alerts represent errors that might occur, the following are samples of alerts returned from a successful request:

Alert created when there are no records of threat in the VirusTotal database:

{
   "timestamp":"2022-11-17T19:22:07.974+0200",
   "rule":{
      "level":3,
      "description":"VirusTotal: Alert - /media/user/software/suspicious-file10.exe - No positives found",
      "id":"87104",
      "firedtimes":4,
      "mail":false,
      "groups":[
         "virustotal"
      ]
   },
   "agent":{
      "id":"010",
      "name":"Ubuntu",
      "ip":"10.0.2.15"
   },
   "manager":{
      "name":"localhost.localdomain"
   },
   "id":"1668705727.84464",
   "decoder":{
      "name":"json"
   },
   "data":{
      "virustotal":{
         "found":"1",
         "malicious":"0",
         "source":{
            "alert_id":"1668705721.82254",
            "file":"/media/user/software/suspicious-file10.exe",
            "md5":"d41d8cd98f00b204e9800998ecf8427e",
            "sha1":"da39a3ee5e6b4b0d3255bfef95601890afd80709"
         },
         "sha1":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
         "scan_date":"2022-11-17 17:19:48",
         "positives":"0",
         "total":"60",
         "permalink":"https://www.virustotal.com/gui/file/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/detection/f-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855-1668705588"
      },
      "integration":"virustotal"
   },
   "location":"virustotal"
}

Alert created when the scanned file was found and identified by the database as malware:

{
   "timestamp":"2022-11-17T19:30:25.085+0200",
   "rule":{
      "level":12,
      "description":"VirusTotal: Alert - /media/user/software/eicar.com - 66 engines detected this file",
      "id":"87105",
      "mitre":{
         "id":[
            "T1203"
         ],
         "tactic":[
            "Execution"
         ],
         "technique":[
            "Exploitation for Client Execution"
         ]
      },
      "firedtimes":1,
      "mail":true,
      "groups":[
         "virustotal"
      ],
      "pci_dss":[
         "10.6.1",
         "11.4"
      ],
      "gdpr":[
         "IV_35.7.d"
      ]
   },
   "agent":{
      "id":"010",
      "name":"Ubuntu",
      "ip":"10.0.2.15"
   },
   "manager":{
      "name":"localhost.localdomain"
   },
   "id":"1668706225.104492",
   "decoder":{
      "name":"json"
   },
   "data":{
      "virustotal":{
         "found":"1",
         "malicious":"1",
         "source":{
            "alert_id":"1668706222.103798",
            "file":"/media/user/software/eicar.com",
            "md5":"44d88612fea8a8f36de82e1278abb02f",
            "sha1":"3395856ce81f2b7382dee72602f798b642f14140"
         },
         "sha1":"3395856ce81f2b7382dee72602f798b642f14140",
         "scan_date":"2022-11-17 17:15:04",
         "positives":"66",
         "total":"68",
         "permalink":"https://www.virustotal.com/gui/file/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f/detection/f-275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f-1668705304"
      },
      "integration":"virustotal"
   },
   "location":"virustotal"
}