> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/advanced-genai-tech/icap-content-validation.md).

# ICAP Content Validation Integration

ICAP content validation integration: use ICAP to forward files uploaded through Web Chat to external services for virus scanning, content filtering, and DLP. Covers the integration architecture, proto

> This document explains how the MaiAgent platform integrates ICAP (Internet Content Adaptation Protocol) to scan and validate user-uploaded files and conversation content for security, protecting against malware and inappropriate content.

## 1. What Is ICAP?

ICAP (Internet Content Adaptation Protocol) is a lightweight protocol for forwarding content to external services for processing, such as virus scanning, content filtering, and data loss prevention.

### 1.1 Core Value of ICAP

| Consideration       | Without Content Validation                                       | With ICAP Content Validation                                           |
| ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Security**        | Users may upload malware or inappropriate content                | Automatically scans and blocks malicious files and content             |
| **Compliance**      | Difficult to meet enterprise security policy requirements        | Integrates enterprise antivirus and DLP solutions                      |
| **Flexibility**     | Requires custom content detection logic                          | Uses a standard protocol to integrate specialized third-party services |
| **Maintainability** | Requires ongoing updates to virus signatures and detection rules | Specialized vendors maintain the detection engine                      |

### 1.2 Common Use Cases

* **File Upload Security**: Documents uploaded to the knowledge base must undergo virus scanning first
* **Conversation Content Filtering**: Detects inappropriate language and sensitive information in conversations
* **Data Loss Prevention (DLP)**: Prevents users from uploading files containing confidential information
* **Compliance Checks**: Ensures content meets regulatory requirements such as GDPR and HIPAA

***

## 2. MaiAgent ICAP Integration Architecture

```mermaid
flowchart TB
    subgraph Client["Client"]
        User["User"]
        WebChat["Web Chat Interface"]
    end
    
    subgraph MaiAgent["MaiAgent Platform"]
        API["Upload API"]
        Queue["Processing Queue"]
        ICAP_Client["ICAP Client"]
        DB[("Database")]
        Storage[("File Storage")]
    end
    
    subgraph ICAP_Service["ICAP Service"]
        Scanner["Antivirus Engine"]
        DLP["DLP Engine"]
        Filter["Content Filter"]
    end
    
    User -- "Upload File" --> WebChat
    WebChat -- "HTTP POST" --> API
    API --> Queue
    Queue --> ICAP_Client
    
    ICAP_Client <-. "ICAP REQMOD" .-> Scanner
    ICAP_Client <-. "ICAP RESPMOD" .-> DLP
    ICAP_Client <-. "ICAP OPTIONS" .-> Filter
    
    ICAP_Client -- "Validation Passed" --> Storage
    ICAP_Client -- "Record Results" --> DB
    
    ICAP_Client -. "Validation Failed<br/>Send Event" .-> WebChat
    WebChat -. "Display Error" .-> User
```

### 2.1 Core Components

* **ICAP Client**: MaiAgent's built-in ICAP protocol implementation, responsible for communicating with the ICAP server
* **ICAP Server**: A third-party content scanning service, such as an antivirus gateway from Symantec, McAfee, or Trend Micro
* **Processing Queue**: Handles file uploads and scanning tasks asynchronously to avoid blocking user operations
* **Scan Records**: Stores all scan results, including file hashes, scan times, and outcomes

### 2.2 ICAP Request Flow

