GetInfectionState

Retrieve the device infection state by conditions (including processes, connections, and any repeated threats)

Syntax

Method ID

#define WAAPI_MID_GET_INFECTION_STATE 80009

JSON Input Structure

{
  "input": {
    "method": 80009,
    "process_scan": boolean,
    "process_scan_options": {
      "scan_level": string,
      "force_rescan": boolean,
      "no_file_upload": boolean,
      "no_sample_sharing": boolean
    },
    "network_connection_scan": boolean,
    "repeated_threat_detection": boolean,
    "repeated_threat_detection_options": {
      "monitor_days": number,
      "repeated_tolerance": number
    }
  }
}

Input Properties

Parameter	Type	Description
`process_scan`	boolean	If true, an attempt will be made to scan processes using configuration from process_scan_options. If false, infected process information will not be returned. Default value is 'true'
`process_scan_options`	object	Will contain a key for each scanning option
`process_scan_options.scan_level`	string	Indicates whether function should scan the given process and all the loaded dll and exe by each process by using value 'deep' or the given processes only by using value 'quick'. The default scan_level value is 'quick'
`process_scan_options.force_rescan`	boolean	If true, will do a force rescan even if we have cached result. Default value is 'false'
`process_scan_options.no_file_upload`	boolean	If true, the scanned file will only be scanned using the hash lookup, and will not be uploaded to Metadefender or target Metadefender server for scanning. Default value is 'false'
`process_scan_options.no_sample_sharing`	boolean	If no_file_upload is set to true, then this value is ignored. Otherwise, if this value is set to true - the file will be saved on Metadefender Server, with intention of sharing samples with antimalware vendors for research. Default value is 'false'
`network_connection_scan`	boolean	If true, will do a scan on all connected addresses and return a list of blacklisted_connections that may indicate potential threats. Default value is 'true'
`repeated_threat_detection`	boolean	If true, will attempt to detect if an antimalware product is installed, and if so - will gather threat data from the located product. If no antimalware product is detected - then no results will be produced for repeathed threat detection. Default value is 'true'
`repeated_threat_detection_options`	object	Will contain a key for each options used in detecting repeated threats
`repeated_threat_detection_options.monitor_days`	number	Number of past, consecutive days-worth of threat history to be included. For instance a value of '3' will consider threat detection history from past 3 days. Default value is '7'
`repeated_threat_detection_options.repeated_tolerance`	number	Minimum number of times the threat has to be detected to be considered a repeated threat. Default value is '2'

JSON Output Structure

{
  "result": {
    "method": 80009,
    "code": number,
    "timing": number,
    "timestamp": string,
    "infection_found": boolean,
    "details": [
      {
        "infected_processes": [
          {
            "file": string,
            "file_id": string,
            "mso_data_id": string,
            "sha1": string,
            "md5": string,
            "sha256": string,
            "total_source": number,
            "threats": [
              {
                "threat_name": string,
                "av_name": string,
                "av_def_time": string,
                "scan_time": string
              },
              ...
            ]
          },
          ...
        ],
        "blacklisted_connections": [
          {
            "network_address": string,
            "total_source": string,
            "threats": [
              {
                "assessment": string,
                "source_name": string,
                "confident": string
              },
              ...
            ],
            "geo_info": object,
            "city": string,
            "country_name": string,
            "country_code": string,
            "region_name": string,
            "region_code": string,
            "latitude": string,
            "longitude": string
          },
          ...
        ],
        "found_repeated_threats": [
          {
            "file": string,
            "found_repeated_by_signature": [
              {
                "signature": string,
                "threat_name": string,
                "repeat_count": number,
                "repeat_details": [
                  {
                    "scan_time": string,
                    "remediation": string
                  },
                  ...
                ]
              },
              ...
            ]
          },
          ...
        ]
      },
      ...
    ]
  }
}

Output Properties

