🦠 FileScan — File Upload & Virus Scanning Service

📖 Overview

FileScan is a Spring Boot–based web application that allows users to upload files, automatically scans them for viruses using ClamAV, and processes them based on the scan results. It supports:

• File upload
• Real-time virus scanning via ClamAV
• Quarantining infected files
• Hashing uploaded files (SHA-256)
• Async file processing for better performance

---

🚀 Features

✅ Upload files via REST API ✅ Scan files using ClamAV (AntiVirus engine) ✅ Quarantine infected files automatically ✅ Store scan results in a database ✅ Asynchronous scanning with Spring’s @Async ✅ File hash generation for integrity checks

---

🧩 Technologies Used

Component	Technology
Backend Framework	Spring Boot 3
Language	Java 17+
Database	JPA / Hibernate (MySQL or H2)
Antivirus Engine	ClamAV
Build Tool	Maven
Async Execution	Spring Async + ThreadPoolTaskExecutor

---

⚙️ Project Structure

com.project.filescan
├── controller
│   └── FileUploadController.java        # Handles file upload REST endpoint
│
├── entity
│   ├── UploadedFile.java                # Represents uploaded file metadata
│   └── FileScanResult.java              # Represents virus scan result
│
├── service
│   ├── ClamAVService.java               # Communicates with ClamAV
│   └── FileScanResultService.java       # Handles scanning and processing logic
│
├── enums
│   ├── ScanStatus.java                  # CLEAN, INFECTED, FAILED, PENDING
│   └── ActionTaken.java                 # NONE, BLOCKED, QUARANTINED
│
├── repository
│   ├── FileScanResultRepository.java    # JPA repository for scan results
│   └── UploadedFileRepository.java      # JPA repository for uploaded files
│
└── AsyncConfig.java                     # Enables asynchronous scanning

---

🧠 How It Works

1. User uploads a file to /upload

2. The file is temporarily saved in the uploads directory

3. The service sends the file stream to ClamAV for scanning

4. Depending on the result:

   • ✅ CLEAN → File remains in uploads/
   • ⚠️ INFECTED → File is moved to quarantine/
   • ❌ FAILED → File is deleted and logged

5. The result is saved in the database and returned in the response.

---

📡 API Endpoint

POST /upload

Request:

curl -X POST http://localhost:8080/upload \
  -F "file=@/path/to/your/file.txt"

Response (Example):

{
  "message": "File report.pdf processed. Status: CLEAN"
}

Infected File Example:

{
  "message": "File malicious.exe processed. Status: INFECTED. Quarantined at: /resources/quarantine/malicious_1722332020000"
}

---

🧰 Configuration

application.properties

clamav.host=localhost
clamav.port=3310

spring.datasource.url=jdbc:mysql://localhost:3306/filescan
spring.datasource.username=root
spring.datasource.password=yourpassword
spring.jpa.hibernate.ddl-auto=update

Directory Paths

• Uploads: src/main/resources/uploads
• Quarantine: src/main/resources/quarantine

(Make sure these directories exist or are created automatically by the app.)

---

🧪 Running the Project

Prerequisites

• Java 17+
• Maven 3+
• ClamAV running locally (or via Docker)

Start ClamAV via Docker

docker run -d --name clamav -p 3310:3310 clamav/clamav:latest

Run the App

mvn spring-boot:run

---

🧾 Example Response Flow

File	Status	Action Taken	Location
safe.txt	CLEAN	NONE	/uploads/safe.txt
virus.exe	INFECTED	QUARANTINED	/quarantine/virus.exe_12345
corrupt.zip	FAILED	BLOCKED	Deleted

---

Would you like me to include setup instructions for ClamAV on Windows or Docker Compose support in the README too?