### Commit Message Examples

Source: https://github.com/ajilach/clamav-rest/blob/master/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits format for various types of changes.

```bash
# New feature (minor bump)
git commit -m "feat: add support for scanning ZIP archives"
```

```bash
# Bug fix (patch bump)
git commit -m "fix: resolve memory leak in scan handler"
```

```bash
# Bug fix with more details (patch bump)
git commit -m "fix: prevent race condition in concurrent scans

Added mutex to protect shared scan state when multiple
requests are processed simultaneously."
```

```bash
# Breaking change (major bump)
git commit -m "feat: redesign REST API endpoints

BREAKING CHANGE: All endpoints now use /api/v3 prefix instead of /api/v2"
```

```bash
# Documentation update (no bump)
git commit -m "docs: update installation instructions"
```

```bash
# Dependency update (no bump)
git commit -m "chore: update clamd dependency to v2.1.0"
```

--------------------------------

### Run ClamAV-REST Docker Image

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Starts the ClamAV-REST Docker container in detached mode, exposing HTTP and HTTPS ports. Ensure Docker is installed and running.

```bash
docker run -p 9000:9000 -p 9443:9443 -itd --name clamav-rest ajilaag/clamav-rest
```

--------------------------------

### GET /scanFile?path=<absolute-path> — Scan a file already on disk

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Scans a file located at an absolute path within the container's filesystem using the SCAN protocol. Returns a single JSON object. Useful for files in mounted volumes.

```APIDOC
## GET /scanFile

### Description
Scans a file that already exists on the container's filesystem at a specified absolute path. It uses the SCAN protocol and returns a single JSON object.

### Method
GET

### Endpoint
/scanFile

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path to the file on the container's filesystem.

### Request Example
```bash
curl -i "http://localhost:9000/scanFile?path=/clamav/tmp/uploads/report.pdf"
```

### Response
#### Success Response (200 OK)
- **Status** (string) - "OK" if the file is clean.
- **Description** (string) - Empty if the file is clean.
- **FileName** (string) - The absolute path of the scanned file.

#### Error Response (412 Precondition Failed)
Returned if the specified path does not point to an existing file.

### Response Example
```json
{"Status":"OK","Description":"","FileName":"/clamav/tmp/uploads/report.pdf"}
```
```

--------------------------------

### Pull Latest ClamAV REST Docker Image

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Use this command to pull the most recent stable release of the clamav-rest Docker image from Docker Hub. Ensure Docker is installed and running.

```bash
docker pull ajilaag/clamav-rest
```

--------------------------------

### Build and Run Test Suite

Source: https://github.com/ajilach/clamav-rest/blob/master/CONTRIBUTING.md

Build a Docker image for the test suite and run it to verify your changes.

```bash
# Build and run the test suite
docker build . -f Dockerfile.test -t clamav-rest:test
docker run --rm clamav-rest:test
```

--------------------------------

### Build and run tests with Docker

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Build the test Docker image and run the end-to-end tests. The container will exit with a non-zero code if tests fail.

```bash
docker build -f Dockerfile.test -t clamav-rest-test .
docker run clamav-rest-test
```

--------------------------------

### Build ClamAV-REST from Source

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Build the ClamAV-REST binary locally using Go 1.26+. Specify the target operating system and architecture.

```bash
# Build locally (requires Go 1.26+)
GOOS=linux GOARCH=amd64 go build
```

--------------------------------

### Build with Nix

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Build the clamav-rest binary using Nix. The resulting binary will be located in the ./result/bin/ directory.

```bash
nix-build
```

--------------------------------

### Build Golang Binary Locally

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Compile the ClamAV-REST Go application locally for different operating systems and architectures. This is useful for development before containerization.

```bash
# For linux on amd64
GOOS=linux GOARCH=amd64 go build
```

```bash
# For macOS on arm64
GOOS=darwin GOARCH=arm64 go build
```

```bash
# For macOS on amd64
GOOS=darwin GOARCH=amd64 go build
```

```bash
# For Windows (using Git Bash or similar)
GOOS=windows GOARCH=amd64 go build
```

--------------------------------

### Provide Custom freshclam.conf (Docker)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Mount your custom freshclam.conf file to override default freshclam settings. This ignores specific environment variables related to freshclam.

```bash
docker run -p 9000:9000 \
  -v /path/to/freshclam.conf:/clamav/etc/freshclam.conf:ro \
  -itd --name clamav-rest ajilaag/clamav-rest
```

--------------------------------

### Enable HTTPS with TLS Certificates (Docker)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Mount your TLS certificate and key to enable HTTPS on port 9443. If not provided, only HTTP on port 9000 is available.

```bash
docker run -p 9000:9000 -p 9443:9443 \
  -v /path/to/server.crt:/etc/ssl/clamav-rest/server.crt:ro \
  -v /path/to/server.key:/etc/ssl/clamav-rest/server.key:ro \
  -itd --name clamav-rest ajilaag/clamav-rest
```

--------------------------------

