edu.ntnu.item.jt.system
Class Scanner

java.lang.Object
  extended by edu.ntnu.item.jt.system.Scanner
All Implemented Interfaces:
Runnable

public class Scanner
extends Object
implements Runnable

Used for managing scan logic. Uses a Guest OS and relevant info to perform scan logic and parse and return result.

Author:
Jøran Vagnby Lillesand

Field Summary
static int OPERATION_EXECUTE
          Indicates that the operation to be performed by the Scanner thread is a malware execution operation.
static int OPERATION_NONE
          Default value for the Scanner thread execution (no operation).
static int OPERATION_SCAN
          Indicates that the operation to be performed by the Scanner thread is a scan operation.
static int OPERATION_UPDATE
          Indicates that the operation to be performed by the Scanner thread is to set the virtual machine in ready state.
 
Constructor Summary
Scanner(GuestOS scanMachine, String name, String avEnginePath, String parameters, String remoteLogPath, LogFilter avScanFilter, AVUpdateInfoBean avUpdateBean, AVRealTimeScanBean realTimeScanBean)
          Constructor for scanner class.
 
Method Summary
 ScanResult executeMalwareSample(File malwareSample, boolean takeSnapshotBeforeExecution, boolean revertToSnapshotAfterExecution)
          Executes the supplied malware sample on the virtual machine associated with this scanner.
 String getName()
          Getter for the AVE name associated with this scanner object.
 GuestOS getScanMachine()
          Get the scan machine (guest OS) used by this scanner.
static void main(String[] args)
           
 void revertToSnapshot(boolean blocking)
          Load a snapshot and revert to it.
 void run()
          Overrides the Runnable run operation.
 ScanResult scan(File localSamplePath, boolean takeSnapshotBeforeScan, boolean revertToSnapshotAfterScan)
          Performs a scan operation on a remote machine.
 void startThreadedAVUpdate(AVUpdateThreadCallback callback)
          Start a AV engine update in a thread.
 void startThreadedMalwareExecution(File localSamplePath, boolean takeSnapshotBeforeScan, ScanThreadCallback callback)
          Creates and starts a thread which will execute a malware sample on the virtual machine associated with this Scanner object.
 void startThreadedScan(File localSamplePath, boolean takeSnapshotBeforeScan, ScanThreadCallback scanThreadCallback)
          Launch a separate thread that performs scan and reports back to the given callback object.
 String toString()
           
 AVUpdateResult updateAV()
          Attempt to update the AV engine for this scanner.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

OPERATION_SCAN

public static final int OPERATION_SCAN
Indicates that the operation to be performed by the Scanner thread is a scan operation.

See Also:
Constant Field Values

OPERATION_EXECUTE

public static final int OPERATION_EXECUTE
Indicates that the operation to be performed by the Scanner thread is a malware execution operation.

See Also:
Constant Field Values

OPERATION_UPDATE

public static final int OPERATION_UPDATE
Indicates that the operation to be performed by the Scanner thread is to set the virtual machine in ready state.

See Also:
Constant Field Values

OPERATION_NONE

public static final int OPERATION_NONE
Default value for the Scanner thread execution (no operation).

See Also:
Constant Field Values
Constructor Detail

Scanner

public Scanner(GuestOS scanMachine,
               String name,
               String avEnginePath,
               String parameters,
               String remoteLogPath,
               LogFilter avScanFilter,
               AVUpdateInfoBean avUpdateBean,
               AVRealTimeScanBean realTimeScanBean)
Constructor for scanner class.

Parameters:
scanMachine - the virtual machine to be used for scanning.
name - the name of the running antivirus engine.
avEnginePath - path to the antivirus executable on the remote machine.
parameters - required parameters to the antivirus executable on the remote machine (including location of database files, output directory for log files etc). Only relevant for explicit scans.
remoteLogPath - path to log files resulting from the scan operation.
avScanFilter - filter to be used for identifying the result from the log file of a scan operation.
avUpdateBean - bean containing the information related to performing automatic update of the virus definitions for this scanner. If automatic update is not supported, supply null.
realTimeScanBean - containing information needed to utilize the real time scanning capability of this scanner. If real time scanning is not supported, supply null.
Method Detail

run

public void run()
Overrides the Runnable run operation. Note that this runnable object should not be invoked directly, but using the appropriate functions (i.e. startThreadedScan()).

Specified by:
run in interface Runnable

toString

public String toString()
Overrides:
toString in class Object

startThreadedScan

public void startThreadedScan(File localSamplePath,
                              boolean takeSnapshotBeforeScan,
                              ScanThreadCallback scanThreadCallback)
Launch a separate thread that performs scan and reports back to the given callback object. More specifically, the function sets some instance variables which starts a thread which performs scan operations based on these variables.

