List Managed Antivirus Scans

Use this API Call to query our Data Extraction API to extract data gathered by N-sight RMM.This section shows the service name and parameters needed in the API Call query, and provides examples of some queries and system responses. For more information, see Data Extraction API.

Service name: list_mav_scans

URL

https://SERVER/api/?apikey=yourAPIkey&service=list_mav_scans

&required_parameters=required_parameters

[&optional_parameters=optional_parameters]

Description

Returns list of Managed Antivirus scans for a device; these could be in-progress or complete.

The information is available as summaries (details=NO) or with threats, quarantine and errors included (details=YES).

Parameters
Post Variable	Description	Type	Required	Options	Default
describe	Optional. Returns a description of the service.	boolean	no	true	0
deviceid	The deviceid must be a valid device id.	integer	yes	0	0
details	Level of information displayed YES for details; NO for summary	string	yes	NO YES	0
v	Managed Antivirus engine version 1 VIPRE engine 2 Bitdefender engine From Dashboard 2019.08.13 this call defaults to version 2 (Bitdefender).	integer	no	1 2	2

Example Service Call =list_mav_scans

https://SERVER/api/?apikey=yourAPIkey&service=list_mav_scans&deviceid=DEVICEID&details=DETAIL&v=VERSION

Example Responses

VIPRE engine: the following example response displays data for scans on a device running the Managed Antivirus VIPRE engine.

<?xml version="1.0" ?>

<scan>[example when details=YES]

<type>[one of: QUICK, DEEP, ACTIVE or CUSTOM]</type>

<status>[one of: NONE, PENDING, PENDING_AGENT, FINISHED, CANCELED, ERROR, PAUSED, RUNNING]</status>

<start>2013-01-15 05:41:55[UTC start time]</start>

<end>2013-01-15 05:41:55[UTC end time; only included if scanning complete]</end>

<cookies_scanned>0</cookies_scanned>

<registry_scanned>0</registry_scanned>

<files_scanned>1</files_scanned>

<folders_scanned>0</folders_scanned>

<processes_scanned>0</processes_scanned>

<threats>[only included when at least one threat is discovered AND details=YES]

<name>Worm.Win32.Downad.Gen (v)</name>

<status>[one of: QUARANTINED, RELEASE_PENDING, RELEASED, DELETE_PENDING, DELETED, REPORTED, FAILED_TO_QUARANTINE, FAILED_TO_RELEASE, FAILED_TO_DELETE]</status>

<quarantine>[only included when item(s) quarantined]

<item>

<count>1[number of files (or other scanned entities) included with this quarantine item]</count>

</item>

[...more item entries if they exist...]

</quarantine>

<trace>

<type>[one of: COOKIE, PROCESS, REGISTRY_ENTRY, FILE, FOLDER, ARCHIVE, PROCESS_MODULE, DEVICE_DRIVER, DLL_EXPORT, SYSTEM_DLL_EXPORT, MASTER_BOOT_RECORD, ROOTKIT, SYSTEM_MODULE, HOOK, UNKNOWN]</type>

<description>[e.g. filename, or registry key with value, or reference to a process etc.]</description>

</trace>

[...more trace entries if they exist...]

</traces>

</threat>

[...more threat entries if they exist...]

</threats>

<errors>[only included if at least one scan error occurred AND details=YES]

<error>

<item>[filename or identifier]</item>

<reason>[scan error - see below]</reason>

</error>

[...more error entries if they exist...]

</errors>

</scan>

<scan>[example when details=NO, i.e. a summary]

<type>QUICK</type>

<status>FINISHED</status>

<cookies_scanned>0</cookies_scanned>

<registry_scanned>29563</registry_scanned>

<files_scanned>3297</files_scanned>

<folders_scanned>818</folders_scanned>

<processes_scanned>35</processes_scanned>

<threat_count>37</threat_count>

<quarantine_count>4</quarantine_count>

<error_count>3</error_count>

</scan>

[...more scan entries if they exist...]

</result>

</example>

Field Descriptions

A result element containing zero or more entries (scan elements in XML), each scan having:

field

included

description

type

yes

Scan type, one of:

VIPRE Engine

QUICK

DEEP

ACTIVE

CUSTOM

Bitdefender Engine

Active Protection

Quick

Deep

Custom

Behavioral

IDS

Device

status

yes

Scan status, one of:

VIPRE Engine

NONE

PENDING

PENDING_AGENT

FINISHED

CANCELED

ERROR

PAUSED

RUNNING

Bitdefender Engine

Scan Finished Normally

Scan Aborted

Scan Stopped

Scan In Progress

start

yes

Scan start time, e.g. 2013-06-21 19:18:17

For VIPRE engine scans the time is UTC

For Bitdefender engine scans the time is the agent local time.

end

if scanning complete

Scan end time, e.g. 2013-06-21 19:27:35

For VIPRE engine scans the time is UTC

For Bitdefender engine scans the time is the agent local time.

cookies_scanned

yes

Number of cookies scanned

registry_scanned

yes

Number of registry entries scanned

files_scanned

yes

Number of files scanned

folders_scanned

yes

Number of folders scanned

Note: For Bitdefender engine scans this is always 0 as the Bitdefender engine does not scan by folder.

processes_scanned

yes

Number of processes scanned

threat_count

if details=NO

Count of threats found

quarantine_count

if details=NO

Count of items quarantined

error_count

if details=NO,

or if v>1 and engine is Bitdefender

Count of errors encountered

threats

if details=YES

List of threats, each threat having:

field

description

name

Name of threat, e.g. Worm.Win32.Downad.Gen (v)

