Spring Boot File Upload with attachmentAV Malware Scanning

This example demonstrates how to integrate malware and virus scanning into a Spring Boot file upload application using the attachmentAV API.

Problem Context

File uploads are a common vector for malware distribution. When users upload files to your application, you need to scan them for viruses and malware before processing or storing them. This prevents infected files from compromising your system or being distributed to other users.

attachmentAV provides a REST API that scans files for malware and viruses in real-time. This example shows how to integrate the attachmentAV API into a Spring Boot application to scan uploaded files before accepting them.

Architecture

    ┌─────────────────────┐
    │                     │
    │    Web Browser      │
    │                     │
    └──────────┬──────────┘
               │
               │ HTTP POST
               │
               ▼
    ┌─────────────────────┐
    │                     │
    │   Spring Boot       │
    │   Application       │
    │                     │
    └──────────┬──────────┘
               │
               │ HTTPS POST
               │
               ▼
    ┌─────────────────────┐
    │                     │
    │  attachmentAV API   │
    │                     │
    └─────────────────────┘

Solution

This application provides two file upload capabilities:

1. Single File Upload

• Users upload one file at a time through a simple form
• File is immediately sent to the attachmentAV API for scanning
• Results (clean, infected, or failed) are displayed to the user
• Infected files are rejected with the virus/malware name shown

2. Multiple Files Upload

• Users can select and upload multiple files simultaneously
• Files are scanned concurrently with a maximum of 3 concurrent API calls to the attachmentAV API
• This is achieved using a fixed thread pool (ExecutorService with 3 threads)
• Results are aggregated and displayed showing counts of:
  • Clean files
  • Infected files (with virus names)
  • Failed scans

Key Features

• Concurrent scanning: Multiple files are scanned in parallel (max 3 at a time) for better performance
• Configurable file size limits: Max file size and request size can be adjusted in application.properties
• Error handling: Proper error messages for infected files, scan failures, and API errors
• Clean UI: Simple white-background interface with two forms side by side

Getting Started

Prerequisites

• Java 17 or later
• Maven 3.6+
• attachmentAV API key (get one at attachmentav.com)

Configuration

1. Set your attachmentAV API key as an environment variable:

export ATTACHMENTAV_API_KEY=your-api-key-here

2. Adjust file upload limits (optional):

Edit src/main/resources/application.properties:

# Maximum size for a single file
spring.servlet.multipart.max-file-size=10MB

# Maximum size for the entire request (important for multi-file uploads)
spring.servlet.multipart.max-request-size=50MB

Running the Application

1. Clone the repository:

git clone https://github.com/widdix/attachmentav-example-java-spring-boot.git
cd attachmentav-spring-boot-file-upload-example

2. Run with Maven:

./mvnw spring-boot:run

Or on Windows:

mvnw.cmd spring-boot:run

3. Build and run the JAR:

./mvnw clean package
java -jar target/uploading-files-complete-0.0.1-SNAPSHOT.jar

4. Access the application:

Open your browser and navigate to:

http://localhost:8080

You'll see two upload forms:

• Left: Single file upload
• Right: Multiple files upload

Testing

Upload test files to verify the integration:

1. Clean file: Upload a regular text or image file

   • Expected: "File has been scanned and is clean!"

2. EICAR test file: Download the EICAR test file to test virus detection

   • Expected: "File is infected: EICAR-Test-File"

3. Multiple files: Select multiple files and upload them together

   • Expected: Summary showing counts of clean, infected, and failed scans

Project Structure

src/
├── main/
│   ├── java/com/example/uploadingfiles/
│   │   ├── FileUploadController.java         # Main controller with upload endpoints
│   │   ├── UploadingFilesApplication.java    # Spring Boot application entry point
│   │   └── attachmentav/
│   │       ├── AttachmentAVService.java      # Service for attachmentAV API calls
│   │       └── AttachmentAVException.java    # Custom exception
│   └── resources/
│       ├── application.properties             # Configuration
│       └── templates/
│           └── uploadForm.html                # Upload form UI

How It Works

Single File Flow

1. User selects a file and clicks "Scan File"
2. File is sent to / endpoint as multipart/form-data
3. FileUploadController.handleFileUpload() receives the file
4. AttachmentAVService.scanFile() sends the file to attachmentAV API
5. API returns scan result (clean, infected, or no)
6. User sees result message

Multiple Files Flow

1. User selects multiple files and clicks "Scan Files"
2. Files are sent to /upload-multiple endpoint
3. FileUploadController.handleMultipleFileUpload() receives files
4. Each file is submitted to a thread pool (max 3 concurrent scans)
5. CompletableFuture manages async scanning
6. Results are collected and aggregated
7. User sees summary with counts of clean/infected/failed files

Concurrent Scanning Implementation

// Fixed thread pool ensures max 3 concurrent API calls -> can be adjusted depending on attachmentAV subscription
private static final int MAX_CONCURRENT_REQUESTS = 3;
private final ExecutorService executorService = Executors.newFixedThreadPool(MAX_CONCURRENT_REQUESTS);

// Each file is scanned asynchronously
CompletableFuture<FileResult> future = CompletableFuture.supplyAsync(() -> {
    ScanResult scanResult = attachmentAVService.scanFile(file);
    return new FileResult(file.getOriginalFilename(), scanResult, null);
}, executorService);

API Reference

attachmentAV API Endpoint

• URL: https://eu.developer.attachmentav.com/v1/scan/sync/binary
• Method: POST
• Headers:
  • x-api-key: Your API key
  • Content-Type: application/octet-stream
  • Content-Length: File size in bytes
• Body: Binary file content
• Response: JSON with scan results

Example response:

{
  "status": "clean",
  "finding": null
}

Or for infected files:

{
  "status": "infected",
  "finding": "EICAR-Test-File"
}

License

This project is open source and available under the terms specified in the repository.

Resources

• attachmentAV Documentation
• Spring Boot Documentation
• EICAR Test File - Safe file to test antivirus detection