clamd

README

go-clamd

A Go client for ClamAV daemon over TCP or UNIX socket.

Requirements

• Minimum Go version 1.20
• Only targeted for Linux.

Features

Go	CalmAv	Description
Ping	PING	Check the server's state. It should reply with "PONG".
Version	VERSION	Print program and database versions.
Reload	RELOAD	Reload the virus databases.
Shutdown	SHUTDOWN	Perform a clean exit.
Scan	SCAN	Scan a file or a directory (recursively) with archive support enabled (if not disabled in clamd.conf). A full path is required.
ScanAll	CONTSCAN	Scan file or directory (recursively) with archive support enabled and don't stop the scanning when a virus is found.
ScanStream	INSTREAM	Scan a stream of data. The stream is sent to clamd in chunks, after INSTREAM, on the same socket on which the command was sent. This avoids the overhead of establishing new TCP connections and problems with NAT. Note: do not exceed StreamMaxLength as defined in clamd.conf, otherwise clamd will reply with INSTREAM size limit exceeded and close the connection.
Stats	STATS	Replies with statistics about the scan queue, contents of scan queue, and memory usage. The exact reply format is subject to change in future releases.

Usage

import (
    "fmt"
    "github.com/Lyimmi/go-clamd"
)

c := clamd.NewClamd()

if ok, _ := c.Ping(ctx); !ok {
    fmt.Println("clamd nok")
}

if ok, err := c.Scan(ctx, fileName); !ok {
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s has maleware\n", fileName)
}

if ok, err := c.ScanAll(ctx, "/tmp"); !ok {
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s has maleware\n", fileName)
}

stats, err := c.Stats(ctx)
if err != nil {
    panic(err)
}
d, err := json.MarshalIndent(stats, "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(string(d))

License

The MIT License (MIT)

Documentation

Overview

Package clamd is a client for ClamAV daemon over TCP or UNIX socket.

Index

• Variables
• type Clamd
  • func NewClamd(opts ...Option) *Clamd
  • func (c *Clamd) Ping(ctx context.Context) (bool, error)
  • func (c *Clamd) Reload(ctx context.Context) (bool, error)
  • func (c *Clamd) Scan(ctx context.Context, src string) (bool, error)
  • func (c *Clamd) ScanAll(ctx context.Context, src string) (bool, error)
  • func (c *Clamd) ScanStream(ctx context.Context, r io.Reader) (bool, error)
  • func (c *Clamd) Shutdown(ctx context.Context) (bool, error)
  • func (c *Clamd) Stats(ctx context.Context) (*Stats, error)
  • func (c *Clamd) Version(ctx context.Context) (string, error)
• type MemStat
• type Option
  • func WithDefaultTCP() Option
  • func WithTCP(host string, port int) Option
  • func WithTimeout(timeout time.Duration) Option
  • func WithUnix(socket string) Option
• type Queue
• type Stats
• type Thread

Variables

var (
	ErrDial               = errors.New("error while connecting to clamd")
	ErrCommandCall        = errors.New("error while calling clamd")
	ErrCommandRead        = errors.New("error while reading response from clamd")
	ErrEmptySrc           = errors.New("scan source is empty")
	ErrInvalidResponse    = errors.New("invalid response from clamd")
	ErrNoSuchFileOrDir    = errors.New("clamd can't find file or directory")
	ErrPermissionDenied   = errors.New("clamd can't open file or dir, permission denied")
	ErrSreamLimitExceeded = errors.New("clamd's INSTREAM size limit exceeded")
	ErrUnknown            = errors.New("unknown error")
	ErrEICARFound         = errors.New("Win.Test.EICAR_HDB-1 FOUND")
)

Errors

Types

type Clamd

type Clamd struct {
	// contains filtered or unexported fields
}

Clamd is a client for ClamAV's daemon clamd.

func NewClamd

func NewClamd(opts ...Option) *Clamd

NewClamd returns a Clamd client with default options.

Default connection is a UNIX socket on /var/run/clamav/clamd.ctl with 30 second timeout. Defaults can be changed by passing in Option functions.

func (*Clamd) Ping

func (c *Clamd) Ping(ctx context.Context) (bool, error)

Ping checks if Clamd is up and responsive.

func (*Clamd) Reload

func (c *Clamd) Reload(ctx context.Context) (bool, error)

Reload Clamd virus databases.

func (*Clamd) Scan

func (c *Clamd) Scan(ctx context.Context, src string) (bool, error)

Scan a file or a directory (recursively) with archive support enabled (if not disabled in clamd.conf). A full path is required.

func (*Clamd) ScanAll

func (c *Clamd) ScanAll(ctx context.Context, src string) (bool, error)

ScanAll Scan file or directory (recursively) with archive support enabled and don't stop the scanning when a virus is found.

func (*Clamd) ScanStream

func (c *Clamd) ScanStream(ctx context.Context, r io.Reader) (bool, error)

ScanStream Scan a stream of data.This avoids the overhead of establishing new TCP connections and problems with NAT.

Note: do not exceed StreamMaxLength as defined in clamd.conf, otherwise clamd will reply with INSTREAM size limit exceeded and close the connection. (default is 25M)

func (*Clamd) Shutdown

func (c *Clamd) Shutdown(ctx context.Context) (bool, error)

Shutdown stops Clamd cleanly.

func (*Clamd) Stats

func (c *Clamd) Stats(ctx context.Context) (*Stats, error)

func (*Clamd) Version

func (c *Clamd) Version(ctx context.Context) (string, error)

Version returns Clamd's version.

type MemStat

type MemStat struct {
	Heap       float32
	Mmap       float32
	Used       float32
	Free       float32
	Releasable float32
	Pools      int
	PoolsUsed  float32
	PoolsTotal float32
}

type Option

type Option func(*Clamd)

Option sets an option to Clamd.

func WithDefaultTCP

func WithDefaultTCP() Option

WithDefaultTCP sets up the client to use the default TCP connection on 127.0.0.1:3310

func WithTCP

func WithTCP(host string, port int) Option

WithTCP sets up the client with a custom TCP connection.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets a timeout on the connection.

func WithUnix

func WithUnix(socket string) Option

WithUnix sets up the client to use a custom unix socket.

type Queue

type Queue struct {
	Items int
	Stats float32
}

type Stats

type Stats struct {
	Pools    int
	State    string
	Threads  Thread
	Memstats MemStat
	Queue    Queue
}

type Thread

type Thread struct {
	Live        int
	Idle        int
	Max         int
	IdleTimeout int
}