Parameters:
localSamplePath - specifies the malware sample to be scanned.
takeSnapshotBeforeScan - specifies whether to take a snapshot before the scan is performed (resource demanding).
scanThreadCallback - specifies which object the thread should report back to upon finishing the scan.

updateAV

public AVUpdateResult updateAV()
Attempt to update the AV engine for this scanner.

Returns:
result description of the operation.

startThreadedAVUpdate

public void startThreadedAVUpdate(AVUpdateThreadCallback callback)
Start a AV engine update in a thread. Sets the needed parameters, and starts a thread for this object.

Parameters:
callback -
See Also:
updateAV()

scan

public ScanResult scan(File localSamplePath,
                       boolean takeSnapshotBeforeScan,
                       boolean revertToSnapshotAfterScan)
                throws InvalidFileException,
                       FileCopyException,
                       CreateSnapshotException,
                       FileExecutionException,
                       IOException,
                       DirectoryCreationException
Performs a scan operation on a remote machine. This involves the following operations:
  1. Optionally take snapshot of current virtual machine state
  2. Copy file from local machine to guest OS (virtual machine)
  3. Run antivirus engine with given parameters in guest OS with the copied file as input.
  4. Copy resulting scan operation log file from Guest OS to local machine
  5. Optionally reverting to snapshot after scan (recommended)
  6. Reading and filtering log
  7. Analyzing result
    • Note that this operation presumes that the Guest OS in use is powered on and logged in with a user of sufficient privilege. Also note that occurences of the string "$samplePath" in the parameters are replaced with the sample path on the remote machine (guest OS).

      Parameters:
      localSamplePath - full path to the local sample. Note that if local machine uses backslash as denominator, these must be escaped (i.e. c:\sample.exe must be supplied as c:\\sample.exe ).
      takeSnapshotBeforeScan - specifies whether to take a snapshot of the current machine state before performing scan.
      revertToSnapshotAfterScan - specifies whether to revert to snapshot after performing scan (recommended).
      Returns:
      object containing aggregated scan result information.
      Throws:
      InvalidFileException - if the local file sample can't be read.
      FileCopyException - if file copying failed (either of sample to guest os or scan log file from guest os).
      CreateSnapshotException - if snapshot creation failed.
      FileExecutionException - if file (antivirus engine executable) execution failed.
      IOException - if writing of log file to temp directory on local machine failed.
      DirectoryCreationException
      See Also:
      LogFilter, ScanResult

startThreadedMalwareExecution

public void startThreadedMalwareExecution(File localSamplePath,
                                          boolean takeSnapshotBeforeScan,
                                          ScanThreadCallback callback)
Creates and starts a thread which will execute a malware sample on the virtual machine associated with this Scanner object. The Thread will will execute untill completion and report back to the provided callback.

Parameters:
localSamplePath - reference to the malware sample.
takeSnapshotBeforeScan - boolean specifying whether a snapshot should be taken before executing the malware. This is only recommended if no clean snapshot is present on the virtual machine.
callback - object to be called when execution is finished (or timed out).
See Also:
scan(File, boolean, boolean)

executeMalwareSample

public ScanResult executeMalwareSample(File malwareSample,
                                       boolean takeSnapshotBeforeExecution,
                                       boolean revertToSnapshotAfterExecution)
                                throws IOException,
                                       InvalidFileException,
                                       CreateSnapshotException,
                                       FileCopyException,
                                       OperationNotSupportedException
Executes the supplied malware sample on the virtual machine associated with this scanner. The malware execution process constists of the following phases:

Parameters:
malwareSample - malware sample to be executed.
takeSnapshotBeforeExecution - boolean stating whether snapshot should be taken prior to copying and execution.
revertToSnapshotAfterExecution - boolean stating whether snapshot revertion should be performed after executing malware.
Returns:
result of the real time scan operation.
Throws:
IOException - if an error occured while processing the local copy of the log file created at the client (the local machine).
InvalidFileException - if the malware sample could not be read.
CreateSnapshotException - if the snapshot could not be created.
FileCopyException - if an exception occured while copying the malware sample to the
OperationNotSupportedException

getName

public String getName()
Getter for the AVE name associated with this scanner object.

Returns:
name of the AVE associated with this scanner object.

getScanMachine

public GuestOS getScanMachine()
Get the scan machine (guest OS) used by this scanner.

Returns:
guest OS used by the scanner.

revertToSnapshot

public void revertToSnapshot(boolean blocking)
                      throws NoSnapshotLoadedException,
                             RevertToSnapshotFailedException,
                             NoSnapshotAvailableException
Load a snapshot and revert to it.

Parameters:
blocking - specifies whether the call should be made in a blocking manner.
Throws:
NoSnapshotLoadedException
RevertToSnapshotFailedException
NoSnapshotAvailableException

main

public static void main(String[] args)
                 throws Exception
Parameters:
args -
Throws:
Exception