```mermaid
sequenceDiagram
    participant User as User
    participant WebChat as Web Chat
    participant MaiAgent as MaiAgent API
    participant ICAP as ICAP Server
    participant Storage as File Storage
    
    User->>WebChat: Upload File
    WebChat->>MaiAgent: POST /upload
    MaiAgent->>MaiAgent: Generate File ID
    
    Note over MaiAgent,ICAP: ICAP REQMOD Request
    MaiAgent->>ICAP: REQMOD /scan HTTP/1.1<br/>Encapsulated: req-hdr=0, req-body=...
    ICAP->>ICAP: Scan File Content
    
    alt File Is Safe
        ICAP-->>MaiAgent: 200 OK (File Passed)
        MaiAgent->>Storage: Store File
        Storage-->>MaiAgent: Storage Successful
        MaiAgent-->>WebChat: 200 OK {fileId: ...}
        WebChat-->>User: Upload Successful
    else File Has Issues
        ICAP-->>MaiAgent: 403 Forbidden (Virus/Prohibited Content)
        MaiAgent->>WebChat: Socket.IO: ICAP_BLOCKED Event
        WebChat-->>User: Display Error Message
        MaiAgent->>MaiAgent: Record Scan Failure
    else ICAP Server Error
        ICAP-->>MaiAgent: 500 Internal Server Error
        MaiAgent->>WebChat: Socket.IO: ICAP_ERROR Event
        WebChat-->>User: System Error, Please Try Again Later
        MaiAgent->>MaiAgent: Write Error Log
    end
```

***

## 3. ICAP Protocol Implementation Details

### 3.1 ICAP Request Format

MaiAgent uses REQMOD (Request Modification) mode to send files to the ICAP server:

```http
REQMOD icap://icap-server.example.com/scan ICAP/1.0
Host: icap-server.example.com
Encapsulated: req-hdr=0, req-body=147
Allow: 204

POST /upload HTTP/1.1
Host: maiagent.ai
Content-Type: application/octet-stream
Content-Length: 1024

400
[Binary file content in chunked encoding]
0
```

**Key Fields**:

* **REQMOD**: Request modification mode, used to inspect content before storage
* **Encapsulated**: Describes the encapsulation format of the HTTP request
* **Allow: 204**: Tells the ICAP server it may return 204 directly if no content modification is needed
* **Chunked Encoding**: Sends file content using chunked transfer encoding

### 3.2 Chunked Transfer Encoding

MaiAgent correctly implements HTTP chunked transfer encoding:

```
Chunked Transfer Format:
<Data size (hexadecimal)>\r\n
<Data content>\r\n
...
0\r\n\r\n  (End marker)
```

**Why Is Correct Chunked Encoding Necessary?**

* ICAP requires HTTP chunked transfer encoding to transmit request and response bodies
* Incorrect encoding prevents the ICAP server from parsing file content correctly
* MaiAgent corrected the hexadecimal representation of chunk sizes to ensure compatibility with the ICAP standard

### 3.3 ICAP Response Handling

The ICAP server may return the following responses:

| Status Code            | Meaning                                                  | MaiAgent Handling                                              |
| ---------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| **200 OK**             | Content has been inspected or modified                   | Accepts the modified content (if any) and stores the file      |
| **204 No Content**     | No content modification is needed                        | Stores the original file directly                              |
| **403 Forbidden**      | Content is prohibited (for example, it contains a virus) | Rejects storage and sends an ICAP\_BLOCKED event to the client |
| **500 Internal Error** | ICAP server error                                        | Logs the error and sends an ICAP\_ERROR event to the client    |

***

## 4. WebChat Integration

When the ICAP scan completes, the system immediately notifies the user of the result:

* **File Blocked**: Displays a user-friendly error message explaining why the file was rejected (for example, a virus was detected)
* **System Error**: Prompts the user to try again later and writes an error log

### User Experience Improvements

* **Immediate Feedback**: Displays a "Scanning" status immediately after a file is uploaded
* **Progress Indicator**: Displays a progress bar during large file uploads
* **User-Friendly Error Messages**: Explains why a file was rejected in easy-to-understand language
* **Retry Mechanism**: Offers an option to upload again if the error is temporary

***

## 5. Scan Record Management

### 5.1 Record Storage

MaiAgent stores detailed records of all ICAP scans:

Each scan record contains the following information:

| Field             | Description                                        |
| ----------------- | -------------------------------------------------- |
| File ID           | Unique identifier of the scanned file              |
| File Name         | Original file name                                 |
| File Hash         | SHA-256 hash used to verify file integrity         |
| Scan Result       | PASS (passed), BLOCKED (blocked), ERROR (error)    |
| Scan Reason       | Specific reason recorded when a file is blocked    |
| ICAP Server       | Address of the ICAP server that performed the scan |
| Scan Time         | Timestamp of the scan                              |
| User/Organization | User who initiated the scan and their organization |