### Scan file using HTTP/2 Prior Knowledge

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a file using the /v2/scan endpoint with HTTP/2 Prior Knowledge enabled. The server should be accessible on localhost:9000.

```bash
$ curl -i -k --http2-prior-knowledge -F "file=@clamrest.go" http://localhost:9000/v2/scan

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 59
date: Fri, 28 Feb 2025 21:49:17 GMT

[{"Status":"OK","Description":"","FileName":"clamrest.go"}]
```

--------------------------------

### Scan file using HTTP/1.1

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a file using the /v2/scan endpoint with HTTP/1.1. Ensure the server is running on localhost:9443.

```bash
$ curl -i -k --http1.1 -F "file=@clamrest.go" https://localhost:9443/v2/scan

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Feb 2025 21:49:54 GMT
Content-Length: 59

[{"Status":"OK","Description":"","FileName":"clamrest.go"}]
```

--------------------------------

### Retrieve ClamAV and signature database versions

Source: https://context7.com/ajilach/clamav-rest/llms.txt

The `/version` endpoint returns the `clamd` binary version, the loaded virus signature database version, and the last update date as a JSON object. This can be checked from inside a running container.

```bash
curl -s http://localhost:9000/version
# {"Clamav":"1.4.2","Signature":"27516","Signature_date":"Mon Dec 30 08:22:39 2024\n"}
```

```bash
docker exec clamav-rest wget -qO- http://localhost:9000/version
# {"Clamav":"1.4.2","Signature":"27516","Signature_date":"Mon Dec 30 08:22:39 2024\n"}
```

--------------------------------

### Scan File via HTTPS with cURL (Clean)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Tests the HTTPS scanning endpoint with a clean file (clamrest.go), using the -k flag for certificate validation. Expects a 200 OK response.

```bash
$ curl -i -k -F "file=@clamrest.go" https://localhost:9443/v2/scan

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Aug 2017 20:23:16 GMT
Content-Length: 33

[{ "Status": "OK", "Description": "","FileName":"clamrest.go"}]
```

--------------------------------

### Home Endpoint

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

The home endpoint returns statistics for the currently running process.

```APIDOC
## GET /

### Description
Returns stats for the currently running process.

### Method
GET

### Endpoint
/

### Response
(Response details not specified in source)
```

--------------------------------

### Scan file using HTTP/2

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a file using the /v2/scan endpoint with HTTP/2. This requires the server to be running on localhost:9443.

```bash
$ curl -i -k --http2 -F "file=@clamrest.go" https://localhost:9443/v2/scan

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 59
date: Fri, 28 Feb 2025 21:49:33 GMT

[{"Status":"OK","Description":"","FileName":"clamrest.go"}]
```

--------------------------------

### Scan File via HTTP with cURL (Clean)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Tests the HTTP scanning endpoint with a clean file (clamrest.go). Expects a 200 OK response indicating no infections were found.

```bash
$ curl -i -F "file=@clamrest.go" http://localhost:9000/v2/scan

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Aug 2017 20:23:16 GMT
Content-Length: 33

[{ "Status": "OK", "Description": "","FileName":"clamrest.go"}]
```

--------------------------------

### Run ClamAV-REST with Docker

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Quickly pull and run the ClamAV-REST Docker image. Use specific versions for production and mount TLS certificates for HTTPS.

```bash
# Pull and run — HTTP on 9000, HTTPS on 9443
docker pull ajilaag/clamav-rest
docker run -p 9000:9000 -p 9443:9443 -itd --name clamav-rest ajilaag/clamav-rest

# Pin to a specific semantic version (recommended for production)
docker run -p 9000:9000 -itd --name clamav-rest ajilaag/clamav-rest:v1.2.3

# Mount TLS certificates to enable HTTPS
docker run -p 9000:9000 -p 9443:9443 \
  -v /path/to/server.crt:/etc/ssl/clamav-rest/server.crt:ro \
  -v /path/to/server.key:/etc/ssl/clamav-rest/server.key:ro \
  -itd --name clamav-rest ajilaag/clamav-rest
```

--------------------------------

### Scan Directory by Path

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan an entire directory using ALLMATCHSCAN. This is useful for scanning multiple files within a mounted share. The response provides status for each item.

```APIDOC
## GET /scanPath

### Description
A scanning endpoint that will scan a folder using ALLMATCHSCAN. A practical example would be to mount a share into the container where you dump files into a folder, call `/scanPath` and let it scan the whole directory content, then continue processing them.

### Method
GET

### Endpoint
/scanPath

### Parameters
#### Query Parameters
- **path** (string) - Required - The full path to the directory to be scanned.

### Response
#### Success Response (200)
- **Raw** (string) - Raw output from the scan (e.g., "/folder: OK").
- **Description** (string) - A description of the threat if found.
- **Path** (string) - The path that was scanned.
- **Hash** (string) - The hash of the scanned item.
- **Size** (integer) - The size of the scanned item.
- **Status** (string) - The scanning status (e.g., "OK", "FOUND").

#### Response Example
```json
[
  {
    "Raw": "/folder: OK",
    "Description": "",
    "Path": "/folder",
    "Hash": "",
    "Size": 0,
    "Status": "OK"
  }
]
```
```

