FitConnect.VirusScanning 3.2.4

FitConnect.VirusScanning

Virus scanning module for the FIT-Connect .NET SDK.

Features

• Multiple Scanner Implementations:

  • ClamAV Daemon (TCP socket connection)
  • ClamAV Process (command-line execution)
  • ICAP (Internet Content Adaptation Protocol - RFC 3507)
  • NoOp (for testing/disabled scanning)

• Automatic Integration: Scans attachments automatically during submission

• Configurable: Flexible configuration options for different environments

• Async/Await: Fully asynchronous API

Installation

The virus scanning module is part of the FIT-Connect SDK. Add it to your client:

using FitConnect.VirusScanning;

// Default (NoOp - no actual scanning)
client.AddVirusScanning();

// ClamAV Daemon
client.AddClamAVDaemonScanning("localhost", 3310);

// ClamAV Process
client.AddClamAVProcessScanning("/usr/bin/clamscan");

// ICAP Scanner
client.AddIcapScanning("icap.example.com", 1344, "avscan");

// Custom configuration
var options = new VirusScanningOptions
{
    Mode = VirusScannerMode.Icap,
    IcapOptions = new IcapOptions
    {
        Host = "icap.example.com",
        Port = 1344,
        ServiceName = "avscan",
        Mode = "RESPMOD"
    },
    FailOnScanError = true,
    MaxFileSizeBytes = 100_000_000 // 100 MB
};
client.AddVirusScanning(options);

ClamAV Setup

ClamAV Daemon (Recommended for Production)

1. Install ClamAV:

   # Ubuntu/Debian
   sudo apt-get install clamav clamav-daemon
   
   # macOS
   brew install clamav
   

2. Start the daemon:

   # Ubuntu/Debian
   sudo systemctl start clamav-daemon
   
   # macOS
   clamd
   

3. Configure your application:

   client.AddClamAVDaemonScanning("localhost", 3310);
   

ClamAV Process (Alternative)

1. Install ClamAV (same as above)

2. Configure your application:

   client.AddClamAVProcessScanning("/usr/bin/clamscan");
   

ICAP Setup

ICAP (Internet Content Adaptation Protocol) allows you to use professional security appliances or specialized ICAP servers for virus scanning.

1. Ensure your ICAP server is reachable and configured (e.g., Symantec Protection Engine, McAfee Web Gateway, or a custom ICAP server).

2. Configure your application:

   client.AddIcapScanning("icap-server.internal", 1344, "avscan");
   

Configuration Options

VirusScanningOptions

• Mode: Scanner mode (ClamAVDaemon, ClamAVProcess, Icap, NoOp)
• DaemonOptions: ClamAV daemon configuration
• ProcessOptions: ClamAV process configuration
• IcapOptions: ICAP configuration
• FailOnScanError: Throw exception on scan errors (default: true)
• MaxFileSizeBytes: Maximum file size to scan (default: 100 MB)

ClamAVDaemonOptions

• Host: ClamAV daemon hostname (default: localhost)
• Port: ClamAV daemon port (default: 3310)
• ReadBufferSize: Buffer size for streaming (default: 2048)
• TimeoutSeconds: Operation timeout (default: 30)

ClamAVProcessOptions

• ExecutablePath: Path to clamscan (default: /usr/bin/clamscan)
• TempDirectory: Temp directory for files (default: system temp)
• TimeoutSeconds: Process timeout (default: 60)

IcapOptions

• Host: ICAP server hostname (default: localhost)
• Port: ICAP server port (default: 1344)
• ServiceName: ICAP service name (default: avscan)
• Mode: ICAP mode (RESPMOD or REQMOD, default: RESPMOD)
• ReadBufferSize: Buffer size for streaming (default: 2048)
• TimeoutSeconds: Operation timeout (default: 30)

Usage Examples

Basic Usage

// Add virus scanning to client
client.AddClamAVDaemonScanning();

// Attachments are automatically scanned during submission
var submission = new SendableSubmission
{
    // ... submission data ...
};

await sender.SendAsync(submission); // Scans attachments automatically

