ICAP Scanners

An ICAP Scanner is a Configuration Item that enables a USP Server instance to inspect file content in-line—i.e., as it is received—using an external ICAP (Internet Content Adaptation Protocol) service. This allows potential threats to be identified and blocked before files reach internal systems, enhancing security at the session break boundary.

ICAP is a lightweight, HTTP-like protocol defined in RFC 3507. It is commonly used for antivirus scanning, data loss prevention, and content filtering in proxy-based environments. In USP, ICAP integration allows scanning to occur during active file transfers without requiring the file to be written to disk.

ICAP Scanners define how files are streamed, evaluated, and handled during transfer. Each scanner includes configuration options to control:

• The ICAP service URI used to connect to the scanning service.
• The maximum file size eligible for scanning, and optional filters to exclude specific file extensions.
• The error handling policy that determines what happens when scanning fails (e.g., block, flag, or allow).
• Support for advanced features like Preview mode and proxying through a secure Tunnel and Proxy Client.

info

To be operational, an ICAP Scanner must be associated with a Rule. A single scanner can be reused across multiple Rules to enforce consistent scanning policies.

Before You Begin

Know Your ICAP Server

Before configuring ICAP integration in USP, 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, USP only supports ICAP and does not support ICAPS.
• Connection Testing: Ensure that the network allows USP 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, USP evaluates its response and applies one of several 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.
• Infected Files: When a file violates security policies (e.g., containing malware or disallowed content), USP automatically stops the proxying process.
• Scanning Errors: When the scan cannot be completed due to network issues, timeouts, or other errors, USP allows configurable fallback actions:
  • Reject (delete): The file transfer is aborted to prevent potential risk.
  • Flag (rename): The file proceeds to its destination, but with a user-defined extension (recommended).
  • Bypass (skip): The file bypasses scanning and proceeds to the destination (not recommended).

Tunnels and Clients

If the ICAP server is restricted by network boundaries, such as firewalls or segmented zones, the USP Server instance will need a Tunnel and a Proxy Client to reach it.

As with other services, Tunnels and Proxy Clients for ICAP are set within Deployments.

Smart Memory Management and File Scanning Limits

To balance performance, security, and system stability, USP's in-line ICAP scanning uses an intelligent memory management approach. Every file being scanned temporarily uses server memory, and to protect overall system performance, you can set a configurable maximum file size limit for scanning, up to 10,485,760 bytes (10 MiB).

Files within this limit are always scanned completely. As a file is received, scanning begins once enough data has been collected, either as a preview segment or additional bytes requested by the scanner. While waiting for the scanner's response, the system continues to accept file data into memory up to the defined maximum. If the scanner responds before that limit is reached, the result is acted upon, either allowing the file to proceed, flagging it, or blocking it. If the bytes received exceed the maximum size before a response is received, scanning is skipped to avoid overuse of system memory, and the file is passed through to the backend without the scan having been completed.

Keep in mind that this memory allocation happens per file. If your environment handles many concurrent file transfers—such as hundreds or even thousands at a time—the total memory usage can grow quickly. For example, if the maximum buffer size is set to 10,485,760 bytes (10 MiB) and 1,000 files are received at once, a theoretical maximum of ~10 GB of memory could be temporarily in use. In such cases, it may be wise to lower the scan size limit to better align with your system's capacity and scan coverage goals.

While in-line scanning offers an effective first layer of protection, it should not be treated as the only defense. To reduce the risk of unscanned files being forwarded, we strongly recommend enabling additional scanning in your Managed File Transfer (MFT) solution. Scanning at rest ensures the entire file can be evaluated without the timing and memory constraints of real-time scanning. Together, both layers offer a more complete and resilient security posture.

Advanced Settings

Preview Mode Support

USP automatically uses ICAP Preview mode when communicating with an ICAP server that supports this feature. Preview mode allows the ICAP server to inspect a small portion of the file (a preview) before deciding whether it needs to see the entire file or can make a decision early. This helps reduce scanning latency and improves overall transfer performance, especially for large files.

File Extension Exclusion