--------------------------------

### Push Changes and Create Pull Request

Source: https://github.com/ajilach/clamav-rest/blob/master/CONTRIBUTING.md

Push your feature branch to your fork and create a Pull Request targeting the master branch.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Verify ClamAV Database Version

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Check the current ClamAV database version after startup. This can be done via HTTP or directly within the container using `clamscan`.

```bash
curl http://localhost:9000/version
```

```bash
clamscan --database=/clamav/data --version
```

--------------------------------

### Deploy ClamAV-REST with Kubernetes

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Apply bundled Kubernetes manifests for deployment, service, and network policy. Optionally, mount TLS certificates from a Kubernetes secret.

```bash
# Apply the bundled example manifests
kubectl apply -f kubernetes_example/namespace.yaml
kubectl apply -f kubernetes_example/configmap.yaml
kubectl apply -f kubernetes_example/deployment.yaml
kubectl apply -f kubernetes_example/service.yaml
kubectl apply -f kubernetes_example/networkpolicy.yaml

# Optional: mount TLS certificates from a Kubernetes secret
kubectl create secret tls clamav-rest-tls \
  --cert=server.crt --key=server.key -n clamav-rest
# Then uncomment the volumeMounts / volumes sections in deployment.yaml
```

--------------------------------

### Clone Repository and Set Upstream

Source: https://github.com/ajilach/clamav-rest/blob/master/CONTRIBUTING.md

Clone the ClamAV REST repository and add the upstream remote for future updates.

```bash
git clone https://github.com/YOUR_USERNAME/clamav-rest.git
cd clamav-rest
git remote add upstream https://github.com/ajilach/clamav-rest.git
```

--------------------------------

### Scan File by Path

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a specific file using its path. This is useful for scanning files in mounted shares. The response indicates if a threat was found.

```APIDOC
## GET /scanFile

### Description
A scanning endpoint that will scan a file using SCAN. A practical example would be to mount a share into the container where you put a file into a folder, call `/scanFile` and let it scan the content.

### Method
GET

### Endpoint
/scanFile

### Parameters
#### Query Parameters
- **path** (string) - Required - The full path to the file to be scanned.

### Response
#### Success Response (200)
- **Status** (string) - The scanning status (e.g., "FOUND", "OK").
- **Description** (string) - A description of the threat if found.
- **FileName** (string) - The name of the scanned file.

#### Response Example
```json
{
  "Status": "FOUND",
  "Description": "Win.Test.EICAR_HDB-1",
  "FileName": "/clamav/tmp/eicar.test"
}
```
```

--------------------------------

### Containerize ClamAV-REST Application

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Build the Docker image for ClamAV-REST and run it as a detached container. The `docker build` command also handles source compilation, negating the need for a local Go environment.

```bash
docker build . -t clamav-rest
```

```bash
docker run -p 9000:9000 -p 9443:9443 -itd --name clamav-rest clamav-rest
```

--------------------------------

### Prometheus metrics

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Exposes Go runtime metrics and application-specific counters in OpenMetrics format, suitable for scraping by Prometheus or compatible systems.

```APIDOC
## GET /metrics

### Description
Provides Prometheus-compatible metrics for monitoring the ClamAV REST service. This includes Go runtime metrics and custom application counters.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- Exposes metrics in OpenMetrics format, including:
  - `no_of_found_viruses_total` (counter) - Total number of viruses found.
  - `no_of_hits_on_deprecated_scan_endpoint_total` (counter) - Number of times a deprecated scan endpoint was hit.
  - Go runtime metrics (e.g., `go_goroutines`).

#### Response Example (partial output)
```
no_of_found_viruses_total 3
no_of_hits_on_deprecated_scan_endpoint_total 12
go_goroutines 8
```
```

--------------------------------

### Retrieve ClamAV and signature database versions

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Fetches the current version of the clamd binary, the loaded virus signature database version, and the date of the last signature update. Returns this information as a JSON object.

```APIDOC
## GET /version

### Description
Retrieves the version information for the ClamAV service, including the clamd binary version, the signature database version, and the last update date.

### Method
GET

### Endpoint
/version

### Response
#### Success Response (200)
- **Clamav** (string) - The version of the clamd binary.
- **Signature** (string) - The version of the virus signature database.
- **Signature_date** (string) - The date and time of the last signature database update.

#### Response Example
```json
{"Clamav":"1.4.2","Signature":"27516","Signature_date":"Mon Dec 30 08:22:39 2024\n"}
```
```

--------------------------------

### POST /scan — Scan files (deprecated v1 endpoint)

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Functionally equivalent to `/v2/scan` but returns raw JSON objects and does not include `FileName`. This endpoint is deprecated and clients should migrate to `/v2/scan`.