### 5.2 Expired Record Cleanup

MaiAgent implements an automatic cleanup mechanism that periodically deletes expired scan records:

The system automatically removes scan records that exceed the retention period through a scheduled background task.

**Cleanup Policy**:

* **Retention Period**: Uses the organization's ICAP "Record Retention Days" setting, which defaults to 30 days; 0 means records are retained permanently
* **Scope**: Retention is configured per organization, and the same period applies to all scan records within that organization

***

## 6. Configuration and Deployment

### 6.1 ICAP Server Configuration

MaiAgent configures ICAP per organization through system administration; the management console has no configuration screen. To enable or adjust ICAP, contact your MaiAgent representative and provide the ICAP server information. Each organization can configure the following settings:

| Setting               | Description                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ICAP Server URL       | Connection URL of the ICAP service; the connection can be tested during configuration                                                                           |
| Enabled               | Scanning runs only when enabled. MaiAgent must also enable ICAP checks for the model used by the Agent; both settings must be enabled for checks to take effect |
| Block Message         | Message shown to users when content is intercepted                                                                                                              |
| Record Retention Days | Retention period for scan records; defaults to 30 days, with 0 meaning permanent retention                                                                      |

### 6.2 Supported ICAP Services

MaiAgent is compatible with the following major ICAP services:

* **Symantec Protection Engine**: Enterprise antivirus and content filtering
* **McAfee Web Gateway**: Gateway-level content scanning
* **Trend Micro IWSVA**: Integrated web security and content scanning
* **Kaspersky Scan Engine**: Kaspersky's ICAP scanning engine
* **ClamAV (via c-icap)**: Open-source antivirus solution

### 6.3 Performance Considerations

To maintain system performance, we recommend:

* **Asynchronous Scanning**: Scan large files through background tasks without blocking upload responses
* **Caching**: Cache scan results for identical files (with the same hash)
* **ICAP Connection Pool**: Maintain persistent connections to the ICAP server to reduce connection overhead
* **Load Balancing**: Distribute the scanning load across multiple ICAP server instances

***

## 7. Technical Advantages of MaiAgent ICAP Integration

### 7.1 Security Advantages

* **Multilayer Protection**: Scans files before storage to guard against malicious content
* **Immediate Blocking**: Blocks threats as soon as they are detected, preventing storage in the system
* **Specialized Engines**: Integrates industry-leading antivirus and DLP engines
* **Complete Records**: Keeps detailed records of all scanning activity for security audits

### 7.2 Compliance Advantages

* **Standard Protocol**: Uses the industry-standard ICAP protocol for easy integration with existing enterprise security infrastructure
* **Audit Trail**: Complete scan records meet compliance requirements
* **Flexible Configuration**: Adjusts scanning policies to meet the compliance needs of different industries
* **Data Protection**: Supports DLP engines to prevent sensitive data leaks

### 7.3 Operational Advantages

* **Decoupled Architecture**: Separates ICAP scanning logic from the application for easier maintenance
* **Horizontal Scaling**: Easily adds ICAP servers to handle more scanning requests
* **Centralized Management**: Enterprises can use existing ICAP infrastructure to manage content scanning across all applications
* **Detailed Logs**: Complete scan logs support troubleshooting and performance optimization

***

## 8. Related Documentation

* [AI Security Guardrails](/tech/en/advanced-genai-tech/guardrails.md) - Learn about MaiAgent's multilayer security strategy
* [File Upload and Knowledge Base Management](https://docs.maiagent.ai/km/km-basic-settings)

### Reference Links

* [ICAP RFC 3507](https://datatracker.ietf.org/doc/html/rfc3507)
* [Chunked Transfer Encoding (RFC 7230)](https://datatracker.ietf.org/doc/html/rfc7230#section-4.1)
* [Open ICAP Forum](https://www.icap-forum.org/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/advanced-genai-tech/icap-content-validation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.