Go と ClamAV によるファイルのウイルススキャン
アップロードを受け付けるアプリケーションには、スキャン後にファイルの隔離を解除するための明確なルールが必要です。このガイドでは ClamAV と Go を使い、検出なし、感染、スキャナーエラー、サイズ制限という四つの結果を区別します。アプリケーションが処理を続行できるのは、明示的に検出なしと判定された場合だけです。
Go によるウイルススキャンの基本
新しいアップロードは、スキャンが完了するまで非公開の隔離領域に保管します。接続失敗、タイムアウト、空の応答、スキャン制限の超過は、検出なしの根拠にはなりません。ウイルススキャンは保護対策の一層にすぎず、すべてのファイルが無害であることを証明するものではありません。
ここでは、アップロードが完了した単一ファイルからサイズを制限したスナップショットを取得し、ローカルのデーモンにストリーミングします。この例ではディレクトリのスキャン、アップロードの削除、ファイルの修復は一切行いません。アプリケーションはスキャン対象のスナップショットを変更不可に保ち、検出なしの判定を受けた後に限り、その同じバイト列を公開する必要があります。
ClamAV の概要と機能
ClamAV は clamscan コマンド、常駐する clamd デーモン、シグネチャ更新用の freshclam を提供します。デーモンを使うと、リクエストごとにシグネチャデータベースを読み込む必要がありません。このガイドでは、libclamav 用の別個の go-clamav バインディングではなく、デーモンのプロトコルに対応した Go クライアントを使います。
デーモンの TCP プロトコルには認証機能がありません。同じホスト上でアクセス権を制限した Unix ソケットを使い、clamd を公開ネットワークに露出させないでください。詳しくは ClamAV スキャンガイドを参照してください。
Go 環境での ClamAV のセットアップ
以下の実行例は、Linux 上の Bash、Go 1.26.8、ClamAV 1.5.4 でテストしました。go version が動作しない場合は、公式インストールガイドに従って Go をインストールしてください。保守が継続されている ClamAV リリースと最新のシグネチャを使ってください。ディストリビューションのバージョンについては、ClamAV サポートポリシーを確認してください。
systemd を使用する Debian または Ubuntu では、ディストリビューションのパッケージでスキャナーとデーモンをインストールします。各 Bash ブロックは全体をまとめて貼り付けてください。&& により、ある手順が失敗した場合に次の手順が実行されるのを防ぎます。
sudo apt-get update &&
sudo apt-get install clamav clamav-daemon &&
sudo systemctl status clamav-freshclam
シグネチャ更新ツールによる初回のデータベースダウンロードが完了するまで待ちます。サービスが更新を管理している間は、別の freshclam プロセスを起動しないでください。ディストリビューションの clamd.conf を確認してから、clamav-daemon を起動または再起動してください。以下の制限を適用し、ソケットのパスとグループ権限を確認します。ほかの OS ではサービスのパスが異なります。
sudo systemctl restart clamav-daemon &&
sudo systemctl status clamav-daemon
ウイルススキャン用の go-clamd の実装
新しい scan-example プロジェクトを作成する親ディレクトリから実行してください。このブロックは独立した Go モジュールを作成し、ここで使うクライアントのバージョンを固定します。作成先のディレクトリがすでに存在する場合はエラーになります。プロジェクトを削除せず、別の親ディレクトリを選んでください。成功すると、シェルの作業ディレクトリが新しいプロジェクトに移ります。作成、移動、依存関係のセットアップのいずれかに失敗した場合は元のディレクトリにとどまります。続行する前にエラーを確認してください。
(
mkdir scan-example &&
cd scan-example &&
GOWORK=off go mod init example.com/scan-example &&
GOWORK=off go get github.com/dutchcoders/go-clamd@v0.0.0-20170520113014-b970184f4d9e
) && cd scan-example
GOWORK=off により、この独立したモジュールを上位ディレクトリの go.work ファイルから切り離します。ビルドとテストのコマンドにも指定してください。詳しくは Go ワークスペースのドキュメントを参照してください。
これは古い小規模なクライアントです。ScanResult
には Path フィールドがあり、Filename ではありません。ScanStream はチャネルとエラーを返し、中断用チャネルを受け取ります。中断用チャネルを閉じると確立済みの接続が閉じられますが、このパッケージには、接続確立とすべての I/O を網羅する、コンテキストに対応した期限管理機能はありません。
そのため、この例ではクライアントを短時間だけ動作するワーカープロセスで実行します。Go の exec.CommandContext はタイムアウト時にそのプロセスを終了させ、終了を待機することでソケットとゴルーチンを解放します。これにはスキャンごとにプロセスが必要になるコストがあります。サービスではワーカーの同時実行数を制限してください。アップロードを受け付けるたびに、無制限にゴルーチンやプロセスを起動しないでください。
実用例とコードスニペット
プログラム全体を main.go として保存してください。アプリケーションが選択した単一の通常ファイルを受け取り、最大 10 MiB と追加の一バイトを読み込み、そのスナップショットをストリーミングします。CLAMD_SOCKET はサーバー設定であり、アップロードのパラメーターではありません。応答がない場合、不正なエントリがある場合、クライアントのチャネルから二つ目の応答が返る場合は、安全側に倒して拒否します。デーモンの未加工の診断情報はプログラムの公開出力に含めません。
バージョンを固定したこのクライアントは、終端のない末尾の応答を破棄したり、完全な応答の後に生じた読み取り失敗を隠したりする場合があります。ワーカーの期限はハングを停止しますが、応答パーサーを修正するものではありません。検出なしの判定は、信頼できるローカルデーモンからの検出なしの応答が、クライアントを通じてちょうど一つ返されたことを意味します。組み込み先でより強い保証が必要な場合は、通信エラーを明示的に報告するクライアントを使ってください。
package main
import (
"bytes"
"context"
"fmt"
"io"
"os"
"os/exec"
"strings"
"time"
"github.com/dutchcoders/go-clamd"
)
type Verdict string
const (
Clean Verdict = "clean"
Infected Verdict = "infected"
ScannerError Verdict = "scanner-error"
SizeLimit Verdict = "size-limit"
maxBytes = 10 * 1024 * 1024
)
func scanStream(data []byte, socket string) Verdict {
abort := make(chan bool)
defer close(abort)
replies, err := clamd.NewClamd("unix:" + socket).ScanStream(bytes.NewReader(data), abort)
if err != nil {
return ScannerError
}
verdict := ScannerError
count := 0
for result := range replies {
count++
if result == nil || count != 1 {
return ScannerError
}
if result.Raw == "INSTREAM size limit exceeded. ERROR" ||
(result.Status == clamd.RES_FOUND &&
strings.HasPrefix(result.Description, "Heuristics.Limits.Exceeded")) {
verdict = SizeLimit
continue
}
switch {
case result.Raw == "stream: OK":
verdict = Clean
case result.Status == clamd.RES_FOUND && result.Path == "stream" && result.Description != "":
verdict = Infected
default:
verdict = ScannerError
}
}
return verdict
}
func scanFile(filePath, executable string, timeout time.Duration) Verdict {
// The caller supplies a completed, immutable file in its private quarantine directory.
info, err := os.Lstat(filePath)
if err != nil || !info.Mode().IsRegular() {
return ScannerError
}
if info.Size() > maxBytes {
return SizeLimit
}
file, err := os.Open(filePath)
if err != nil {
return ScannerError
}
defer file.Close()
data, err := io.ReadAll(io.LimitReader(file, maxBytes+1))
if err != nil {
return ScannerError
}
if len(data) > maxBytes {
return SizeLimit
}
socket := os.Getenv("CLAMD_SOCKET")
if socket == "" {
socket = "/var/run/clamav/clamd.ctl"
}
if !strings.HasPrefix(socket, "/") || timeout <= 0 {
return ScannerError
}
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
command := exec.CommandContext(ctx, executable, "--worker", "--stdin")
command.Env = []string{"CLAMD_SOCKET=" + socket}
command.Stdin = bytes.NewReader(data)
output, err := command.Output()
if err != nil || ctx.Err() != nil {
return ScannerError
}
switch verdict := Verdict(output); verdict {
case Clean, Infected, ScannerError, SizeLimit:
return verdict
default:
return ScannerError
}
}
func main() {
if len(os.Args) == 3 && os.Args[1] == "--worker" && os.Args[2] == "--stdin" {
data, err := io.ReadAll(io.LimitReader(os.Stdin, maxBytes+1))
verdict := ScannerError
if err == nil && len(data) <= maxBytes {
verdict = scanStream(data, os.Getenv("CLAMD_SOCKET"))
}
fmt.Print(verdict)
return
}
if len(os.Args) != 2 {
fmt.Fprintln(os.Stderr, "Usage: scan-example <quarantined-file>")
os.Exit(2)
}
executable, err := os.Executable()
if err != nil {
fmt.Println(ScannerError)
os.Exit(2)
}
verdict := scanFile(os.Args[1], executable, 5*time.Second)
fmt.Println(verdict)
switch verdict {
case Clean:
return
case Infected:
os.Exit(1)
case SizeLimit:
os.Exit(3)
default:
os.Exit(2)
}
}
実行前に実行ファイルをビルドしてください。タイムアウト用ラッパーは、その同じ実行ファイルをワーカーモードで起動します。終了コードは、検出なしが 0、感染が 1、スキャナーエラーが 2、サイズ制限が 3 です。
GOWORK=off go build -o scan-example . &&
CLAMD_SOCKET=/var/run/clamav/clamd.ctl ./scan-example "/path/to/quarantine/completed-upload"
ファイルパスは、非公開の隔離ディレクトリ内にあるアップロード完了済みの単一ファイルに置き換えてください。ソケットパスが異なる場合は、デーモンの LocalSocket に置き換えます。検出なしのファイルでは clean、EICAR では infected が出力されます。ビルドが成功するまでスキャンは実行されないため、再ビルドに失敗しても古いバイナリは実行されません。
タイムアウトは、ローカルのスナップショットを読み込んだ後のデーモンとの通信時間を制限します。隔離ストレージはローカルに配置し、アプリケーションの管理下に置く必要があります。このタイムアウトは、任意のネットワークマウント上のファイルに対する期限でも、ユーザーが指定したパスの認可チェックでもありません。
本番環境向けの ClamAV 設定
デーモンの制限をアプリケーションの 10 MiB 制限に合わせます。たとえば、以下は clamd.conf の設定であり、シェルコマンドではありません。
LocalSocket /var/run/clamav/clamd.ctl
LocalSocketMode 660
StreamMaxLength 10M
MaxFileSize 10M
MaxScanSize 50M
MaxRecursion 16
MaxFiles 1000
MaxThreads 4
HeuristicAlerts yes
AlertExceedsMax yes
LocalSocketGroup をアプリケーションと共有するグループに設定し、不要な TCP リスナーを削除します。ソケットディレクトリには、信頼できるプロセスだけがアクセスできるようにしてください。サイズとアーカイブの制限は過剰な処理を防ぎますが、コンテンツの一部が未スキャンになる場合もあります。AlertExceedsMax yes を設定すると、対象となるエンジン制限に達した際に
Heuristics.Limits.Exceeded… が検出結果として返されます。このプログラムでは、これをマルウェアではなく
size-limit として報告します。再帰とファイル数の制限も同じ状態で扱います。
StreamMaxLength による拒否は、別種のプロトコルエラーです。クライアントが書き込みを終える前に届く場合があり、その場合は接続または書き込みの失敗が
scanner-error として報告されます。どちらの状態でも隔離は解除しません。いずれも、ファイル全体がスキャンされたことを意味しません。全体の判定が検出なしであっても、ClamAV のほかの形式制限やパーサーの制約は引き続き適用されます。
freshclam で公式シグネチャデータベースを最新に保ってください。更新の失敗、デーモンのログ、スキャンのレイテンシ、隔離領域の処理待ち件数を監視します。設定変更後は、プラットフォームのパッケージ構成に従ってサービスを再起動または再読み込みします。同時実行数は HTTP リクエスト数だけでなく、解凍コストも含め、利用可能なメモリと CPU に合わせて調整してください。
eicar によるテスト
EICAR は、ウイルス対策エンジンが意図的に検出する、無害な 68 バイトのテスト文字列を公開しています。生成は隔離したテストディレクトリ内だけで行ってください。以下を main_test.go として保存します。クライアントパッケージの正確な EICAR バイト列と、前の手順でコンパイルしたプログラムを使用します。CLAMD_SOCKET にはテスト用デーモンの非公開ソケットを設定してください。
package main
import (
"os"
"path/filepath"
"testing"
"time"
"github.com/dutchcoders/go-clamd"
)
func TestEICAR(t *testing.T) {
if len(clamd.EICAR) != 68 {
t.Fatal("EICAR fixture must contain exactly 68 bytes")
}
executable, err := filepath.Abs("scan-example")
if err != nil {
t.Fatal(err)
}
file := filepath.Join(t.TempDir(), "eicar.txt")
if err := os.WriteFile(file, clamd.EICAR, 0600); err != nil {
t.Fatal(err)
}
if verdict := scanFile(file, executable, 5*time.Second); verdict != Infected {
t.Fatalf("EICAR must be detected as infected; got %s", verdict)
}
}
GOWORK=off go test -run '^TestEICAR$' -count=1 .
デーモンが停止している場合、このテストは失敗する必要があります。マルウェアの検出成功として扱ってはいけません。小さな検出対象を含まないテストファイル、サイズ超過のテストファイル、存在しないファイル、不正または空のデーモン応答、応答しないデーモンもテストしてください。プロトコルのテスト用データでエラー処理を決定的に検証できますが、実際のスキャナーと設定済みデータベースに対する EICAR の検証に代わるものではありません。
Go アプリケーションでのウイルススキャンのベストプラクティス
- 隔離を最優先: アップロード完了済みのファイルを非公開で保管し、変更不可のスナップショットをスキャンします。検出なしの結果を得た後に限り、その同じバイト列の隔離を解除します。公開アップロードディレクトリは使わないでください。
- 安全側に倒して拒否: スキャナーエラーや制限に達した場合は、ファイルを拒否するか隔離したまま保持します。上限のあるキューとバックオフを使って再試行し、再試行の上限に達しても隔離を解除しないでください。
- リソースの制限: アップロードサイズ、同時実行ワーカープロセス数、アーカイブの深さ、展開後のバイト数、スキャン時間、キューの長さに上限を設けます。拒否されたスキャンを種類ごとに監視してください。
- スキャナーの分離: 制限付きのローカルソケットと専用のサービスアカウントを使います。アプリケーションがバイト列をストリーミングするため、デーモンが隔離ファイルに直接アクセスする必要はありません。
- 有用なステータスの保持: 呼び出し元には一貫した判定を返し、詳細な診断情報はアクセス制御されたログに保管します。返されたエラーをすべて「ウイルス検出」として扱わないでください。
- 依存関係の見直し: バージョンを固定したクライアントは古く、I/O エラーの報告機能に制約があります。ここではプロセス分離によってキャンセルを実現していますが、最新のコンテキスト対応 API になるわけではありません。
よくある問題のトラブルシューティング
- スキャナーエラー: ソケットの権限、データベースの利用可否、デーモンの稼働状態、ログを確認します。設定したソケットが Go で使っているものと一致することを確認してください。ソケットを公開しないでください。
- タイムアウト: 五秒の制限を延長する前に、キューの深さとデーモンのリソースを調べます。タイムアウトするとワーカーは強制終了し、ファイルの隔離解除はブロックされます。
- サイズ制限: アプリケーションのサイズ制限、
StreamMaxLength、MaxFileSize、アーカイブ展開後の制限を比較します。一つの値だけを増やしても、別の制限が残る場合があります。 - EICAR が検出されない: 68 バイトのテストデータ、読み込まれたシグネチャデータベース、実際の判定を確認します。接続エラーは検出成功ではありません。
- 予期しない検出なしの結果:
HeuristicAlertsとAlertExceedsMaxを確認し、サポート形式とスキャン制限を調べ、スキャンしたバイト列を公開していることを確認します。
まとめと参考資料
ClamAV は、失敗状態を明確に扱えば、Go のアップロードパイプラインに有用なマルウェアスキャンを追加できます。アプリケーション、デーモン設定、隔離解除ポリシーの間で、スキャン成功の意味を一致させる必要があります。この例を応用する際は、以下の一次資料を参照してください。
Transloadit の 🤖 /file/virusscan Robot
は、当社のファイルフィルタリングサービスの一部として、毎日シグネチャを更新する ClamAV を使用します。error_on_decline オプションで、ファイルを拒否した際に Assembly を停止するか、そのファイルを後続の処理から除外するかを制御します。動作を選ぶ際は Robot のドキュメントを参照してください。
