devopstom/go-clamav-rest-echo

go-clamav-rest-echo

镜像概述

go-clamav-rest-echo是一个基于Echo v4框架重新实现的ClamAV代理，用于与ClamAV的clamd服务通信，提供文件病毒扫描功能及健康检查接口。该镜像可作为中间件，为应用提供便捷的RESTful API来集成病毒扫描能力。

核心功能与特性

• 健康检查：提供/和/healthz端点，通过ping clamd服务检查其可用性
• 文件扫描：支持两种扫描接口，返回不同详细程度的结果
  • /scan：返回简单状态（OK或Malware detected）及对应HTTP状态码
  • /scanResponse：返回包含原始扫描信息、***描述等详细JSON数据
• 环境变量配置：支持通过环境变量自定义连接参数，无需修改代码

环境变量说明

使用场景

适用于需要集成病毒扫描功能的应用场景，如：

• 文件上传服务的病毒检测
• 邮件服务器附件扫描
• 文档管理系统的安全检查
• 任何需要通过REST API调用ClamAV扫描能力的系统

使用方法

Docker运行

1. 单独运行（需确保clamd服务可达）

bash
docker run -e CLAMD_HOST=clamav_host -e CLAMD_PORT=3310 -p 8080:8080 devopstom/go-clamav-rest-echo:latest

2. 与clamav容器联动

首先运行clamav容器（推荐使用https://github.com/cabinetoffice/docker-clamav%EF%BC%89%EF%BC%9A

bash
docker run --name clamav -v ${PWD}/clamdata:/var/lib/clamav -d -p 3310:3310 quay.io/ukhomeofficedigital/clamav:latest

然后运行代理容器并链接clamav容器：

bash
docker run -e CLAMD_HOST=clamav --link=clamav -p 8080:8080 devopstom/go-clamav-rest-echo:latest

Docker Compose示例

yaml
version: '3'
services:
  clamav:
    image: quay.io/ukhomeofficedigital/clamav:latest
    volumes:
      - ./clamdata:/var/lib/clamav
    ports:
      - "3310:3310"
    restart: always

  clamav-proxy:
    image: devopstom/go-clamav-rest-echo:latest
    environment:
      - CLAMD_HOST=clamav
      - CLAMD_PORT=3310
      - LISTEN_PORT=8080
    ports:
      - "8080:8080"
    depends_on:
      - clamav
    restart: always

API接口说明

健康检查接口

/ 和 /healthz

• 功能：检查与clamd服务的连接状态
• 请求方式：GET
• 成功响应（200 OK）：

  json
  "OK"
  

• 失败响应（500 Internal Server Error）：

  json
  {"message":"Could not ping clamd"}
  

• 示例：

  bash
  curl -i http://localhost:8080/
  

文件扫描接口

/scan

• 功能：扫描文件并返回简单结果
• 请求方式：POST（multipart/form-data格式）
• 请求参数：
  • name：文件名（可选）
  • file：待扫描文件
• 响应：
  • 无***（200 OK）："OK"
  • 检测到***（451 Unavailable For Legal Reasons）：{"message":"Malware detected"}
• 示例：

  bash
  # 扫描恶意文件
  curl -i -F "name=eicar" -F "file=@./eicar.com" http://localhost:8080/scan
  
  # 扫描干净文件
  curl -i -F "name=clean" -F "file=@/bin/true" http://localhost:8080/scan
  

/scanResponse

• 功能：扫描文件并返回详细结果
• 请求方式：POST（multipart/form-data格式）
• 请求参数：
  • name：文件名（可选）
  • file：待扫描文件
• 响应：
  • 无***（200 OK）：

    json
    {"Raw":"stream: OK","Description":"","Path":"stream","Hash":"","Size":0,"Status":"OK"}
    

  • 检测到***（451 Unavailable For Legal Reasons）：

    json
    {"Raw":"stream: Win.Test.EICAR_HDB-1 FOUND","Description":"Win.Test.EICAR_HDB-1","Path":"stream","Hash":"","Size":0,"Status":"FOUND"}
    

• 示例：

  bash
  # 扫描恶意文件
  curl -i -F "name=eicar" -F "file=@./eicar.com" http://localhost:8080/scanResponse
  
  # 扫描干净文件
  curl -i -F "name=clean" -F "file=@/bin/true" http://localhost:8080/scanResponse
  

Docker Hub地址

https://hub.docker.com/r/devopstom/go-clamav-rest-echo