```APIDOC
## POST /scan (Deprecated)

### Description
Scans files using a `multipart/form-data` request. This is a deprecated endpoint, functionally similar to `/v2/scan` but with a different response format and missing the `FileName` field. Clients should migrate to `/v2/scan`.

### Method
POST

### Endpoint
/scan

### Parameters
#### Request Body
- **file** (file) - Required - One or more files to scan, sent as multipart/form-data.

### Request Example (Clean File)
```bash
curl -i -F "file=@document.pdf" http://localhost:9000/scan
```

### Response
#### Success Response (200 OK)
- **Status** (string) - "OK" if the file is clean.
- **Description** (string) - Empty if the file is clean.

#### Error Response (406 Not Acceptable)
- **Status** (string) - "FOUND" if malware is detected.
- **Description** (string) - The name of the detected malware signature.

### Response Headers
- **Deprecation** (string) - Indicates the deprecation status, e.g., `version=v1`.
- **Link** (string) - Provides a link to the successor version, e.g., `http://localhost:9000/v2/scan; rel=successor-version`.

### Response Example (Clean File)
```json
{"Status":"OK","Description":""}
```

### Response Example (Infected File)
```json
{"Status":"FOUND","Description":"Eicar-Test-Signature"}
```
```

--------------------------------

### Configure ClamAV-REST Environment Variables

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Set environment variables to configure scanning limits, service networking, signature updates, CORS, and proxy settings for freshclam.

```bash
# Scanning limits
MAX_SCAN_SIZE=100M         # Total data scanned per file stream
MAX_FILE_SIZE=25M          # Reject files larger than this (also sets StreamMaxLength in clamd)
MAX_RECURSION=16           # Max depth of nested archives
MAX_FILES=10000            # Max files inside a single archive
MAX_EMBEDDEDPE=10M         # Max size for embedded PE files
MAX_HTMLNORMALIZE=10M      # Max size of HTML to normalize
MAX_HTMLNOTAGS=2M          # Max size of normalized (tag-stripped) HTML
MAX_SCRIPTNORMALIZE=5M     # Max size of scripts to normalize
MAX_ZIPTYPERCG=1M          # Max size for ZIP type-recognition re-analysis
MAX_PARTITIONS=50          # Max raw-disk partitions to scan
MAX_ICONSPE=100            # Max PE icons to scan
PCRE_MATCHLIMIT=100000     # Max PCRE match calls
PCRE_RECMATCHLIMIT=2000    # Max recursive PCRE match calls

# Service / networking
PORT=9000                  # HTTP listen port
SSL_PORT=9443              # HTTPS listen port
SSL_CERT=/etc/ssl/clamav-rest/server.crt
SSL_KEY=/etc/ssl/clamav-rest/server.key
CLAMD_PORT=tcp://localhost:3310
MAX_RECONNECT_TIME=30      # Seconds to wait for clamd before giving up

# Signature updates
SIGNATURE_CHECKS=2         # freshclam checks per day (1–50)

# CORS — semicolon-separated list of allowed origins; * allows all
ALLOW_ORIGINS=*

# Proxy for freshclam signature downloads (all optional)
PROXY_SERVER=proxy.example.com
PROXY_PORT=8080
PROXY_USERNAME=user
PROXY_PASSWORD=secret
```

```bash
# Example: raise file size limit and restrict CORS
docker run -p 9000:9000 \
  -e MAX_FILE_SIZE=100M \
  -e MAX_SCAN_SIZE=200M \
  -e ALLOW_ORIGINS="https://app.example.com;https://admin.example.com" \
  -itd --name clamav-rest ajilaag/clamav-rest
```

--------------------------------

### Create TLS Secret (Kubernetes)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Create a TLS secret in Kubernetes to enable HTTPS. This secret will be mounted as a volume in your deployment.

```bash
kubectl create secret tls clamav-rest-tls \
  --cert=server.crt --key=server.key -n clamav-rest
```

--------------------------------

### Create Feature or Fix Branch

Source: https://github.com/ajilach/clamav-rest/blob/master/CONTRIBUTING.md

Create a new branch for your feature development or bug fix.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

--------------------------------

### Scan File over HTTP/2 with Prior Knowledge (h2c)

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Utilize unencrypted HTTP/2 (h2c) for scanning files. This is an alternative to standard HTTP/1.1 or HTTPS.

```bash
curl -i --http2-prior-knowledge -F "file=@document.pdf" http://localhost:9000/v2/scan
# HTTP/2 200
# ["{\"Status\":\"OK\",\"Description\":\"\",\"FileName\":\"document.pdf\"}"]
```

--------------------------------

### POST /v2/scan — Scan one or more uploaded files

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Accepts multipart/form-data requests with one or more files. Streams each file to clamd for scanning. The response is a JSON array detailing the status of each file. The overall HTTP status reflects the worst result across all files.

```APIDOC
## POST /v2/scan

### Description
Scans one or more uploaded files using a multipart/form-data request. Each file is individually streamed to `clamd`.

### Method
POST

### Endpoint
/v2/scan

### Parameters
#### Request Body
- **file** (file) - Required - One or more files to scan, sent as multipart/form-data.

### Request Example
```bash
curl -i -F "file=@document.pdf" http://localhost:9000/v2/scan
```