USP allows administrators to specify a list of file extensions that should be excluded from ICAP scanning. This feature helps optimize system performance by preventing unnecessary scans of file types that are known to be safe or irrelevant to security policies (like compressed or encrypted files).

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

Flagging

If Error Policy is set to Flag (rename), then USP flags the files as unscanned. You can then configure UDMG to look for this extension and deal with it accordingly.

Logging

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

info

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

ICAP Timeout

The timeout for ICAP server scans is configured in the USP Server Configuration File using the icap.timeout argument name. This value defines how long the USP Server will wait for a response from the ICAP server during scan operations. By default, the timeout is set to 30 seconds.

ICAP Scanner Administration via USP Admin UI

Adding an ICAP Scanner

To add an ICAP Scanner, follow these steps:

1. From the Sidebar, click Configuration > ICAP Scanners.
2. Click Add ICAP Scanner.
3. Complete the details for the new ICAP Scanner using the Field Descriptions table as a guide.
4. Click Save.

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 Service Hostname	The hostname or IP address of the ICAP server.	Format: icap://example.com:port/service	Yes
Port	The port used to connect to the ICAP service.		Yes
ICAP Service Name	The service name (if any) of the ICAP service.	Must follow the Standard Naming Pattern.	No
Skip Files Matching Extension(s)	Specify file extensions that should not be scanned as a comma-delimited list.	Type the file extension and click Enter. File extensions must be specified without leading dots.	No
Maximum File Size to Scan (bytes)	Files under this limit are virtually guaranteed to be scanned. However, files larger than the limit may also be scanned if results are returned early. info For more information, refer to Smart Memory Management and File Scanning Limits.		No
Error Policy	Behavior when a file targeted for scanning cannot be scanned for any reason (network or other faults). Options: Reject (delete) Flag (rename) Bypass (skip)		Yes
Extension for Flagged (Renamed) Files	Extension added to flagged files for subsequent identification.		Yes, if Error Policy is set to Flag.

Editing an ICAP Scanner

To edit an ICAP Scanner, follow these steps:

1. From the Sidebar, click Configuration > ICAP Scanners.
2. Click the ICAP Scanner you want to edit.
3. Click the Edit button above the ICAP Scanner details.
4. Edit the details of the ICAP Scanner using the Field Descriptions table above as a guide.
5. Click Save.

warning

If you modify a ICAP Scanner that is currently in use by a USP Server instance, the changes will not take effect until you manually apply the updated configuration by pushing it to the server. To apply the changes:

1. Navigate to Monitoring > Status.
2. Click the Name of the associated USP Server instance.
3. Go to the Configuration tab.
4. Review the pending changes in the Updated Configuration column.
5. If the changes are correct, click Push Configuration.

ICAP Scanner Metadata

ICAP Scanner details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

Name	Description
ID	Universally Unique Identifier of this ICAP Scanner.
Created At	Date and time this ICAP Scanner was created.
Updated At	Date and time this ICAP Scanner was last updated.

Deleting an ICAP Scanner

To delete an ICAP Scanner, follow these steps:

1. From the Sidebar, click Configuration > ICAP Scanners.
2. Click the ICAP Scanner you want to delete.
3. Click the Delete button above the ICAP Scanner details.
4. You will be asked to confirm the deletion. Click Delete.

warning

USP Manager prevents deletion of an ICAP Scanner if it is currently referenced by a Rule.

Additionally, if the ICAP Scanner is used by a USP Server instance, the updated configuration must be manually applied. To apply the changes:

1. Navigate to Monitoring > Status.
2. Click the Name of the associated USP Server instance.
3. Go to the Configuration tab.
4. Review the pending changes in the Candidate Configuration - Preview section.
5. If the changes are correct, click Push Configuration.

The changes do not take effect on the server until this step is completed.

ICAP Test

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 Configuration > ICAP Scanners.
2. Click the ICAP Scanner you want to test.
3. Click the Test ICAP button above the ICAP Scanner details. This action performs an OPTIONS test using the provided ICAP service URI.

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 after 10 seconds. 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.