Java ClamAV Client Library

A simple yet efficient Java client library for the ClamAV antivirus daemon.

Pre-requisites

This library requires a JDK version 8.

Installing

With Maven

Add this dependency to the <dependencies> section of your pom.xml file:

<dependency>
    <groupId>xyz.capybara</groupId>
    <artifactId>clamav-client</artifactId>
    <version>2.1.3</version>
</dependency>

With Gradle

Add this dependency to the dependencies section of your build.gradle file:

compile 'xyz.capybara:clamav-client:2.1.3'

Manually

Alternatively, you can download the jar file of this library directly from the Maven Central Repository website and add it to the classpath of your application: Download page.

Usage

After the library has been added to your build, start by creating an instance:

ClamavClient client = new ClamavClient("localhost");

By default, the client will try to connect to the port 3310 which is the default ClamAV daemon port.

If your ClamAV daemon listens to another port, you can indicate it with:

ClamavClient client = new ClamavClient("localhost", 3311);

Be careful if you intend to use the functionality of scan of a file/directory on the server filesystem and if the ClamAV daemon is running on an OS having a different path separator than the OS on which your Java application is running. (for example, if your Java application is running on a Windows platform but the ClamAV daemon is running on a remote UNIX platform)

You will then have to explicitly indicate the target server platform to the client library at instantiation:

ClamavClient client = new ClamavClient("localhost", Platform.UNIX);

// Or with an alternate port number:
ClamavClient client = new ClamavClient("localhost", 3311, Platform.UNIX);

By default, the chosen file separator will be the one of the platform your Java application is running on.

Commands

Scan commands

ScanResult scan(InputStream inputStream, Integer chunkSize)

Scans an InputStream and sends a response as soon as a virus has been found. The chunkSize can be used to control the size of the chunk sent to ClamAV. Defaults to 2048 bytes

ScanResult scan(Path path)

Scans a file/directory on the filesystem of the ClamAV daemon and sends a response as soon as a virus has been found.

ScanResult scan(Path path, boolean continueScan)

Scans a file/directory on the filesystem of the ClamAV daemon and may continue the scan to the end even if a virus has been found, depending on the continueScan argument.

ScanResult parallelScan(Path path)

Scans a file/directory on the filesystem of the ClamAV daemon and will continue the scan to the end even if a virus has been found. This method may improve performances on SMP systems by performing a multi-threaded scan.

Scan result

The ScanResult object returned by the scan commands can be of two types:

OK: if no viruses have been found,
VirusFound: if viruses have been found. Information about the infected files are stored in the foundViruses member map filled as following:

Key: infected file path
Value: list of viruses found in the file

Usage of the scan result

In Java:

if (scanResult instanceof ScanResult.OK) {
    // OK
} else if (scanResult instanceof ScanResult.VirusFound) {
    Map<String, Collection<String>> viruses = ((ScanResult.VirusFound) scanResult).getFoundViruses();
}

The same code in Kotlin would be much more readable, thanks to the when keyword and the smart-casting ability of the language:

when (scanResult) {
    is ScanResult.OK -> // OK
    is ScanResult.VirusFound -> scanResult.foundViruses
}

Admin commands

void reloadVirusDatabases()

Triggers the virus databases reloading by the ClamAV daemon.

void shutdownServer()

Immediately shutdowns the ClamAV daemon.

Other commands

void ping()

Pings the ClamAV daemon. If a correct response has been received, the method simply returns. Otherwise, a ClamavException exception is thrown.

String version()

Requests the version of the ClamAV daemon.

String stats()

Requests stats from the ClamAV daemon.

Building from sources

To build this library from its sources, an installation of Maven is required. Clone this repository and launch its build with the Maven command:

mvn clean package

If the build is successful, the jar file of the library will be found into the target directory.

Contributing

Feel free to fork this repository and submit pull requests :)

You can also submit issues in case of bugs or feature requests.

Licensing

The code in this project is licensed under MIT license. The content of the license can be found in the LICENSE file under the root of this repository.

cdarras / clamav-client