### Response
#### Success Response (200)
- **Status** (string) - "OK" if the file is clean.
- **Description** (string) - Empty if the file is clean.
- **FileName** (string) - The name of the scanned file.

#### Error Response (406 Not Acceptable)
- **Status** (string) - "FOUND" if malware is detected.
- **Description** (string) - The name of the detected malware signature.
- **FileName** (string) - The name of the infected file.

#### Error Response (413 Request Entity Too Large)
- **Status** (string) - "PARSE ERROR"
- **Description** (string) - "File size limit exceeded"
- **FileName** (string) - The name of the file that exceeded the size limit.

#### Error Response (422 Unprocessable Entity)
- **Status** (string) - "ERROR"
- **Description** (string) - "MimePart FileName missing"

### Response Example (Clean File)
```json
[{"Status":"OK","Description":"","FileName":"document.pdf"}]
```

### Response Example (Infected File)
```json
[{"Status":"FOUND","Description":"Eicar-Test-Signature","FileName":"eicar.com.txt"}]
```

### Response Example (Multiple Files - Mixed Results)
```json
[{"Status":"OK","Description":"","FileName":"clean.txt"},{"Status":"FOUND","Description":"Eicar-Test-Signature","FileName":"eicar.com.txt"}]
```

### Response Example (File Size Exceeded)
```json
[{"Status":"PARSE ERROR","Description":"File size limit exceeded","FileName":"large_file.bin"}]
```

### Response Example (Missing Filename)
```json
[{"Status":"ERROR","Description":"MimePart FileName missing"}]
```
```

--------------------------------

### Scan File over HTTPS with curl

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Perform a file scan using HTTPS. Ensure the TLS certificate is mounted at runtime for secure communication. The '-k' flag bypasses certificate verification.

```bash
curl -i -k -F "file=@document.pdf" https://localhost:9443/v2/scan
# HTTP/2 200
# ["{\"Status\":\"OK\",\"Description\":\"\",\"FileName\":\"document.pdf\"}"]
```

--------------------------------

### Scan a file

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Scans a single file for viruses. Returns 406 Not Acceptable if a virus is found, 412 Precondition Failed if the path is invalid, and 400 Bad Request if the path parameter is missing.

```APIDOC
## GET /scanFile?path=<absolute-file-path>

### Description
Scans a specified file for viruses. The endpoint returns different HTTP status codes based on the scan result and input validity.

### Method
GET

### Endpoint
/scanFile

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path to the file to be scanned.

### Request Example
```bash
curl -i "http://localhost:9000/scanFile?path=/clamav/tmp/virus/eicar.test"
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the scan result (e.g., "OK").
- **Description** (string) - Provides details about the scan result (e.g., virus name or empty if clean).
- **FileName** (string) - The name of the file scanned.

#### Error Responses
- **406 Not Acceptable**: Returned if a virus is detected in the file.
- **412 Precondition Failed**: Returned if the provided path does not point to a file.
- **400 Bad Request**: Returned if the 'path' query parameter is missing.
```

--------------------------------

### Version Endpoint

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Retrieves the ClamAV binary version, virus signature database version, and the last update date of the signatures.

```APIDOC
## GET /version

### Description
Returns the clamav binary version and also the version of the virus signature databases and the signature last update date.

### Method
GET

### Endpoint
/version

### Response
(Response details not specified in source)
```

--------------------------------

### Deploy ClamAV-REST with Docker Compose

Source: https://context7.com/ajilach/clamav-rest/llms.txt

A production-hardened Docker Compose configuration for non-root user and read-only filesystem. Includes health checks and volume definitions.

```yaml
# docker-compose-nonroot.yml — production-hardened configuration
services:
  clamav-rest:
    image: ajilaag/clamav-rest
    mem_reservation: "2G"
    mem_limit: "3G"
    ports:
      - "9000:9000"
      - "9443:9443"
    read_only: true
    user: 100:101          # clamav:clamav UID:GID
    volumes:
      - clamav:/clamav:rw
      - run-clamav:/run/clamav:rw
      - var-log-clamav:/var/log/clamav:rw
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:9000/"]
      interval: 60s
      timeout: 2s
      retries: 2
      start_period: 210s   # ClamAV DB load takes time on cold start
volumes:
  clamav:
  run-clamav:
  var-log-clamav:
```

--------------------------------

### Scan File (HTTP)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a file using the HTTP endpoint. Returns 406 if a virus is found, 200 otherwise.

