File Coverage

blib/lib/WebService/VirusTotal.pm

Criterion	Covered	Total	%
statement	65	299	21.7
branch	10	174	5.7
condition	0	42	0.0
subroutine	17	33	51.5
pod	14	16	87.5
total	106	564	18.7

#
# VirusTotal
#
# This package was insipred by Chistopher Frenz's perl script at:
#    http://perlgems.blogspot.com.es/2012/05/using-virustotal-api-v20.html
#
# Package is Copyright (C) 2013, Michelle Sullivan (SORBS) , and Proofpoint Inc.
#

package WebService::VirusTotal;

use 5.006;
use strict;
use warnings;
use Carp;

use LWP::UserAgent;
use JSON;

use Digest::SHA qw(sha1_hex sha256_hex);
use Digest::MD5 qw(md5_hex);
use List::Util qw(first);

use base qw(Exporter);

our $ID = q$Id: VirusTotal.pm 3165 2014-01-07 12:31:37Z michelle $;
our $VERSION = sprintf("1.0.%d", q$Revision 3165$ =~ /(\d+)/g);
my $TESTSTRING = 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*';
my $INTERNALAGENT = sprintf("%s-MIS/0.%d", $ID =~ /Id:\s+(\w+)\.pm\s+(\d+)\s+/);

#warn("[" . localtime(time()) . "] WebService::VirusTotal Revision: $VERSION (Agent: $INTERNALAGENT)\n");

sub new
{
        my $class = shift;
        my $this = {};
        my %arg = @_;

        $this->{DEBUG} = (exists $arg{debug} ? $arg{debug} : 0);
	$this->{FNLEN} = 64;

	my %scanhash = ();

	$this->{'ua'} = undef;
	$this->{'conn'} = undef;
	$this->{'scanhash'} = \%scanhash;

        bless ($this, $class);

        return $this;
}

sub init
{
	my $self = shift;
	$self->apiagent();
	$self->scanapi();
	$self->reportapi();
	$self->apikey();
}


sub debug
{
	my $self = shift;
	if (@_) {$self->{DEBUG} = $_[0]};
	return $self->{DEBUG};
}

sub conn_proxy
{
	my $self = shift;
	if (@_) {$self->{PROXY} = $_[0]};
	return $self->{PROXY};
}

sub apiagent
{
	my $self = shift;
	if (@_) {$self->{AGENTSTRING} = $_[0]};
	$self->{AGENTSTRING} = $INTERNALAGENT if (!defined $self->{AGENTSTRING});
	return $self->{AGENTSTRING};
}

sub conn_cache
{
	my $self = shift;
	if (@_) {$self->{CONNCACHE} = $_[0]};
	$self->{CONNCACHE} = 0 if (!defined $self->{CONNCACHE});
	return $self->{CONNCACHE};
}

sub allowlong
{
	my $self = shift;
	if (@_)
	{
		if ($_[0])
		{
			$self->{FNLEN} = 256;
		} else {
			$self->{FNLEN} = 64;
		}
	}
	return $self->{FNLEN};
}

sub cache
{
	my $self = shift;
	if (@_) {$self->{CACHE} = $_[0]};
	# if cache use is true, but the cache is not defined then init it
	if (!defined $self->{CACHE} and $self->conn_cache())
	{
		$self->{CACHE} = $self->init_cache();
	}
	# return the cache object, this could be undef if caching is not defined.
	return $self->{CACHE};
}

sub init_cache
{
	use LWP::ConnCache;

	my $self = shift;
	return $self->{CACHE} if defined $self->{CACHE};

	my $cache = LWP::ConnCache->new;
	$cache->total_capacity($self->cache_limit());
	return $cache;
}

sub cache_check
{
	my $self = shift;

	# if connection cache is not being used return true regardless
	return 1 if (!$self->conn_cache());

	# if the cache is not initialised return an error
	if (!defined $self->cache())
	{
		carp("Connection Cache is enabled but not intialised!");
		return undef;
	}

	# Prune dead entries
	$self->cache->prune();
	return 1;
}

