ICAP Scanner

UDMG supports ICAP, allowing inbound files to be scanned for viruses and other threats before reaching their destination.

ICAP (Internet Content Adaptation Protocol) is a lightweight, HTTP-like protocol defined in RFC 3507 and widely used for virus scanning and content filtering in transparent HTTP proxy caches.

In UDMG, ICAP integration is managed through two layers:

• A Domain-specific ICAP Scanner configured in the UDMG Admin UI, and
• global ICAP settings configured in the Configuration File's icap block.

This design lets each Domain define its own ICAP Scanner settings (such as the ICAP server address and scan policies), while the icap block provides shared, server-wide behavior (such as timeouts) for all Domains.

For the ICAP Scanner to participate in file transfers, the involved Local Filesystem Endpoint must have its ICAP Scanning - Inbound field enabled.

info

UDMG does not support ICAPS (ICAP over TLS) in the current version.

Before You Begin

Know Your ICAP Server

Before configuring ICAP integration in UDMG, it is essential to gather key information about the ICAP server. Having this information in advance helps ensure correct configuration of ICAP Scanners and prevents common setup issues:

• ICAP Server URI: You need the full URI of the ICAP server, including the hostname or IP address, port number, and service name (it typically follows the format: icap://hostname:port/service).
• Security Requirements: Determine if the ICAP server requires secure connections over TLS (ICAPS). Currently, UDMG only supports ICAP and does not support ICAPS.
• Connection Testing: Ensure that the network allows UDMG to reach the ICAP server endpoint on the specified port. Firewall or routing issues can prevent successful communication.

Scan Results Handling

When a file is scanned by the ICAP server, UDMG evaluates the response and applies one of several configurable actions depending on whether a violation or an error is detected:

• Clean Files: Files that pass the scan without any detected threats are allowed to proceed normally and are forwarded to their intended destination.
• Violations: If the ICAP server identifies a file as violating security policies (e.g., containing malware or disallowed content), UDMG can be configured to take one of the following actions:
  • Reject (delete): The file is deleted immediately and a failure response is sent to the connected client.
  • Quarantine: The file is kept in the Temporary Path directory with a renamed extension for later review or manual intervention.
• Error Policy: In cases where the scan cannot be completed due to network issues, timeouts, or other errors, UDMG allows configurable fallback actions:
  • Reject (delete): The file is deleted to prevent potential risk.
  • Quarantine: The file is kept in the Temporary Path directory with a renamed extension for later review or manual intervention.
  • Flag (rename): The file is renamed but allowed to continue to the target destination.
  • Bypass (skip): The file bypasses scanning and proceeds to the destination (not recommended).

Advanced Settings

Preview Mode and Max Bytes to Scan

Preview mode is a feature supported by many ICAP servers that allows scanning only a portion of a file initially, rather than sending the entire file at once. Using Preview mode is recommended whenever supported, as it significantly speeds up scanning—especially for large files—and improves overall efficiency.

With Preview mode, UDMG sends an initial chunk of the file to the ICAP server for scanning (the size of this chunk is determined by the ICAP server). If the ICAP server determines that further data is needed for a thorough scan, it requests the remaining bytes, and the rest of the file is sent up to the configured Max Bytes to Scan.

If the ICAP server does not support Preview mode, UDMG automatically disables Preview mode for that scan and sends the entire file or up to the configured Max Bytes to Scan.

Scenario	UDMG Behavior
Preview mode is enabled in UDMG and the ICAP server supports it.	Sends the configured preview size of bytes; if the ICAP server requests more data, sends remaining bytes up to max scan size.
Preview mode is enabled in UDMG, but the ICAP server does not support it.	UDMG disables Preview mode automatically and sends the full file or max bytes in a single scan request.
Preview mode is disabled in UDMG settings.	Sends the entire file or max bytes in one scan request without using Preview.
Preview mode is enabled in UDMG and the ICAP server supports it, but the file size is smaller than the expected preview size.	Sends the entire file in a single scan without preview.

File Extension Exclusion

UDMG allows administrators to specify a list of file extensions to exclude from ICAP scanning. This feature helps optimize system performance by preventing unnecessary scans of file types that typically don't require scanning—such as encrypted files or compressed archives—or otherwise deemed irrelevant to security policies.

Files matching any of the configured extensions will bypass ICAP scanning and proceed directly to their destination.

Logging

UDMG provides logging for all ICAP scanning operations, enabling administrators to monitor scanning activity, troubleshoot issues, and maintain audit trails.

When integrated with Universal Automation Center (UAC), relevant ICAP scan events can trigger automation workflows, with logging capturing event details and file status (e.g., a file was quarantined, deleted, or allowed).

info

The log level for ICAP scanning corresponds to the setting configured in the log block of UDMG's HCL configuration file. For more details on log configuration and management, refer to Logging.

Configuring ICAP

ICAP Scanners are configured at the Domain level. To configure an ICAP Scanner, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click the ICAP Scanner card.
3. Complete the fields for the ICAP Scanner settings, using the Field Descriptions table as a guide.
4. Click Save.

info

For the ICAP Scanner to participate in file transfers, the involved Local Filesystem Endpoint must have its ICAP Scanning - Inbound field enabled.

Field Descriptions

Name	Description	Specifications	Required
Name	The name of the ICAP Scanner.	Must be unique. Must follow the Standard Naming Pattern.	Yes
Description	The description of the ICAP Scanner.		No
ICAP Server Hostname	The ICAP server hostname or IP address.	Format: example.com 192.168.1.10	Yes
Port	The port of the ICAP Service.	Must be within 1 and 65535.	Yes
ICAP Service Name	The service name of the ICAP Service.	Example: avscan	No
Use Preview if Supported by the ICAP Server	A toggle switch to enable or disable the ICAP Preview mode. If disabled, UDMG sends the entire file or up to the Max Bytes to Scan value.		No
Max Bytes to Scan	Specifies the maximum number of bytes UDMG sends to the ICAP server for scanning. For more details, see Preview Mode and Max Bytes to Scan.	Specify a value that matches your ICAP vendor's recommended settings (typically 1MiB-5MiB).	No
Skip Files Matching (Extensions)	Enter a comma-separated list of file extensions that should be excluded from scanning. Do not include the leading period (dot).	Example: pgp, zip, gz	No
Violations	Behavior if a violation is detected. Options: Reject (delete) Quarantine		Yes
Error Policy	Behavior if a file intended to be scanned could not be scanned for any reason (network or other faults). Options: Reject (delete) Quarantine Flag (rename) Bypass (skip)		Yes
Extension for Flagged (Renamed) Files	Extension added to quarantined or flagged files for subsequent identification.	Example: FLAGGED	Yes, if Violations or Error Policy are set to Quarantine or Flag

Testing the ICAP Connection

The ICAP server connection can be tested to confirm if the service is correctly configured.

To test the ICAP server, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click the ICAP Scanner card.
3. Click the Test ICAP button above the ICAP Scanner details. This action performs a test using the provided ICAP Server Hostname and Port.

info

You can also check the ICAP Scanner status in the UDMG Status modal.

Responses

Scenarios	Message
Good response!	The ICAP test connection was successful! Response details: Connected to: icap://icap.example.net:1344 Server responded in: 82 ms Supported methods: RESPMOD, REQMOD Preview: supported, up to 2048 bytes Allow: 204 supported ISTag: "sophos-dlp-103" OPTIONS-TTL: 3600 seconds
Unable to connect	The ICAP test was unable to connect to: [URI]. Please verify the address, port, and service name, and that there is a valid route to the ICAP server, and try again.
Timeout on response	The ICAP test made a connection, but no response was received, or a timeout occurred. Please verify that the ICAP server is operational, is configured correctly, and that there are no limitations on the network route, and try again.
Bad response	The ICAP test made a connection, but was unable to validate the response. You may continue as is or try a different configuration. Please review logs for the detailed response message received.