Custom Scanner Agent Requirements
Initial message
The initial gRPC message from the Agent must include the following file metadata in the file_details field:
•File size – This field is required.
•Reference – A unique identifier for the file (such as unique ID); this field is also required.
•SHA1 hash – Recommended if cloud sandboxing is enabled. If omitted, the Scanner will compute the hash itself, requiring the full file content to be transferred.
No additional configuration is required for the initial message by default. Optional scan-specific configuration can be passed via the configuration property.
If the file to be scanned is an email, the file_format property of file_details must be set to 'FILE_FORMAT_EMAIL'.
|
Mail scanning functionality is currently experimental and under testing. Please monitor this documentation for updates and changes. |
Data Requests During Scanning
During the scanning process, the scanner will send data requests specifying the required portions of the file in the data_request field, including:
Parameter |
Description |
|---|---|
size_bytes |
Specifies the total number of bytes requested from the file. |
position |
Indicates the exact starting byte position in the file for the read operation. |
data_chunk_size_limit_bytes |
Specifies the maximum size allowed for each data chunk. By default, this parameter is set to 4096 bytes. For example, a request for 131 kilobytes would be divided into multiple 4kB chunks. |
Responding to Data Requests
Your agent must respond with messages containing the following fields:
Parameter |
Description |
|---|---|
position |
Position in file from which the data was read |
data |
Contains the segment of file data returned in the response. The size must not exceed the limit defined by data_chunk_size_limit_bytes. |
is_last_chunk |
Specifies whether the current message contains the final segment of the requested data. This must be set when the data is split across multiple chunks or when the full data fits within a single chunk based on data_chunk_size_limit_bytes. |
End of scan can be discerned by having non-empty scan_results property of received message.
Scan result if Dynamic Scan component is connected
|
This section applies only to customers using the ESET PRIVATE Scanning Solution with the dynamic scan component enabled. |
If a dynamic scan is performed and completes successfully, its result will appear as the final entry in the scan_results array, with deep_scan_status set to 'DEEP_SCAN_STATUS_FINISHED'.
If a dynamic scan was requested but no result is returned, wait approximately 5 minutes and try scanning again, as cloud sandboxing may take longer to complete.
For a detailed breakdown of the result structure, refer to the ThreatScanResult message definition in the types.proto file.