Manual Scanning with MalwareScanner

using FitConnect.VirusScanning.Utilities;

var scanner = new ClamAVDaemonAdapter();
var malwareScanner = new MalwareScanner(scanner, VirusScannerMode.ClamAVDaemon);

// Scan data
var dataResult = await malwareScanner.ScanDataAsync(dataBytes);
if (dataResult.Status == VirusScanStatus.Infected)
{
    Console.WriteLine($"Malware detected: {dataResult.Signature}");
}

// Scan attachments
var attachmentResult = await malwareScanner.ScanAttachmentsAsync(attachments);

Custom Scanner Implementation

public class CustomVirusScanner : IVirusScannerAdapter
{
    public async Task<VirusScanResult> ScanAsync(
        Stream data, 
        string fileName, 
        CancellationToken cancellationToken)
    {
        // Your custom scanning logic
        return new VirusScanResult(
            VirusScanStatus.Clean,
            "CustomScanner",
            null,
            TimeSpan.Zero,
            "Scan completed"
        );
    }

    public Task<bool> IsAvailableAsync(CancellationToken cancellationToken)
    {
        return Task.FromResult(true);
    }

    public Task<VirusScanEngineInfo?> GetEngineInfoAsync(CancellationToken cancellationToken)
    {
        return Task.FromResult<VirusScanEngineInfo?>(
            new VirusScanEngineInfo("CustomScanner", "1.0.0"));
    }
}

// Use custom scanner
var customScanner = new CustomVirusScanner();
var options = new VirusScanningOptions { Mode = VirusScannerMode.NoOp };
var service = new VirusScanningService(customScanner, options);
client.AddVirusScanning(service);

Exception Handling

The module throws two types of exceptions:

• FitConnectAttachmentVirusDetectedException: Malware detected in attachment
• FitConnectVirusScanFailedException: Scan failed (only if FailOnScanError = true)

try
{
    await sender.SendAsync(submission);
}
catch (FitConnectAttachmentVirusDetectedException ex)
{
    Console.WriteLine($"Virus detected: {ex.Message}");
}
catch (FitConnectVirusScanFailedException ex)
{
    Console.WriteLine($"Scan failed: {ex.Message}");
}

Testing

For testing, use the NoOp scanner:

// In test setup
client.AddVirusScanning(); // Uses NoOp by default

// Or explicitly
var options = VirusScanningOptions.Default();
client.AddVirusScanning(options);

EICAR Test File

To test malware detection, use the EICAR test file:

var eicarString = "X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*";
var eicarBytes = Encoding.ASCII.GetBytes(eicarString);

var attachment = new Attachment(eicarBytes, "eicar.txt", "text/plain");
// This will throw FitConnectAttachmentVirusDetectedException

Performance Considerations

• ClamAV Daemon: Faster, recommended for production (persistent process)
• ClamAV Process: Slower, spawns new process for each scan
• File Size Limit: Configure MaxFileSizeBytes to skip large files
• Timeouts: Adjust timeout settings based on expected file sizes

Troubleshooting

ClamAV Daemon Not Available

Error: Virus scanner is not available

Solution: Ensure ClamAV daemon is running:

sudo systemctl status clamav-daemon
# or
ps aux | grep clamd

Connection Refused

Error: Connection refused to localhost:3310

Solution: Check ClamAV daemon configuration:

sudo nano /etc/clamav/clamd.conf
# Ensure TCPSocket 3310 is uncommented

Scan Timeout

Error: Connection to ClamAV daemon timed out

Solution: Increase timeout in options:

var options = new VirusScanningOptions
{
    DaemonOptions = new ClamAVDaemonOptions
    {
        TimeoutSeconds = 120 // Increase timeout
    }
};

Architecture

IVirusScannerAdapter (Interface)
├── ClamAVDaemonAdapter (TCP socket)
├── LocalClamAVProcessAdapter (Process execution)
├── IcapAdapter (RFC 3507 ICAP protocol)
└── NoOpVirusScannerAdapter (Testing)

License

Part of the FIT-Connect SDK, licensed under EUPL.