```APIDOC
## POST /v2/scan

### Description
Scans a file for viruses. The API returns a `406 - Not Acceptable` response if at least one virus is found, and a `200 - OK` otherwise.

### Method
POST

### Endpoint
http://localhost:9000/v2/scan

### Parameters
#### Request Body
- **file** (file) - Required - The file to scan.

### Request Example
```bash
curl -i -F "file=@eicar.com.txt" http://localhost:9000/v2/scan
```

### Response
#### Success Response (200)
- **Status** (string) - OK
- **Description** (string) - Empty if no virus found.
- **FileName** (string) - The name of the scanned file.

#### Success Response Example (Clean File)
```json
[
  {
    "Status": "OK",
    "Description": "",
    "FileName": "clamrest.go"
  }
]
```

#### Error Response (406)
- **Status** (string) - FOUND
- **Description** (string) - Description of the found virus signature.
- **FileName** (string) - The name of the scanned file.

#### Error Response Example (Virus Found)
```json
[
  {
    "Status": "FOUND",
    "Description": "Eicar-Test-Signature",
    "FileName": "eicar.com.txt"
  }
]
```

### Status Codes
- 200 - OK: clean file = no KNOWN infections
- 406 - Not Acceptable: payload is infected
```

--------------------------------

### Scan Single Clean File with curl

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Use this endpoint to scan a single clean file using a multipart/form-data request. The response indicates a 200 OK status if the file is clean.

```bash
curl -i -F "file=@document.pdf" http://localhost:9000/v2/scan
# HTTP/1.1 200 OK
# ["{\"Status\":\"OK\",\"Description\":\"\",\"FileName\":\"document.pdf\"}"]
```

--------------------------------

### Scan File (HTTPS)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Scan a file using the HTTPS endpoint. Returns 406 if a virus is found, 200 otherwise.

```APIDOC
## POST /v2/scan

### Description
Scans a file for viruses using HTTPS. The API returns a `406 - Not Acceptable` response if at least one virus is found, and a `200 - OK` otherwise.

### Method
POST

### Endpoint
https://localhost:9443/v2/scan

### Parameters
#### Request Body
- **file** (file) - Required - The file to scan.

### Request Example
```bash
curl -i -k -F "file=@eicar.com.txt" https://localhost:9443/v2/scan
```

### Response
#### Success Response (200)
- **Status** (string) - OK
- **Description** (string) - Empty if no virus found.
- **FileName** (string) - The name of the scanned file.

#### Success Response Example (Clean File)
```json
[
  {
    "Status": "OK",
    "Description": "",
    "FileName": "clamrest.go"
  }
]
```

#### Error Response (406)
- **Status** (string) - FOUND
- **Description** (string) - Description of the found virus signature.
- **FileName** (string) - The name of the scanned file.

#### Error Response Example (Virus Found)
```json
[
  {
    "Status": "FOUND",
    "Description": "Eicar-Test-Signature",
    "FileName": "eicar.com.txt"
  }
]
```

### Status Codes
- 200 - OK: clean file = no KNOWN infections
- 406 - Not Acceptable: payload is infected
```

--------------------------------

### Scan all files in a directory

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Recursively scans all files within a specified directory using clamd's ALLMATCHSCAN. Returns a JSON array of results. An overall HTTP status of 406 is returned if any file in the directory is infected. A 400 Bad Request is returned if the path parameter is missing.

```APIDOC
## GET /scanPath?path=<absolute-directory>

### Description
Recursively scans all files within a given directory. The response is a JSON array detailing the status of each file. An infected file results in a 406 Not Acceptable status for the entire request.

### Method
GET

### Endpoint
/scanPath

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path to the directory to scan.

### Request Example
```bash
curl -i "http://localhost:9000/scanPath?path=/clamav/tmp/uploads"
```

### Response
#### Success Response (200)
- An array of JSON objects, where each object represents a file and contains:
  - **Status** (string) - The scan status for the file (e.g., "OK", "FOUND").
  - **Description** (string) - Details about the scan result (e.g., virus name or empty if clean).

#### Response Example (Clean Directory)
```json
[{"Status":"OK","Description":""},{"Status":"OK","Description":""}]
```

#### Response Example (Directory with Infected File)
```json
[{"Status":"OK","Description":""},{"Status":"FOUND","Description":"Win.Test.EICAR_HDB-1"}]
```

#### Error Responses
- **406 Not Acceptable**: Returned if any file within the directory is found to be infected.
- **400 Bad Request**: Returned if the 'path' query parameter is missing.
```

--------------------------------

### Scan File by Path

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Scan a file located at an absolute path within the container's filesystem using the SCAN protocol. This is useful for files on mounted volumes. Returns 412 if the path is invalid.

```bash
curl -i "http://localhost:9000/scanFile?path=/clamav/tmp/uploads/report.pdf"
# HTTP/1.1 200 OK
# {"Status":"OK","Description":"","FileName":"/clamav/tmp/uploads/report.pdf"}
```

--------------------------------

### Scan Files

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Upload one or more files for scanning. The API returns a JSON array with the status, description, and filename for each scanned file. The HTTP status code reflects the most severe outcome.

```APIDOC
## POST /v2/scan

### Description
Accepts a multipart/form-data request with one or more files and returns a json array with status, description and filename, along with the most severe http status code that was possible to determine.

### Method
POST

### Endpoint
/v2/scan

### Parameters
#### Request Body
- **files** (multipart/form-data) - Required - One or more files to scan.

### Response
#### Success Response (200)
- **Status** (string) - The scanning status (e.g., "OK", "FOUND").
- **Description** (string) - A description of the threat if found, otherwise empty.
- **FileName** (string) - The name of the scanned file.

#### Response Example
```json
[
  {
    "Status": "OK",
    "Description": "",
    "FileName": "checksums.txt"
  }
]
```
```

