Callback for Processing a File (COM)

Method

OnProcess

Description

This callback is fired after each Process method when a pre-defined event is found.

Note

Connection Points

Function prototype

void OnProcess
(
[out] VARIANT *OutDetail,
[out, retval] VARIANT *OutArgsArray
)

Arguments

Argument

Description

Data Type

OutDetail

The details from this event. The JSON schema depends on the callback type. See ‘‘callback types’’ for more details.

string

OutArgsArray

0: CallBackType: Since OnProcess is a general callback that is fired for different events, this specifies the event type. See the callback types for details of the type.

1: Ticket: The ticket returned from the Process API. For example 974989300.

2: The final result of processing the specified file through a workflow

1 = The file was allowed. JSON equivalent is "Allowed"

2 = The file was blocked. JSON equivalent is "Blocked"

3 = The file is currently being processed. JSON equivalent is "Processing"

Safearray of variants with the following order

0: UINT32

1: string

2: UINT32

Callback types

Callback Type

Description and example

2

This callback method is invoked whenever each engine completes the scan. This callback can be used for a progress report of scanning when more than one engine is used. If engines are not used for any reason such as encrypted archive or scan request on a known file, no progress report is fired.


Example
{
    "type": "ScanProgressReport",
    "ticket": 974989300,
    "scan_result": "1",
    "threat_list": [
        "eicar",
        "eicar"
    ],
    "product_name": "Clamwin Scan Engine",
    "scan_start_time": "6/5/2014 2:32 PM",
    "scan_end_time": "6/5/2014 2:32 PM",
    "scan_time_(ms)": "1",
    "file_path": "C:\\some\\file.txt",
    "process_result": "Processing"
}


4

This connection point is fired whenever a scan is completed. This event is not global but specific to the client that makes this scan request. In other words, when scanning is requested by a client, other client objects will not get a callback when the scanning is completed.


Example
{
    "type": "OnScanComplete",
    "ticket": 974989300,
    "scan_result": "1",
    "threat_list": [
        "eicar",
        "eicar"
    ],
    "scan_start_time": "6/5/2014 2:32 PM",
    "scan_end_time": "6/5/2014 2:32 PM",
    "scan_time_(ms)": "2",
    "file_path": "C:\\some\\file.txt",
    "process_result": "Processing"
}


7

This callback method is invoked when Process' archive handling is enabled and an archive was successfully extracted.

This callback can be used to determine if a processed file is an archive.


Example
{
    "type": "ArchiveFileInfo",
    "ticket": 783676241,
    "file_path": "2files_dirty.zip",
    "process_result": "Processing"
}


8

This is fired after a file has been fully processed through each stage of a workflow.

If Data Sanitization (DS) is enabled and copy/move is disabled, the sanitized file will appear next to the original file.

If DS and copy/move are enabled, the sanitized filename will be reported in "post_processing.copy/move_destination"

Collisions are handled by incrementing the file name: file_name.txt , file_name_1.txt , file_name_2.txt , ..

Possible Blocked Reasons

  • Failed to start the processing job: "Process Failed"

  • Mismatch detected: "Mismatch"

  • File type disallowed: "Filtered"

  • Scan Result: "Known | ("Dirty" or "Infected") | Suspicious |
    Failed | Cleaned | Unknown |
    ("Skipped Dirty" or "Skipped Infected") | Not Scanned |
    Aborted | Password Protected Document"

  • Archive: "Encrypted Archive | Missing File During Extraction |
    Insufficient Space For Archive Extraction |
    Exceeded Archive Size | Exceeded Archive File Number |
    Archive Extraction Error | Exceeded Archive Depth |
    Archive Error"

  • Post Action: "Sanitization Failed"
    (Copy or Quarantine failure will not cause blocked result)

Possible Process Results

  • "Allowed": the file is allowed

  • "Blocked": the file is blocked

  • "Processing": the file is currently being processed

Possible Action Ran Results

  • Sanitized

  • Copied

  • Moved

  • Quarantined

  • Deleted

  • Ran Script

*Copied and Moved will never exist together
*Quarantined and Deleted will never exist together
*(Copied/Moved) and (Quarantined/Deleted) will never exist together

JSON Key

Explanation

Info

scan_all_result_i

Final consolidated scan result

Normally, for single files, these values can be retrieved from the OnScanComplete type callback.
However, for a final consolidated archive scan result (e.g. the scan result for each file in an archive is consolidated to represent the final archive scan result), these values can be useful.

scan_all_result_a

String description of the final scan result

Example
{
    "type": "ProcessComplete",
    "ticket": "974989300",
    "process_result": "Allowed",
    "file_path": "C:\\some\\file.txt",
    "user_agent": "metascan_rest",
    "profile": "Default",
    "file_type_skipped_scan": false,
    "blocked_reason": "",
    "scan_all_result_i": "0",
    "scan_all_result_a": "No Threat Detected"
}

If Post Processing/File Handling is ran:

Example
{
    "type": "ProcessComplete",
    "ticket": "974989300",
    "process_result": "Allowed",
    "file_path": "C:\\some\\toConvert.docx",
    "user_agent": "metascan_rest",
    "profile": "Default",
    "file_type_skipped_scan": false,
    "blocked_reason": "",
    "scan_all_result_i": "0",
    "scan_all_result_a": "No Threat Detected",
    "post_processing": {
        "actions_ran": "Sanitized | Quarantined | Moved",
        "actions_failed": "Delete Failed",
    	"converted_to": "pdf",
    	"copy_destination": "C:\\toConvert.pdf"
    }
}

9

This callback is fired for AnalyzeFileType. It will be fired for a single file as well as for individual files within an archive.

For a single file it will be a fully qualified path, such as: "C:\\level1\\file.txt"
For a file inside an archive it will be prefixed with \\, such as: "\\level1\\file.txt"

Example
{
    "type": "FileTypeAnalyze",
    "ticket": "974989300",
    "file_path": "C:\\some\\toConvert.docx",
    "file_size": 5134,
    "file_type_category" : "E",
    "file_type_description" : "Win64 Executable",
    "file_type_extension" : "EXE/DLL",
    "md5": "20A2DFB5...",
    "sha1": "6D5052F...",
    "sha256": "4A7C7...",
    "process_result": "Processing"
}