Property	Type	Description
`result.method`	number	The method ID that generated this result.
`result.code`	number	The result code. See Result Codes.
`result.timing`	number	The measured time for the method call in milliseconds.
`result.timestamp`	string	The timestamp in seconds of when the call was made.
`result.infection_found`	boolean	If true, infections were found and more information is available in 'details' object
`result.details`	object	Contains grouped results for all requested scan types
`result.details.infected_processes`	array<object>	Holds the process scan results
`result.details.infected_processes.file`	string	Absolute path to process file that was detected as a threat
`result.details.infected_processes.file_id`	string	Threat file's ID
`result.details.infected_processes.mso_data_id`	string	Threat file's Metadefender ID
`result.details.infected_processes.sha1`	string	Threat file's SHA-1 hash value
`result.details.infected_processes.md5`	string	Threat file's MD5 hash value
`result.details.infected_processes.sha256`	string	Threat file's SHA-256 hash value
`result.details.infected_processes.total_source`	number	Number of Matascan Online engines used for scanning
`result.details.infected_processes.threats`	array<object>	An array of threats found with detailed information
`result.details.infected_processes.threats.threat_name`	string	Name of threat found
`result.details.infected_processes.threats.av_name`	string	Name of the antimalware product used to detect the threat
`result.details.infected_processes.threats.av_def_time`	string	The definition time of a specific antivirus engine
`result.details.infected_processes.threats.scan_time`	string	The time the threat was found in unix time (GMT).
`result.details.blacklisted_connections`	array<object>	Holds the network connection scan results
`result.details.blacklisted_connections.network_address`	string	Network address of the detected threat
`result.details.blacklisted_connections.total_source`	string	Number of Matascan Online engines used for scanning
`result.details.blacklisted_connections.threats`	array<object>	An array of threats found with detailed information
`result.details.blacklisted_connections.threats.assessment`	string	Assessment of the type of detected threat
`result.details.blacklisted_connections.threats.source_name`	string	Name associated with the source of the threat
`result.details.blacklisted_connections.threats.confident`	string	Confidence level behind the detected threat
`result.details.blacklisted_connections.geo_info`	object	Geographic information related to the threat
`result.details.blacklisted_connections.city`	string	Name of city from which the threat originated
`result.details.blacklisted_connections.country_name`	string	Name of country from which the threat originated
`result.details.blacklisted_connections.country_code`	string	Country code from which the threat originated
`result.details.blacklisted_connections.region_name`	string	Name of the geographic region from which the threat originated
`result.details.blacklisted_connections.region_code`	string	Geographic region code from which the threat originated
`result.details.blacklisted_connections.latitude`	string	Geographic coordinate of the threat origin along the North-South position of a point on the Earth's surface, measured in decimal degrees North or South of the equator
`result.details.blacklisted_connections.longitude`	string	Geographic coordinate of the threat origin along the East-West position of a point on the Earth's surface, measured in decimal degrees East or West of the Prime Meridian
`result.details.found_repeated_threats`	array<object>	An array of details representing repeated threats which were detected
`result.details.found_repeated_threats.file`	string	Absolute file path of the repeated threat
`result.details.found_repeated_threats.found_repeated_by_signature`	array<object>	Details of threats that had their signatures repeatedly detected
`result.details.found_repeated_threats.found_repeated_by_signature.signature`	string	Signature ID of the detected threat
`result.details.found_repeated_threats.found_repeated_by_signature.threat_name`	string	Name of the detected threat
`result.details.found_repeated_threats.found_repeated_by_signature.repeat_count`	number	Number of times this threat has been repeatedly detected
`result.details.found_repeated_threats.found_repeated_by_signature.repeat_details`	array<object>	Details of the repeated threats
`result.details.found_repeated_threats.found_repeated_by_signature.repeat_details.scan_time`	string	The time the threat was found in unix time (GMT).
`result.details.found_repeated_threats.found_repeated_by_signature.repeat_details.remediation`	string	The type of remediation (none, cleaned, deleted, quarantined, or partial).

Result Codes

Code	Name	Description
0	`WAAPI_OK`	The operation completed successfully.

note

Other codes may be returned. See the full Result Codes reference for the complete list.

Remarks

Error Handling

The results of this function are determined by the error code returned by the call. If successful, WAAPI_OK or a special success code will be returned. Always check both the function return value and the result.code field in the output JSON.

Examples

Examples will be added here demonstrating the usage of this method.

Syntax​

Method ID​

JSON Input Structure​

Input Properties​

JSON Output Structure​

Output Properties​

Result Codes​

Remarks​

Error Handling​

Examples​

See Also​