--------------------------------

### Expose Prometheus metrics from ClamAV REST API

Source: https://context7.com/ajilach/clamav-rest/llms.txt

The `/metrics` endpoint exposes Go runtime metrics, build info, and application-specific counters in OpenMetrics format, suitable for scraping by Prometheus. It includes counts of found viruses and hits on deprecated scan endpoints.

```bash
curl -s http://localhost:9000/metrics | grep -E "^ (no_of|go_goroutines)"
# no_of_found_viruses_total 3
# no_of_hits_on_deprecated_scan_endpoint_total 12
# go_goroutines 8
```

```yaml
scrape_configs:
  - job_name: clamav-rest
    static_configs:
      - targets: ["clamav-rest:9000"]
```

--------------------------------

### Scan Multiple Files with curl

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Submit multiple files in a single multipart request. The overall HTTP status will reflect the worst result among all files (e.g., 406 if any file is infected).

```bash
curl -i \
  -F "file=@clean.txt" \
  -F "file=@eicar.com.txt" \
  http://localhost:9000/v2/scan
# HTTP/1.1 406 Not Acceptable
# ["{\"Status\":\"OK\",\"Description\":\"\",\"FileName\":\"clean.txt\"}","{\"Status\":\"FOUND\",\"Description\":\"Eicar-Test-Signature\",\"FileName\":\"eicar.com.txt\"}"]
```

--------------------------------

### Scan File via HTTP with cURL (Infected)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Tests the HTTP scanning endpoint by sending the EICAR test file. Expects a 406 Not Acceptable response if the file is detected as a virus.

```bash
$ curl -i -F "file=@eicar.com.txt" http://localhost:9000/v2/scan
HTTP/1.1 100 Continue

HTTP/1.1 406 Not Acceptable
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Aug 2017 20:22:34 GMT
Content-Length: 56

[{ "Status": "FOUND", "Description": "Eicar-Test-Signature","FileName":"eicar.com.txt"}]
```

--------------------------------

### Home / stats endpoint

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Provides runtime statistics from clamd, including pool information, state, queue depth, and memory usage. This endpoint also serves as the liveness and readiness probe target. Returns 503 if clamd is unavailable.

```APIDOC
## GET /

### Description
Returns runtime statistics from the `clamd` service. This endpoint is commonly used for health checks and monitoring.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Pools** (integer) - Number of available pools.
- **State** (string) - The current state of the clamd service (e.g., "VALID PRIMARY").
- **Threads** (string) - Information about active, idle, and maximum threads.
- **Queue** (string) - The current queue depth.
- **Memstats** (string) - Memory statistics from the Go runtime.

#### Response Example
```json
{"Pools":1,"State":"VALID PRIMARY","Threads":"live 1 idle 0 max 10 idle-timeout 30","Queue":"0","Memstats":"..."}
```

#### Error Responses
- **503 Service Unavailable**: Returned if `clamd` is unavailable.
```

--------------------------------

### Scan all files in a directory with ClamAV REST API

Source: https://context7.com/ajilach/clamav-rest/llms.txt

The `/scanPath` endpoint recursively scans an entire directory using `clamd`'s ALLMATCHSCAN. The overall HTTP status is 406 if any file in the directory is infected. A missing path parameter results in a 400 Bad Request.

```bash
curl -i "http://localhost:9000/scanPath?path=/clamav/tmp/uploads"
# HTTP/1.1 200 OK
# [{"Status":"OK","Description":""},{"Status":"OK","Description":""}]
```

```bash
curl -i "http://localhost:9000/scanPath?path=/clamav/tmp/mixed"
# HTTP/1.1 406 Not Acceptable
# [{"Status":"OK","Description":""},{"Status":"FOUND","Description":"Win.Test.EICAR_HDB-1"}]
```

```bash
curl -i "http://localhost:9000/scanPath"
# HTTP/1.1 400 Bad Request
# URL param 'path' is missing
```

--------------------------------

### Home / stats endpoint for ClamAV REST API

Source: https://context7.com/ajilach/clamav-rest/llms.txt

The `/` endpoint provides runtime statistics from `clamd`, including pools, state, queue depth, and memory. It serves as the liveness and readiness probe target. Returns 503 if `clamd` is unavailable.

```bash
curl -s http://localhost:9000/
# {"Pools":1,"State":"VALID PRIMARY","Threads":"live 1 idle 0 max 10 idle-timeout 30","Queue":"0","Memstats":"..."}
```

```bash
wget -q -O /dev/null http://localhost:9000/ && echo "healthy"
# healthy
```

--------------------------------

### Scan with Missing Filename

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Submit a file part without a filename, which results in a 422 Unprocessable Entity status due to missing required information.

```bash
curl -i -F "file=@document.pdf;filename=" http://localhost:9000/v2/scan
# HTTP/1.1 422 Unprocessable Entity
# ["{\"Status\":\"ERROR\",\"Description\":\"MimePart FileName missing\"}"]
```