sub cache_limit
{
	my $self = shift;
	if (@_) {$self->{CACHELIMIT} = $_[0]};
	$self->{CACHELIMIT} = 1 if (!defined $self->{CACHELIMIT});
	return $self->{CACHELIMIT};
}

sub reportapi
{
	my $self = shift;
	if (@_) {$self->{VTREPORTAPI} = $_[0]};
	$self->{VTREPORTAPI} = "https://www.virustotal.com/vtapi/v2/file/report" if (!defined $self->{VTPREPORTAPI});
	return $self->{VTREPORTAPI};
}

sub scanapi
{
	my $self = shift;
	if (@_) {$self->{VTSCANAPI} = $_[0]};
	$self->{VTSCANAPI} = "https://www.virustotal.com/vtapi/v2/file/scan" if (!defined $self->{VTPSCANAPI});
	return $self->{VTSCANAPI};
}

sub apikey
{
	my $self = shift;
	if (@_) {$self->{APIKEY} = $_[0]};
	$self->{APIKEY} = undef if (!defined $self->{APIKEY});
	return $self->{APIKEY};
}

sub timeout
{
	my $self = shift;
	if (@_) { $self->{CONNTIMEOUT} = $_[0] };
	$self->{CONNTIMEOUT} = 30 if (!defined $self->{CONNTIMEOUT});
	return $self->{CONNTIMEOUT};
}