category

Category of threat, e.g. Worm.W32

Note: the threat category names can differ between the VIPRE and Bitdefender engines.

status

Threat status, one of:

VIPRE Engine

QUARANTINED

RELEASE_PENDING

RELEASED

DELETE_PENDING

DELETED

REPORTED

FAILED_TO_QUARANTINE

FAILED_TO_RELEASE

FAILED_TO_DELETE

Bitdefender Engine

Ignored

Detected

Deleted

Blocked

Quarantined

Cleaned

Note: for Bitdefender the value represents the status of the most recent operation within the set of traces relating to this threat - there is also a separate status field within each individual trace entry which may be more useful (see below).

quarantine

(only included if item(s) quarantined during this scan)
List of items quarantined; each item having:

field

description

guid

Unique id on the device for the quarantined item

For Bitdefender scans, this field is not always populated and if present contains an integer rather than a 'GUID' string. This ID is more readily available from the mav_quarantine_list and list_mav_quarantine services.

count

Number of files (or other scanned entities, e.g. registry entries) moved to quarantine for this item.

Note: For Bitdefender engine scans this is always 1 as there is only ever one trace per quarantine item.

deleted

Has the quarantined item been deleted?

YES or NO

type

Field only included for Bitdefender scans contains the type of the quarantined item with the value one of:

File	Process
Http	Boot Sector
Cookie	Registry
POP3	ADS Stream
SMTP

description

Field only included for Bitdefender engine scans contains the path of the quarantined item trace on the device.

traces

List of traces of the threat, each trace having:

field

description

type

Type of trace. one of:

VIPRE Engine
COOKIE	DLL_EXPORT
PROCESS	SYSTEM_DLL
REGISTRY_ENTRY	EXPORT
FILE	MASTER_BOOT_RECORD
FOLDER	ROOTKIT
ARCHIVE	SYSTEM_MODULE
PROCESS_MODULE	HOOK
DEVICE_DRIVER	UNKNOWN

Bitdefender Engine
File	Process
Http	Boot Sector
Cookie	Registry
POP3	ADS Stream
SMTP

description

Could be:

a filename

a registry key with value

a reference to a process

etc

status

Field only included for Bitdefender engine scans contains status of this trace with the value one of:

Ignored

Detected

Deleted

Blocked

Quarantined

Cleaned

errors

if details=YES and at least one scanning error occurred and the engine is VIPRE

This field is only present for scans performed by the VIPRE engine and only when at least one scanning error occurred. It provides a list of errors which occurred while scanning, each having:

field

description

item

filename or identifier

reason

CREATE_FILE	STOP_SERVICE
DELETE_FILE	DELETE_SERVICE
COPY_FILE	LIST_REGISTRY_KEYS
MOVE_FILE	LIST_REGISTRY_VALUES
READ_FILE_ADS	OPEN_REGISTRY_VALUE
LIST_FOLDER_CONTENTS	CREATE_REGISTRY_VALUE
CREATE_FOLDER	DELETE_REGISTRY_VALUE
DELETE_FOLDER	LOAD_REGISTRY_VALUE
COPY_FOLDER	GET_REGISTRY_VALUE
MOVE_FOLDER	SET_REGISTRY_VALUE
LIST_PROCESSES	REBOOT_DELETE_FILE
LIST_PROCESS_MODULES	REBOOT_DELETE_FOLDER
OPEN_PROCESS	REBOOT_DELETE_REGISTRY_KEY
CREATE_PROCESS	REBOOT_DELETE_REGISTRY_VALUE
SUSPEND_PROCESS	CORRUPT_ARCHIVE
RESUME_PROCESS	PASSWORD_PROTECTED_ARCHIVE
KILL_PROCESS	ARCHIVE_NESTED_TOO_DEEP
LIST_SERVICES	REMEDIATION_FAILURE
OPEN_SERVICE	OPERATION_NOT_IMPLEMENTED
START_SERVICE	FAILED_TO_QUARANTINE
PAUSE_SERVICE	UNKNOWN
RESUME_SERVICE

engine

if v > 1

Managed Antivirus engine where this data originates from, either VIPRE or Bitdefender

Example Associated Service Calls
Parameter	Call	URL Format
DeviceID	list_devices_at_client	https://SERVER/api/?apikey=yourAPIkey&service=list_devices_at_client&clientid=CLIENTID&devicetype=server
	list_servers	https://SERVER/api/?apikey=yourAPIkey&service=list_servers&siteid=SITEID
	list_workstations	https://SERVER/api/?apikey=yourAPIkey&service=list_workstations&siteid=SITEID
SiteID	list_sites	https://SERVER/api/?apikey=yourAPIkey&service=list_sites&clientid=CLIENTID
ClientID	list_clients	https://SERVER/api/?apikey=yourAPIkey&service=list_clients

The scan information for both the Bitdefender and VIPRE Managed Antivirus engines will go back for one year (where available).

Example Associated Service Calls
Parameter	Call	URL Format
DeviceID	list_devices_at_client	https://SERVER/api/?apikey=yourAPIkey&service=list_devices_at_client&clientid=CLIENTID&devicetype=server
	list_servers	https://SERVER/api/?apikey=yourAPIkey&service=list_servers&siteid=SITEID
	list_workstations	https://SERVER/api/?apikey=yourAPIkey&service=list_workstations&siteid=SITEID
SiteID	list_sites	https://SERVER/api/?apikey=yourAPIkey&service=list_sites&clientid=CLIENTID
ClientID	list_clients	https://SERVER/api/?apikey=yourAPIkey&service=list_clients