--------------------------------

### Metrics Endpoint

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Prometheus endpoint for scraping metrics.

```APIDOC
## GET /metrics

### Description
Prometheus endpoint for scraping metrics.

### Method
GET

### Endpoint
/metrics

### Response
(Response details not specified in source)
```

--------------------------------

### Custom freshclam.conf Directives

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

These directives are required in your custom freshclam.conf for the container to function correctly. This bypasses environment variables for freshclam configuration.

```text
Foreground yes
DatabaseDirectory /clamav/data
NotifyClamd /clamav/etc/clamd.conf
```

--------------------------------

### Deprecated Scan Single Clean File

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Use the deprecated `/scan` endpoint for scanning a clean file. This endpoint returns raw JSON objects and lacks the `FileName` field. Clients should migrate to `/v2/scan`.

```bash
curl -i -F "file=@document.pdf" http://localhost:9000/scan
# HTTP/1.1 200 OK
# Deprecation: version=v1
# Link: http://localhost:9000/v2/scan; rel=successor-version
# {"Status":"OK","Description":""}
```

--------------------------------

### Scan File via HTTPS with cURL (Infected)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Tests the HTTPS scanning endpoint using cURL with the -k flag to ignore certificate errors. Sends the EICAR test file and expects a 406 Not Acceptable response.

```bash
$ curl -i -k -F "file=@eicar.com.txt" https://localhost:9443/v2/scan
HTTP/1.1 100 Continue

HTTP/1.1 406 Not Acceptable
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Aug 2017 20:22:34 GMT
Content-Length: 56

[{ "Status": "FOUND", "Description": "Eicar-Test-Signature","FileName":"eicar.com.txt"}]
```

--------------------------------

### Scan File Exceeding Max Size

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Attempt to scan a file larger than the configured MAX_FILE_SIZE (default 25MB). The API returns a 413 Request Entity Too Large status.

```bash
curl -i -F "file=@large_file.bin" http://localhost:9000/v2/scan
# HTTP/1.1 413 Request Entity Too Large
# ["{\"Status\":\"PARSE ERROR\",\"Description\":\"File size limit exceeded\",\"FileName\":\"large_file.bin\"}"]
```

--------------------------------

### Scan a single file with ClamAV REST API

Source: https://context7.com/ajilach/clamav-rest/llms.txt

Use the `/scanFile` endpoint to scan a specific file. Ensure the path parameter points to an existing file. An infected file will result in a 406 Not Acceptable status.

```bash
curl -i "http://localhost:9000/scanFile?path=/clamav/tmp/virus/eicar.test"
# HTTP/1.1 406 Not Acceptable
# {"Status":"FOUND","Description":"Win.Test.EICAR_HDB-1","FileName":"/clamav/tmp/virus/eicar.test"}
```

```bash
curl -i "http://localhost:9000/scanFile?path=/clamav/tmp/does-not-exist.txt"
# HTTP/1.1 412 Precondition Failed
# {"Status":"PARSE ERROR","Description":"..., this likely means the file path supplied to the api does not point to a file on disk.","FileName":"/clamav/tmp/does-not-exist.txt"}
```

```bash
curl -i "http://localhost:9000/scanFile"
# HTTP/1.1 400 Bad Request
# URL param 'path' is missing
```

--------------------------------

### Access Container Shell

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Execute commands inside the running ClamAV-REST container for debugging or maintenance. Replace `(whatever your container name is e.g. clamav-rest)` with the actual container name.

```bash
docker exec -it (whatever your container name is e.g. clamav-rest) /bin/sh
```

--------------------------------

### Scan Endpoint (Deprecated)

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

This endpoint scans files, similar to `/v2/scan`, but with differences in response structure and without filename in JSON. It is deprecated and intended for backward compatibility.

```APIDOC
## POST /scan (Deprecated)

### Description
[DEPRECATED] Scans files, similar to `/v2/scan` but returns one or more JSON objects without a valid JSON structure in between and does not include the filename as a JSON property. This endpoint is present for backward compatibility and will be sunsetted. It accepts multipart/form-data for multiple files but was likely intended for single file scanning.

### Method
POST

### Endpoint
/scan

### Parameters
#### Request Body
- Accepts `multipart/form-data` for file uploads.

### Response
#### Success Response
- `Status` (string) - Indicates the status of the scan (e.g., "OK").
- `Description` (string) - Provides a description of the scan result.

### Response Example
```json
{
  "Status": "OK",
  "Description": ""
}
```

### Deprecation Notice
This endpoint is deprecated. Please use `/v2/scan` instead. Headers indicating deprecation and pointing to the new endpoint will be returned.
```

--------------------------------

### Retrieve Prometheus Metrics

Source: https://github.com/ajilach/clamav-rest/blob/master/README.md

Fetch Prometheus metrics from the ClamAV-REST service. Metrics are available over both HTTP and HTTPS.

```bash
curl http://localhost:9000/metrics
```

```bash
curl https://localhost:9443/metrics
```