# Public method for accessing VirusTotal
sub scan
{
	my $self = shift;
	my $file = shift;
	my ($filename, $infected, $description) = (undef, undef, undef);
	my $tmpfile = 0;
	my $result = 0;
	carp("Entered scan()...") if $self->debug();
	if (length($file) > $self->allowlong() && $file !~ /\//)
	{
		$tmpfile++;
	} else {
		if ( -r $file && $file !~ /\.\./ )
		{
			# this is a filename and I can read it (and does not contain '..')
			$filename = $file;
		} else {
			$tmpfile++;
		}
	}
	if ($tmpfile)
	{
		$filename = "/tmp/nofilename-$$.tmp";
		open FILE, ">$filename";
		while (<$file>)
		{
			print FILE;
		}
		close FILE;
	}

	carp("Filename for scanning is: $filename") if $self->debug();
	if ($self->_connect())
	{
		carp("Connected to VT, scanning...") if $self->debug();
		# We are connected we can proceed....
		#
		open FILE, "<$filename";
		my $scankey = sha256_hex();
		close FILE;

		#
		# Check the internal checksums against the hash, if found we don't need to submit to VT
		# If not found we need to call the private method _submit() and actually submit it
		# If it is found we can call the private method _result() to get any results.
		if (exists $self->{'scanhash'}->{$scankey})
		{
			carp("Found a hash.. checking for a result..") if $self->debug();
			($infected, $description) = $self->_result($scankey);
			# return any result or undef if we have to wait for a result...
			if (!defined $infected)
			{
				# an error occurred, could be that the file has not completed scanning
				$description = "Please try later..";
			}
		} else {
			carp("Did not find a hash.. submitting for a scan...") if $self->debug();
			# scan key not found, so we need to submit it...
			$result = $self->_submit($scankey, $filename);
			if (defined $result)
			{
				# scan submission was successful, pause 15 seconds then check to see if there is a response
				if ($result ne 1)
				{
					carp("Scan returned something other than done so pausing 15 seconds...") if $self->debug();
					sleep 15;
				}
				($infected, $description) = $self->_result($scankey);
				# return any result or undef if we have to wait for a result...
				if (!defined $infected)
				{
					carp("Result check was an error, tempfailing...") if $self->debug();
					# an error occurred, could be that the file has not completed scanning
					$description = "Please try later..";
				}
			}
		}
	} else {
		# Not connected (and unable to connect) so return an error
		carp("Not connected to VirusTotal API, check your configuration!");
		$infected = undef;
		$description = "Not connected to VirusTotal API, check your configuration!";
	}
	unlink($filename) if ($tmpfile);
	return ($infected, $description);
}

# Private method to test the connection state and if not connected/tested to try a connection.
sub _connect
{
	my $self = shift;
	if (!ref $self or !ref $self->{'scanhash'})
	{
		croak("You cannot call _connect() before calling new() (and you shouldn't do it!)");
	}

	if (defined $self->{'valid_conn'} && $self->{'valid_conn'} && defined $self->{'ua'})
	{
		# We have previously connected
		return $self->{'valid_conn'};
	}

	if (!defined $self->{'valid_conn'})
	{
		# No valid connection tried, so setup LWP
		if (!defined $self->{'ua'})
		{
			$self->{'ua'} = LWP::UserAgent->new(
				ssl_opts => { verify_hostname => 1 },
				agent => $self->apiagent(),
				timeout => $self->timeout(),
				conn_cache => $self->cache(),
			);
			if (defined $self->conn_proxy())
			{
				$self->{'ua'}->proxy('https', $self->conn_proxy());
			}
		}
		$self->{'valid_conn'} = 0;
	}
	# A connection was previously tried and failed, or this is a new connection
	if (!$self->{'valid_conn'} and $self->{'last_conn_check'} < (time() - 300))
	{
		# test the connection by sending the EICAR string..
		carp("Connecting to " . $self->reportapi() . " for the EICAR test..") if $self->debug();
		my $response = $self->{'ua'}->post( $self->reportapi(),
			Content_Type => 'multipart/form-data',
			Content => [
					'apikey' => $self->apikey(),
					'resource' => sha256_hex($TESTSTRING),
				],
			);
		if (!$response->is_success)
		{
			my $a = ( $response->status_line =~ /403 Forbidden/ ) ? " (Have you set your API key?)" : "";
			carp("Unable to connect to VirusTotal using " . $self->scanapi() . " error: " . $response->status_line . "$a\n");
		} else {
			my $results=$response->content;
			carp("Parsing test response: $results") if $self->debug();
			# pulls the sha256 value out of the JSON response
			# Note: there are many other values that could also be pulled out
			my $json = JSON->new->allow_nonref;
			my ($decjson, $sha, $respcode) = (undef, undef, undef);
			eval {
				$decjson = $json->decode($results);
			};
			if (defined $decjson)
			{
				# if json->decode() fails it will call croak, so we catch it and display the returned text
				$sha = $decjson->{"sha256"};
				$respcode = $decjson->{"response_code"};
				if (defined $sha && $sha ne "")
				{
					# we were able to submit successfully so we can set valid_conn to true
					$self->{'scanhash'}->{'test'}->{'key'} = $sha;
					$self->{'scanhash'}->{'test'}->{'submitted'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
					$self->{'scanhash'}->{'test'}->{'last_checked'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
					$self->{'scanhash'}->{'test'}->{'infected'} = $decjson->{"positives"};
					$self->{'scanhash'}->{'test'}->{'result'} = first { $_->{detected} } values %{ $decjson->{scans} };
					$self->{'valid_conn'} = 1;
					carp("Validated connection...") if $self->debug();
				} else {
					carp("Unable to parse test, VirusTotal responded with: $results");
				}
			}
		}
		$self->{'last_conn_check'} = time();
	}
	return $self->{'valid_conn'};
}

# Private method, will send the request to VirusTotal
sub _submit
{
	#Code to submit a file to Virus Total
	my $self = shift;
	my $res = undef;
	carp("Entered _submit()") if $self->debug();
	croak ("You can't call this directly! Use the scan() method!") if (!ref $self);
	croak ("You cannot call _submit() before calling new() (and you shouldn't do it!") if (!ref $self->{'scanhash'});

	if (!defined $self->{'valid_conn'} && !$self->{'valid_conn'})
	{
		carp("Not connected to VirusTotal, please check your connection before calling _submit()!");
		return $res;
	}

	my $scankey = shift; # This is our internally generated scan key to be used to lookup the result key
	my $file = shift; # This is the file name and location of the file to check

START:	carp("Sending file ($file)..") if $self->debug();
	my $response = $self->{'ua'}->post(
		$self->scanapi,
    		Content_Type => 'multipart/form-data',
    		Content => [
			'apikey' => $self->apikey(),
    			'file' => [$file]
		]
  	);
	if (!$response->is_success)
	{
		carp("Unable to post to '" . $self->scanapi() . "' error: " . $response->status_line . "\n");
		return $res;
	}
	my $results=$response->content;

	carp("Got response: $results") if $self->debug();
	#pulls the sha256 value out of the JSON response
	#Note: there are many other values that could also be pulled out
	my $json = JSON->new->allow_nonref;
	my ($decjson, $sha, $respcode) = (undef, undef, undef);
	eval {
		$decjson = $json->decode($results);
	};
	if (defined $decjson)
	{
		# if json->decode() fails it will call croak, so we catch it and display the returned text
		$sha = $decjson->{"sha256"};
		$respcode = $decjson->{"response_code"};
		if (defined $respcode)
		{
			carp("Got response code $respcode") if $self->debug();
			if ($respcode eq "1")
			{
				# we were able to submit successfully and we got a report embedded
				$self->{'scanhash'}->{$scankey}->{'key'} = $sha;
				$self->{'scanhash'}->{$scankey}->{'submitted'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
				$self->{'scanhash'}->{$scankey}->{'last_checked'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
				$self->{'scanhash'}->{$scankey}->{'infected'} = $decjson->{"positives"};
				$self->{'scanhash'}->{$scankey}->{'result'} = first { $_->{detected} } values %{ $decjson->{scans} };
				$self->{'valid_conn'} = 1;
			} elsif ($respcode eq "-2" or $respcode eq "0") {
				# we were able to submit successfully and we got a response indicating queued
				$self->{'scanhash'}->{$scankey}->{'key'} = $sha;
				$self->{'scanhash'}->{$scankey}->{'submitted'} = time();
				$self->{'scanhash'}->{$scankey}->{'last_checked'} = 0;
				$self->{'scanhash'}->{$scankey}->{'infected'} = undef;
				$self->{'scanhash'}->{$scankey}->{'result'} = $decjson->{"verbose_msg"};
				$self->{'valid_conn'} = 1;
			} elsif ($respcode eq "-1") {
				carp("Transient Error occured, restarting...\n");
				carp("Got response code -1 (so restarting..)") if $self->debug();
				goto START;
			} else {
				carp("Got response code $respcode (" . $decjson->{"verbose_msg"} . ")") if $self->debug();
				$self->{'scanhash'}->{$scankey}->{'result'} = $decjson->{"verbose_msg"};
			}
		} else {
			carp("Unable to parse $scankey, VirusTotal responded with: $results");
		}
	} else {
		carp("Unable to parse $scankey, VirusTotal responded with: $results");
		carp("JSON decoder returned: $decjson [$@]");
	}
	return $respcode;
}

# Private method, will get the request from VirusTotal
sub _result
{
	#Code to retrieve a result from VirusTotal
	my $self = shift;
	carp("Entered _result()") if $self->debug();
	croak ("You can't call this directly! Use the scan() method!") if (!ref $self);
	croak ("You cannot call _result() before calling new() (and you shouldn't do it!") if (!ref $self->{'scanhash'});

	my $scankey = shift; # This is our internally generated scan key to be used to lookup the result key

	if (!defined $self->{'valid_conn'} && !$self->{'valid_conn'})
	{
		carp("Not connected to VirusTotal, please check your connection before calling _result()!");
		return undef;
	}

	if (!exists $self->{'scanhash'}->{$scankey} || !defined $self->{'scanhash'}->{$scankey}->{'key'})
	{
		carp("Attempted to retrieve a result for a key that doesn't exist!");
		return undef;
	}

	# Check to see if we checked in the last 5 minutes.  If we did return the same result.
	unless ($self->{'scanhash'}->{$scankey}->{'last_checked'} && $self->{'scanhash'}->{$scankey}->{'last_checked'} > (time() - 300))
	{
		# Code to retrieve the results that pertain to a submitted file by hash value
		# FIXME: Original code had neither content_type or content .. are they needed (probably not, but should we include) for readability?
RESTART:	carp("Sending filehash ($scankey)..") if $self->debug();
		my $response = $self->{'ua'}->post(
			$self->reportapi(),
			Content_Type => 'multipart/form-data',
			Content => [
				'apikey' => $self->apikey(),
				'resource' => $scankey
			]
		);

		if (!$response->is_success)
		{
			carp("Unable to post to '" . $self->reportapi() . "' error: " . $response->status_line . "\n");
			return (undef, undef);
		}
		my $results=$response->content;
		carp("Got response: $results") if $self->debug();

		# pulls the sha256 value out of the JSON response
		# Note: there are many other values that could also be pulled out
		my $json = JSON->new->allow_nonref;
		my ($decjson, $sha, $respcode) = (undef, undef, undef);
		eval {
			$decjson = $json->decode($results);
		};
		if (defined $decjson)
		{
			# if json->decode() fails it will call croak, so we catch it and display the returned text
			$sha = $decjson->{"sha256"};
			$respcode = $decjson->{"response_code"};
			if (defined $respcode)
			{
				if ($respcode eq "1")
				{
					# we were able to submit successfully so we can set valid_conn to true
					$self->{'scanhash'}->{$scankey}->{'key'} = $sha;
					$self->{'scanhash'}->{$scankey}->{'submitted'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
					$self->{'scanhash'}->{$scankey}->{'last_checked'} = sprintf("%d", $decjson->{"scanid"} =~ /^[1234567890abcdef]+-(\d+)$/);
					$self->{'scanhash'}->{$scankey}->{'infected'} = $decjson->{"positives"};
					$self->{'scanhash'}->{$scankey}->{'result'} = first { $_->{detected} } values %{ $decjson->{scans} };
					$self->{'valid_conn'} = 1;
					carp("Got response code $respcode") if $self->debug();
				} elsif ($respcode eq "-2" or $respcode eq "0") {
					# we were able to submit successfully and we got a response indicating queued
					$self->{'scanhash'}->{$scankey}->{'key'} = $sha;
					$self->{'scanhash'}->{$scankey}->{'submitted'} = time();
					$self->{'scanhash'}->{$scankey}->{'last_checked'} = 0;
					$self->{'scanhash'}->{$scankey}->{'infected'} = undef;
					$self->{'scanhash'}->{$scankey}->{'result'} = $decjson->{"verbose_msg"};
					$self->{'valid_conn'} = 1;
					carp("Got response code $respcode") if $self->debug();
				} elsif ($respcode eq "-1") {
					carp("Transient Error occured, restarting...\n");
					carp("Got response code $respcode (transient error, restarting)") if $self->debug();
					goto RESTART;
				} else {
					carp("Got unknown response code $respcode") if $self->debug();
					$self->{'scanhash'}->{$scankey}->{'result'} = $decjson->{"verbose_msg"};
				}
			} else {
				carp("Unable to parse $scankey, VirusTotal responded with: $results");
			}
		} else {
			carp("Unable to parse $scankey, VirusTotal responded with: $results");
		}
	}
	return ($self->{'scanhash'}->{$scankey}->{'infected'}, $self->{'scanhash'}->{$scankey}->{'result'}->{'result'});
}

1;

__END__