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 (Internet Content Adaptation Protocol) 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.

Each scanner defines how files are streamed, evaluated, and handled during transfer, and includes configuration options to control:

• The ICAP or ICAPS service URI used to connect to the scanning service.
• Optional CA Certificate to enable ICAPS.
• 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(S) server. Collecting this information beforehand helps ensure correct configuration of ICAP Scanners and prevents common setup issues:

• ICAP(S) server URI: You need the full URI of the ICAP(S) server, including the hostname or IP address, port number, and service name (it typically follows the format: hostname:port/service).
• Connection testing: Ensure that the network allows USP to reach the ICAP(S) server endpoint on the specified port. Firewall or routing issues can prevent successful communication.

ICAPS (ICAP over TLS)

ICAPS is the secure variant of the Internet Content Adaptation Protocol. It encapsulates ICAP traffic within a TLS (Transport Layer Security) session to ensure confidentiality, integrity, and server authenticity during file scanning.

To configure an ICAP Scanner to use ICAPS:

1. Verify TLS support on the ICAP Server: Some ICAP services expose both ICAP (1344) and ICAPS (11344) endpoints. Confirm that the server supports secure connections and that the required port is accessible.
2. Obtain the CA Certificate: This certificate must correspond to the Certificate Authority that signed the ICAPS server's TLS certificate. It is used to validate the server's authenticity.
3. Add the CA Certificate: Import the certificate into USP Manager as a CA Certificate.
4. Reference the CA Certificate: In the CA Certificate for ICAPS field, select the certificate you imported.

info

In ICAPS, specify the server hostname using the same format as plain ICAP: hostname:port/service. Do not include a URL scheme such as icaps://. TLS negotiation is handled internally by USP when you assign a CA Certificate to the ICAP Scanner.

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.

File Size Limits

USP Server dynamically allocates memory for in-line ICAP scanning to optimize performance and prevent unnecessary resource usage. Memory is assigned per file as it is received and incrementally expanded as scanning progresses, up to the configured maximum limit.

This maximum is controlled through the Maximum File Size to Scan (bytes) setting defined in each ICAP Scanner. The minimum allowed value is 1 byte, and there is no upper limit. Administrators can adjust this value as needed to balance scanning coverage with available system resources.

warning

When configuring very large limits (for example, values greater than 100 MB), ensure that each USP Server instance has sufficient RAM to handle the expected number of concurrent transfers. Because memory is allocated dynamically per active file, environments with high concurrency and large buffer settings may experience increased memory consumption.

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.

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
CA Certificate for ICAPS	The name of the CA Certificate used for validating the remote server's X.509 certificate for the secure ICAP connection.	Must reference an already created CA Certificate.	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)	Defines the maximum file size (in bytes) eligible for in-line ICAP scanning. warning Be careful with large values (over 100 MB), as they can significantly increase total memory usage. info For more information, refer to File Size Limits.	Must be greater than 1.	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.