https://github.com/quarkiverse/quarkus-antivirus
Virus scan files using ClamAV or VirusTotal
https://github.com/quarkiverse/quarkus-antivirus
antivirus clamav file quarkus-extension security virustotal
Last synced: 6 months ago
JSON representation
Virus scan files using ClamAV or VirusTotal
- Host: GitHub
- URL: https://github.com/quarkiverse/quarkus-antivirus
- Owner: quarkiverse
- License: apache-2.0
- Created: 2023-10-22T22:33:05.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T11:38:13.000Z (7 months ago)
- Last Synced: 2025-04-01T12:33:08.860Z (7 months ago)
- Topics: antivirus, clamav, file, quarkus-extension, security, virustotal
- Language: Java
- Homepage: https://www.clamav.net/
- Size: 361 KB
- Stars: 11
- Watchers: 6
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Quarkus Antivirus
[](https://search.maven.org/artifact/io.quarkiverse.antivirus/quarkus-antivirus)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/quarkiverse/quarkus-antivirus/actions/workflows/build.yml)
A Quarkus extension that lets you scan files for viruses using a pluggable engine architecture.
Out of the box these engines are supported by this extension:
- [ClamAV](https://www.clamav.net/) which is a Linux Native antivirus server
- [VirusTotal](https://www.virustotal.com/) which is a REST API to check the Hash of a file to see if it has already been reported for viruses
- [ICAP](https://github.com/toolarium/toolarium-icap-client) The Internet Content Adaptation Protocol (ICAP) is widely used to enhance network security by enabling communication between clients and servers for tasks such as antivirus scanning and data loss prevention. Several products support ICAP scanning, either as ICAP servers providing scanning services or as clients integrating ICAP capabilities. Examples include:
- [MetaDefender ICAP Server](https://www.opswat.com/products/metadefender) by OPSWAT
- [Clearswift Secure ICAP Gateway](https://emailsecurity.fortra.com/products/secure-icap-gateway) by Clearswift
- [ClamAV ICAP Server](https://squidclamav.darold.net/documentation.html) by ClamAV
- [OpenSCAP ICAP Server](https://www.open-scap.org/) by OpenSCAP
- [Cloudmersive ICAP Anti-Virus Scanning Server](https://cloudmersive.com/icap-anti-virus-scan-server) by Cloudmersive
- [Broadcom ICAP Server](https://techdocs.broadcom.com/us/en/vmware-security-load-balancing/avi-load-balancer/avi-load-balancer/30-1/vmware-avi-load-balancer-configuration-guide/load-balancing-overview/internet-content-adaptation-protocol.html) by Broadcom
- [Kaspersky ICAP Server](https://support.kaspersky.com/ScanEngine/1.0/en-US/179823.htm) by Kaspersky
## Getting started
Read the full [Antivirus documentation](https://docs.quarkiverse.io/quarkus-antivirus/dev/index.html).
### Prerequisite
- Create or use an existing Quarkus application
- Add the Antivirus extension
### Installation
Create a new Antivirus project (with a base Antivirus starter code):
- With [code.quarkus.io](https://code.quarkus.io/?a=Antivirus-bowl&j=17&e=io.quarkiverse.antivirus%3Aquarkus-antivirus)
- With the [Quarkus CLI](https://quarkus.io/guides/cli-tooling):
```bash
quarkus create app antivirus-app -x=io.quarkiverse.antivirus:quarkus-antivirus
```
Or add to you pom.xml directly:
```xml
io.quarkiverse.antivirus
quarkus-antivirus
{project-version}
```
## Configuration
Now that you configured your POM to use the service, now you need to configure which scanner(s) you want to use in `application.properties`:
### ClamAV
[ClamAV](https://www.clamav.net/) is an open source Linux based virus scanning engine.
If you don't set a host `quarkus.antivirus.clamav.host` a DevService will start a ClamAV instance for you on a dynamic free port, so you can test locally during development.
```properties
quarkus.antivirus.clamav.enabled=true
```
#### ClamAV Health Check
If you are using the `quarkus-smallrye-health` extension,
quarkus-vault can add a readiness health check to validate the connection to the ClamAV server.
If enabled (by default) and the extension is present,
when you access the `/q/health/ready` endpoint of your application you will have information about the connection validation status.
You can disable this behavior by setting the property `quarkus.antivirus.clamav.health.enabled` to `false` in your application.properties.
### VirusTotal
[VirusTotal](https://www.virustotal.com/) is a REST API that analyses suspicious files to detect malware using over 70 antivirus scanners. VirusTotal checks the hash of a file to see if it has been scanned and what the results are. You can set the threshold of how many of the 70+ engines you want to report the file as malicious before you consider it a malicious file using the `minimum-votes` property.
```properties
quarkus.antivirus.virustotal.enabled=true
quarkus.antivirus.virustotal.key=
quarkus.antivirus.virustotal.minimum-votes=1
```
### ICAP
The Internet Content Adaptation Protocol (ICAP) is widely used to enhance network security by enabling communication between clients and servers for tasks such as antivirus scanning and data loss prevention. Several products support ICAP scanning, either as ICAP servers providing scanning services or as clients integrating ICAP capabilities.
To test an ICAP server you can use ClamAV ICAP Server by running the following docker command:
```bash
docker run --rm --name icap-server -p 1344:1344 toolarium/toolarium-icap-calmav-docker:0.0.1
```
Then configure the ICAP server in your `application.properties`:
```properties
quarkus.antivirus.icap.enabled=true
quarkus.antivirus.icap.host=localhost
quarkus.antivirus.icap.port=1344
quarkus.antivirus.icap.service=srv_clamav
```
## Usage
Simply inject the `Antivirus` service, and it will run the scan against all configured services. It works against `InputStream` so it can be used in any Quarkus application it is not constrained to REST applications only.
```java
@Path("/antivirus")
@ApplicationScoped
public class AntivirusResource {
@Inject
Antivirus antivirus;
@PUT
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.TEXT_PLAIN)
@Path("/upload")
public Response upload(@MultipartForm @Valid final UploadRequest fileUploadRequest) {
final String fileName = fileUploadRequest.getFileName();
final InputStream data = fileUploadRequest.getData();
try {
// copy the stream to make it resettable
final ByteArrayInputStream inputStream = new ByteArrayInputStream(
IOUtils.toBufferedInputStream(data).readAllBytes());
// scan the file and check the results
List results = antivirus.scan(fileName, inputStream);
for (AntivirusScanResult result : results) {
if (result.getStatus() != Response.Status.OK.getStatusCode()) {
throw new WebApplicationException(result.getMessage(), result.getStatus());
}
}
// write the file out to disk
final File tempFile = File.createTempFile("fileName", "tmp");
IOUtils.copy(inputStream, new FileOutputStream(tempFile));
} catch (IOException e) {
throw new BadRequestException(e);
}
return Response.ok().build();
}
}
```
## Pluggable
We can't anticipate every antivirus engine out there and some may be proprietary. However, the architecture is designed to be pluggable, so you can plug your own engine in. Simply produce a bean that extends the `AntivirusEngine` interface and it will be picked up and used.
```java
@ApplicationScoped
public class MyCustomEngine implements AntivirusEngine {
@Override
public boolean isEnabled() {
return true;
}
@Override
public AntivirusScanResult scan(final String filename, final InputStream inputStream) {
// scan your file here
}
}
```
## 🧑💻 Contributing
- Contribution is the best way to support and get involved in community!
- Please, consult our [Code of Conduct](./CODE_OF_CONDUCT.md) policies for interacting in our community.
- Contributions to `quarkus-antivirus` Please check our [CONTRIBUTING.md](./CONTRIBUTING.md)
### If you have any idea or question 🤷
- [Ask a question](https://github.com/quarkiverse/quarkus-antivirus/discussions)
- [Raise an issue](https://github.com/quarkiverse/quarkus-antivirus/issues)
- [Feature request](https://github.com/quarkiverse/quarkus-antivirus/issues)
- [Code submission](https://github.com/quarkiverse/quarkus-antivirus/pulls)
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Melloware
🚧 💻
Sauli Ketola
⚠️ 🤔
Geoffrey GREBERT
💻
Negoita Silviu
🤔 🐛
Martin Stefanko
💬
Richard Bischof
🐛
Patrick
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!