Rust と ClamAV によるリアルタイムディレクトリ監視とウイルススキャン
ローカルの ClamAV デーモンで書き込み完了済みファイルをスキャンする Rust の監視ツールを作成します。ファイルを移動・削除せず、検出なし、感染あり、スキャナーエラーの結果を報告します。明示的に検出なしと応答された場合に限り、検出なしと判定します。
リアルタイム監視と Rust を使う理由は?
ファイルシステムイベントは、書き込みが完了する前に届くことがあります。一定時間の経過やファイルサイズが変わらないことは、完了の証拠にはなりません。そこで、この例ではファイル生成側の規約を定めます。一意な名前で末尾が
.part のファイルに書き込み、閉じてから、同じディレクトリ内で
.ready にアトミックに名前を変更します。.ready ファイルは決して変更しないでください。このディレクトリには、アプリケーションと信頼できる生成元だけがアクセスできるようにします。
監視ツールは、最上位の .ready ファイルのみをスキャンします。これは通知ツールであり、アクセス制御のゲートではありません。結果が示すのはスキャンしたバイト列の状態であり、変更可能なパスを後で読み取る許可ではありません。
前提条件
このチュートリアルでは Linux と Bash、Rust と Cargo 1.98.1、ClamAV 1.5.4 を使用します。定義データベースが更新済みで、Rust プロセスからアクセスできる Unix ソケットを備えたローカルの clamd デーモンを用意してください。以下のコマンドは Linux 向けで、クライアントは Unix ソケットを使用します。
ClamAV デーモン(clamd)の設定
Debian または Ubuntu では、ClamAV パッケージガイドにデーモンと定義更新ツールのパッケージが記載されています。
sudo apt-get update &&
sudo apt-get install clamav-daemon clamav-freshclam
ディストリビューションの clamd.conf で、データベースとサービスユーザーの設定を維持し、ローカルソケットを設定します。以下は設定の一部です。TCPSocket ディレクティブが有効なまま残っていないことを確認してください。
LocalSocket /var/run/clamav/clamd.ctl
LocalSocketMode 660
StreamMaxLength 10M
MaxFileSize 10M
MaxScanSize 20M
AlertExceedsMax yes
アプリケーションのサービスユーザーにソケットのグループへのアクセス権を付与し、サービスを再起動します。データベースの更新は、ディストリビューションの FreshClam サービスに任せます。ロックされたデータベースに対し、別の更新ツールを手動で実行しないでください。
sudo systemctl enable --now clamav-freshclam &&
sudo systemctl restart clamav-daemon
ClamAV プロトコルドキュメントには、ソケットと INSTREAM のフレーミングが説明されています。Clamd には TCP 認証がありません。この例では、権限でアクセスを制御したローカルソケットのみを使用します。ワークロードに合わせてアーカイブとスキャンの制限を設定してください。AlertExceedsMax が有効な場合、デーモンの制限超過アラートを検出なしとして扱ってはいけません。
プロジェクトのセットアップ
既存の Cargo プロジェクトの外にある、書き込み可能なディレクトリから始めます。Cargo は祖先ディレクトリのワークスペースに新しいパッケージを追加することがあり、設定は親ディレクトリから継承されます。以下の Bash ブロックは、何かを作成する前に、そのような場所での実行を拒否します。cargo new が成功した場合に限り、新しいプロジェクトに移動します。既存の realtime_virus_scanner ディレクトリには手を加えません。
(
cd -P . || exit 1
scanner_parent=$PWD
while :; do
if [ -e "$scanner_parent/Cargo.toml" ] ||
[ -e "$scanner_parent/.cargo/config.toml" ] ||
[ -e "$scanner_parent/.cargo/config" ]; then
printf 'Choose a directory outside existing Cargo projects/configuration.\n' >&2
exit 1
fi
[ "$scanner_parent" = / ] && break
scanner_parent=${scanner_parent%/*}
[ -n "$scanner_parent" ] || scanner_parent=/
done
cargo new realtime_virus_scanner --edition 2021 --vcs none
) && cd realtime_virus_scanner
セットアップが成功したら、新しいプロジェクトの Cargo.toml を次の内容に置き換えます。
[package]
name = "realtime_virus_scanner"
version = "0.1.0"
edition = "2021"
[dependencies]
clap = { version = "=4.5.50", features = ["derive"] }
notify = "=8.2.0"
tokio = { version = "=1.48.0", features = ["fs", "io-util", "macros", "net", "rt-multi-thread", "signal", "sync", "time"] }
アプリケーションでは Cargo.lock を保持してください。この例では、別の ClamAV クライアントラッパーに依存せず、小規模な INSTREAM のやり取りを Tokio で直接実装します。
clap によるコマンドラインインターフェイス
CLI は --directory と --socket を受け付けます。既存の書き込み完了済みファイルをスキャンして終了するには、--once を追加します。終了コードがゼロなら選択されたすべてのファイルで検出なし、一なら感染またはスキャナーエラーを示します。対象が空の場合もゼロで終了しますが、未完了の .part ファイルの状態は示しません。監視モードでは Ctrl+C が押されるまでスキャンを繰り返し、各結果を報告します。
notify によるリアルタイムディレクトリ監視
推奨のウォッチャーは、作成、変更、削除のイベント後にスキャナーを起動します。起動するたびにディレクトリ全体を再スキャンするため、容量が一のチャネルでイベントをまとめます。イベントを取りこぼした場合も、五秒間隔の状態照合でファイルを見つけます。スキャンが自分自身を起動しないように、読み取り・アクセスイベントは無視します。
Tokio による非同期ウイルススキャン
各スキャンでは、サイズに上限を設けたスナップショットを取得し、64 KiB のチャンクで送信して、最大 4097 バイトの応答を読み取ります。受け入れるのは、形式が完全に一致し、終端があり、単一の検出なし応答だけです。空、途中で切れた応答、上限超過、複数、または認識できない応答は、安全側に倒して拒否します。感染またはエンジンの制限の検出は、検出なしとは判定しません。ファイルの読み取りと clamd との通信全体に、十秒の期限を設けます。
全体の実装:src/main.rs
以下の完全なプログラムを src/main.rs として保存します。
use clap::Parser;
use notify::{Event, EventKind, RecursiveMode, Watcher};
use std::{error::Error, path::{Path, PathBuf}, time::Duration};
use tokio::{
fs::{self, File},
io::{AsyncReadExt, AsyncWriteExt},
net::UnixStream,
sync::mpsc,
time::{interval, timeout},
};
type AppResult<T> = Result<T, Box<dyn Error + Send + Sync>>;
const MAX_BYTES: u64 = 10 * 1024 * 1024;
#[derive(Parser)]
struct Args {
#[arg(long)]
directory: PathBuf,
#[arg(long, default_value = "/var/run/clamav/clamd.ctl")]
socket: PathBuf,
#[arg(long)]
once: bool,
}
#[derive(Debug, PartialEq)]
enum Verdict {
Clean,
Infected,
ScannerError,
}
fn parse_reply(reply: &[u8]) -> Verdict {
if reply == b"stream: OK\0" {
return Verdict::Clean;
}
if let Some(name) = reply.strip_prefix(b"stream: ")
.and_then(|value| value.strip_suffix(b" FOUND\0"))
{
if !name.is_empty() && !name.iter().any(|byte| byte.is_ascii_control()) {
return Verdict::Infected;
}
}
Verdict::ScannerError
}
async fn scan(path: &Path, socket: &Path) -> AppResult<Verdict> {
// The private-directory producer contract forbids modifying published .ready files.
if !fs::symlink_metadata(path).await?.file_type().is_file() {
return Err("Input must be a regular, non-symlink file".into());
}
let file = File::open(path).await?;
if !file.metadata().await?.is_file() {
return Err("Input must be a regular file".into());
}
let mut bytes = Vec::new();
file.take(MAX_BYTES + 1).read_to_end(&mut bytes).await?;
if bytes.len() as u64 > MAX_BYTES {
return Err("Input exceeds 10 MiB".into());
}
let mut stream = UnixStream::connect(socket).await?;
stream.write_all(b"zINSTREAM\0").await?;
for chunk in bytes.chunks(64 * 1024) {
stream.write_all(&(chunk.len() as u32).to_be_bytes()).await?;
stream.write_all(chunk).await?;
}
stream.write_all(&0u32.to_be_bytes()).await?;
let mut reply = Vec::new();
stream.take(4097).read_to_end(&mut reply).await?;
Ok(if reply.len() > 4096 {
Verdict::ScannerError
} else {
parse_reply(&reply)
})
}
async fn scan_directory(args: &Args) -> AppResult<bool> {
let mut entries = fs::read_dir(&args.directory).await?;
let mut all_clean = true;
while let Some(entry) = entries.next_entry().await? {
let path = entry.path();
if path.extension().and_then(|value| value.to_str()) != Some("ready") {
continue;
}
let verdict = match timeout(Duration::from_secs(10), scan(&path, &args.socket)).await {
Ok(Ok(verdict)) => verdict,
_ => Verdict::ScannerError,
};
all_clean &= verdict == Verdict::Clean;
// Debug path formatting escapes newlines and control characters in filenames.
println!("{verdict:?} {:?}", path.file_name());
}
Ok(all_clean)
}
async fn monitor(args: &Args) -> AppResult<bool> {
if args.once {
return scan_directory(args).await;
}
let (tx, mut rx) = mpsc::channel(1);
let mut watcher = notify::recommended_watcher(move |event: notify::Result<Event>| {
let changed = match event {
Ok(event) => matches!(
event.kind,
EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_)
),
Err(_) => {
eprintln!("Watcher error; periodic reconciliation remains active.");
true
}
};
if changed {
// A full queue already guarantees a complete directory reconciliation.
let _ = tx.try_send(());
}
})?;
watcher.watch(&args.directory, RecursiveMode::NonRecursive)?;
let mut ticks = interval(Duration::from_secs(5));
loop {
tokio::select! {
_ = ticks.tick() => {}
event = rx.recv() => {
if event.is_none() {
return Err("Watcher channel closed".into());
}
}
}
scan_directory(args).await?;
}
}
async fn run() -> AppResult<bool> {
let args = Args::parse();
tokio::select! {
result = monitor(&args) => result,
result = tokio::signal::ctrl_c() => {
result?;
Err("Scanning interrupted".into())
}
}
}
#[tokio::main]
async fn main() {
match run().await {
Ok(true) => {}
Ok(false) => std::process::exit(1),
Err(_) => {
eprintln!("Scanner stopped; check the directory, socket, and daemon configuration.");
std::process::exit(1);
}
}
}
プロジェクトディレクトリからビルドし、新しい非公開の受信ディレクトリを使って監視ツールを起動します。各処理が成功した場合にのみ次へ進むため、ビルドに失敗しても古い実行ファイルは起動しません。
mkdir -m 700 inbox &&
cargo build --jobs 2 --target-dir target &&
./target/debug/realtime_virus_scanner --directory inbox --socket /var/run/clamav/clamd.ctl
デーモンが別のパスを使っている場合は、ソケット引数を変更してください。このターミナルは実行したままにします。別のターミナルでプロジェクトディレクトリに移動し、未使用の名前の組を使って、書き込みを完了したファイルを公開します。
(
set -o noclobber
test ! -e inbox/example.ready &&
test ! -L inbox/example.ready &&
test ! -e inbox/example.part &&
test ! -L inbox/example.part &&
printf 'A completed example file.\n' > inbox/example.part &&
mv -n -- inbox/example.part inbox/example.ready &&
test ! -e inbox/example.part
)
検出なしのスキャンでは Clean Some("example.ready") が表示されます。状態照合で完了済みファイルを再スキャンするため、複数回表示されることがあります。生成側のブロックは、いずれかの名前がすでに存在すると、内容を置き換えずに非ゼロを返します。後続のファイルには新しい名前を使い、同じ名前で生成処理を並行実行しないでください。printf コマンドでファイルを閉じてから、mv で公開します。
監視ツールのターミナルで Ctrl+C を押すと停止します。同じ受信ディレクトリを一度だけスキャンするには、次を実行します。
./target/debug/realtime_virus_scanner --directory inbox --socket /var/run/clamav/clamd.ctl --once
エラー処理と通知
ScannerError は、ソケットが利用できない、入力が 10 MiB を超える、シンボリックリンクである、期限が切れたといった理由でスキャンが失敗したことを示します。Infected には、ClamAV で設定された制限超過アラートも含まれます。どちらの結果でも、後続の利用側にファイルを渡すべきではありません。この例では、スキャンの失敗によってアップロードが削除されないように、意図的にすべてのファイルをその場に残します。
Ctrl+C は実行中のスキャンの Future を破棄し、ソケットを閉じ、ウォッチャーを解放して、非ゼロで終了します。監視モードでは、失敗したスキャンを後の状態照合で再試行します。検出なしではない結果を含むバッチについて、呼び出し元が失敗を示す終了コードを必要とする場合は、--once を使用します。
パフォーマンスに関する考慮事項
同時に実行するスキャンは一つ、保留する起動通知は一つで、ファイルごとのスナップショットと応答には上限があります。ディレクトリの列挙では、パスのキューを蓄積しません。完了済みファイルをすべて再スキャンすることで、スループットを犠牲にして、小規模で復旧しやすい例にしています。より大規模なサービスでは、処理状況を永続的に追跡し、各判定を、実際にスキャンした正確な不変オブジェクトに関連付ける必要があります。
この監視ツールは再帰的に動作しません。また、五秒間隔は状態照合のスケジュールであり、検出までの時間を保証するものではありません。バッチが大きい場合やスキャンが遅い場合は、さらに時間がかかります。サービス運用の一環として、定義を維持し、デーモンのアーカイブ制限をテストしてください。
まとめ
.ready ファイルを公開するのは、信頼できる生成元だけに限定します。利用側は、この監視ツールの結果をファイル配信の許可として扱ってはいけません。Clean は、設定された ClamAV エンジンがスキャンしたバイト列から何も検出しなかったことを意味し、ファイルが無害であることを意味しません。定義を最新に保ち、受け入れる形式に合わせてデーモンの制限を選択してください。
Transloadit も、🤖 /file/virusscan Robotを通じたファイルのフィルタリングに ClamAV を使用しています。
