Node.js で ClamAV によるサーバー側マルウェアスキャンを実装
アップロードしたファイルは、マルウェアスキャンが完了するまで非公開にします。このチュートリアルでは、未検出、検出、スキャン未完了を区別し、その後アップロードされたコピーを削除するローカルの Node.js エンドポイントを構築します。通常のテキストと、無害な EICAR ウイルス対策テスト文字列で動作をテストします。
スキャン結果の意味の定義
ClamAV の clamd デーモンは、ウイルス対策エンジンを読み込んだ状態で保持し、ソケット経由でスキャン要求を受け付けます。Node.js パッケージの clamscan は、このデーモンのクライアントです。scanStream メソッドはバイト列を送信するため、デーモンがアプリケーションのアップロードディレクトリにアクセスする必要はありません。
スキャンが完了し、何も検出されなかったとしても、ファイルの安全性が証明されたわけではありません。未対応の形式、暗号化された内容、新たな脅威、形式固有のスキャン制限を考慮する必要があります。この例では、エラーや制限アラートが報告されたファイルを拒否しますが、検査をすり抜けるあらゆる理由を特定するものではありません。ファイル形式の検証と後続処理の安全性確保は、別の対策として維持してください。
サーバーでの ClamAV のセットアップ
Linux、cURL、および最新のパッチを適用した Node.js 24 または 26 LTS リリースを使用してください。パッチバージョンを選ぶ際は、保守対象のリリース系列とセキュリティ更新を確認してください。この例全体は Node.js 24.22.2 と 26.13.0、Corepack 0.34.5、Yarn 4.12.0、ClamAV 1.5.4、および clamscan@2.4.0 でテストしています。Corepack がない場合は、先に Corepack をインストールしてください。Node.js 26 には同梱されていません。Node アプリケーションを起動する前に、公式シグネチャデータベースを備えた非公開の clamd を稼働させる必要があります。まだ用意していない場合は、ClamAV インストールガイドとデーモン設定ガイドに従ってください。データベースのインストールとサービス管理の方法は、Linux ディストリビューションによって異なります。
テスト専用デーモンの設定で、次の各オプションを一度ずつ設定し、既存の値を置き換えてから再起動してください。DatabaseDirectory と LocalSocket の既存のパスは維持します。ソケットとその親ディレクトリへのアクセスは、アプリケーションユーザーだけに許可してください。公開 TCP リスナーは有効にしないでください。
StreamMaxLength 26M
MaxFileSize 25M
MaxScanSize 100M
MaxRecursion 16
MaxFiles 1000
AlertExceedsMax yes
これらの制限は、それぞれ役割が異なります。StreamMaxLength は、ソケット経由で送信するバイト数を制限します。MaxFileSize は、アーカイブから展開した各ファイルを含め、個々のファイルに適用されます。MaxScanSize は、展開された内容も含む、入力ごとのスキャン処理総量を制限します。AlertExceedsMax を使用すると、対応する制限違反に対して
Heuristics.Limits.Exceeded アラートが生成されます。以下のラッパーは、これらをマルウェアの特定ではなく、スキャン未完了として扱います。各制限の正確な適用範囲は、バージョン別の設定リファレンスを参照してください。
FreshClam を使って公式シグネチャを更新し、更新からの経過時間を監視してください。FreshClam サービスがすでに管理しているデータベースに対して、別の更新プログラムを実行しないでください。このチュートリアルは、デーモンが読み込んだデータベースを使用します。Node パッケージは、シグネチャのダウンロードもデーモンの制限の変更も行いません。
ClamAV と Node.js の統合
書き込み可能なディレクトリで、次のセットアップブロックを貼り付けてください。新しい node-clamav プロジェクトを作成し、既存のディレクトリの上書きは拒否します。ロックファイルによって独立した Yarn プロジェクトを開始します。nodeLinker は node_modules インストールを選択し、ignorePath は、親プロジェクトの yarnPath が固定した Yarn バージョンを上書きするのを防ぎます。インストールに失敗した場合は、解決してから先に進んでください。
(
set -eu
mkdir -m 700 node-clamav
cd node-clamav
printf '{"private":true,"type":"commonjs","packageManager":"yarn@4.12.0"}\n' > package.json
printf 'nodeLinker: node-modules\nignorePath: true\n' > .yarnrc.yml
touch yarn.lock
corepack yarn add --exact clamscan@2.4.0 express@5.2.1 multer@2.4.0
)
次の三つのファイルを node-clamav 内に保存してください。これらは明示的な CommonJS の .cjs 拡張子を使用し、ビルド工程なしで Node から直接実行します。
まず、ClamAVScanner.cjs を保存してください。このラッパーは、ファイルにも起動時のプローブにも、パッケージのストリーミング API を使用します。クライアントがソケットを開いている間に入力ファイルがなくなる場合があるため、接続前にエラーリスナーを登録します。
const { createReadStream } = require('node:fs')
const { stat } = require('node:fs/promises')
const { Readable } = require('node:stream')
const ClamScan = require('clamscan')
const MAX_FILE_BYTES = 25 * 1024 * 1024
class ClamAVScanner {
async initialize(socket) {
this.clamscan = await new ClamScan().init({
clamscan: { active: false },
preference: 'clamdscan',
clamdscan: { socket, timeout: 10000, localFallback: false },
})
this.isInitialized = true
}
async scanFile(filePath) {
const info = await stat(filePath)
if (!info.isFile() || info.size === 0 || info.size > MAX_FILE_BYTES) {
throw new Error('File is empty, invalid, or exceeds the scan limit')
}
return this.scanStream(createReadStream(filePath))
}
async scanBuffer(buffer) {
if (!Buffer.isBuffer(buffer) || buffer.length === 0 || buffer.length > MAX_FILE_BYTES) {
throw new Error('Buffer is empty, invalid, or exceeds the scan limit')
}
return this.scanStream(Readable.from([buffer]))
}
async scanStream(input) {
if (!this.isInitialized) {
input.destroy()
throw new Error('ClamAV scanner not initialized')
}
const inputError = new Promise((_, reject) => input.once('error', reject))
try {
const result = await Promise.race([inputError, this.clamscan.scanStream(input)])
if (
!result || result.timeout === true ||
(result.isInfected !== true && result.isInfected !== false) ||
!Array.isArray(result.viruses) ||
!result.viruses.every((name) => typeof name === 'string')
) {
throw new Error('Scan result is inconclusive')
}
const { isInfected, viruses } = result
if (
viruses.some((name) => name.startsWith('Heuristics.Limits.Exceeded')) ||
isInfected !== (viruses.length > 0)
) {
throw new Error('Scan limit or inconsistent result; scan is inconclusive')
}
return { isInfected, viruses }
} finally {
input.destroy()
}
}
}
module.exports = ClamAVScanner
次に、scan-worker.cjs を保存してください。各ワーカーは一つのクライアント接続を所有します。ファイルパスがない場合は、起動時の小規模なスキャンを要求します。実際のアップロードには、非公開の一時パスを使用します。
const { parentPort, workerData } = require('node:worker_threads')
const ClamAVScanner = require('./ClamAVScanner.cjs')
async function main() {
const scanner = new ClamAVScanner()
await scanner.initialize(workerData.socket)
const result = workerData.filePath === null
? await scanner.scanBuffer(Buffer.from('scanner startup probe'))
: await scanner.scanFile(workerData.filePath)
parentPort.postMessage({ result })
}
main().catch((error) => {
parentPort.postMessage({ errorCode: typeof error?.code === 'string' ? error.code : 'SCAN_FAILED' })
})
ClamAV によるアップロードファイルのスキャン
server.cjs を保存してください。ループバックでのみ待ち受け、一度に一つのアップロードを受け付けます。Multer は、単一の file フィールドを、新しく作成した非公開ディレクトリに書き込みます。アップロードの上限は 25 MiB です。アップロードされたファイル名がファイルシステムのパスになることはなく、アプリケーションがこれらのディレクトリを公開することもありません。
10 秒のスキャン期限には、クライアントの初期化も含まれます。Promise が拒否されるだけではソケット操作はキャンセルされないため、アプリケーションは
worker.terminate() の完了を待ってから、一時入力を削除します。これにより Node クライアントは停止しますが、clamd がすでに受け付けた処理のキャンセルは保証されません。デーモン自体の制限は引き続き適用されます。
const { mkdtemp, rm } = require('node:fs/promises')
const { createServer } = require('node:http')
const { tmpdir } = require('node:os')
const { join, resolve } = require('node:path')
const { Worker } = require('node:worker_threads')
const express = require('express')
const multer = require('multer')
const app = express()
let uploadRoot
let busy = false
let stopping = false
let socket
function diagnosticCode(error) {
return ['ENOENT', 'EACCES', 'EEXIST', 'EADDRINUSE', 'ECONNREFUSED', 'ETIMEDOUT'].includes(error?.code)
? error.code
: 'SCAN_FAILED'
}
async function scanFile(filePath) {
const worker = new Worker(join(__dirname, 'scan-worker.cjs'), {
workerData: { socket, filePath },
stdout: true,
stderr: true,
})
// The client can print raw errors even with debugMode disabled.
worker.stdout.resume()
worker.stderr.resume()
let timer
try {
return await new Promise((resolveScan, reject) => {
timer = setTimeout(() => {
reject(Object.assign(new Error('Scan deadline exceeded'), { code: 'ETIMEDOUT' }))
}, 10000)
worker.once('message', (message) => {
if (message.errorCode) {
reject(Object.assign(new Error('Scan failed'), { code: message.errorCode }))
} else {
resolveScan(message.result)
}
})
worker.once('error', reject)
worker.once('exit', () => reject(new Error('Scanner exited without a result')))
})
} finally {
clearTimeout(timer)
await worker.terminate()
}
}
app.post('/upload', async (req, res) => {
if (busy || stopping) return res.status(503).json({ result: 'busy' })
busy = true
let directory
let status = 503
let result = 'inconclusive'
try {
directory = await mkdtemp(join(uploadRoot, 'request-'))
const upload = multer({
dest: directory,
limits: { fileSize: 25 * 1024 * 1024, files: 1, fields: 0, parts: 2 },
}).single('file')
await new Promise((resolveUpload, reject) => {
upload(req, res, (error) => error ? reject(error) : resolveUpload())
})
if (!req.file || req.file.size === 0) {
status = 400
result = 'invalid-upload'
} else {
const scan = await scanFile(req.file.path)
status = scan.isInfected ? 403 : 200
result = scan.isInfected ? 'detected' : 'no-detection'
}
} catch (error) {
if (error instanceof multer.MulterError) {
status = error.code === 'LIMIT_FILE_SIZE' ? 413 : 400
result = 'invalid-upload'
} else {
console.error('File scan could not be completed', { code: diagnosticCode(error) })
}
} finally {
if (directory) {
try {
await rm(directory, { recursive: true, force: true })
} catch (error) {
status = 500
result = 'cleanup-failed'
stopping = true
console.error('Temporary file cleanup failed', { code: diagnosticCode(error) })
}
}
busy = false
}
if (!res.destroyed) res.status(status).json({ result })
})
async function main() {
const port = Number(process.env.PORT ?? '3000')
if (!Number.isInteger(port) || port < 0 || port > 65535 || !process.env.CLAMD_SOCKET) {
throw new Error('Set CLAMD_SOCKET and a valid PORT')
}
socket = resolve(process.env.CLAMD_SOCKET)
const probe = await scanFile(null)
if (probe.isInfected) throw new Error('Startup probe triggered a detection')
uploadRoot = await mkdtemp(join(tmpdir(), 'node-clamav-'))
const server = createServer({ requestTimeout: 15000, connectionsCheckingInterval: 1000 }, app)
await new Promise((resolveListen, reject) => {
server.once('error', reject)
server.listen(port, '127.0.0.1', resolveListen)
})
console.log(`Listening on http://127.0.0.1:${server.address().port}`)
const stop = () => {
if (stopping && !server.listening) return
stopping = true
server.close(() => {
rm(uploadRoot, { recursive: true, force: true }).catch((error) => {
console.error('Temporary file cleanup failed', { code: diagnosticCode(error) })
process.exitCode = 1
})
})
}
process.on('SIGINT', stop)
process.on('SIGTERM', stop)
}
main().catch(async (error) => {
console.error('Server startup failed; check CLAMD_SOCKET, PORT, and daemon status', {
code: diagnosticCode(error),
})
if (uploadRoot) {
await rm(uploadRoot, { recursive: true, force: true }).catch(() => {
console.error('Temporary file cleanup failed')
})
}
process.exitCode = 1
})
親ディレクトリから、ターミナルでサーバーを起動してください。ソケットパスは、デーモンの LocalSocket の値に置き換えます。たとえば、一部の Ubuntu パッケージは /var/run/clamav/clamd.ctl を使用します。起動時のプローブが成功しない限り、準備完了を示す URL は表示されません。3000 が使用中の場合は、PORT に別のポートを設定してください。
(cd node-clamav && CLAMD_SOCKET=/absolute/path/to/clamd.sock node server.cjs)
無害なファイルと EICAR テスト文字列の送信
同じ親ディレクトリで別のターミナルを開き、次のブロックを貼り付けてください。既存のファイルを置き換えず、新しいテストファイルを作成します。EICAR は、実際のマルウェアではなく、無害なウイルス対策テストパターンです。コンピューターのウイルス対策ソフトが隔離する場合があります。ファイルを保持するために保護を無効にしないでください。
(
set -eu
cd node-clamav
node <<'JS'
const { writeFileSync } = require('node:fs')
writeFileSync('hello.txt', 'ordinary upload\n', { flag: 'wx' })
writeFileSync('eicar.txt', 'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*', { flag: 'wx' })
JS
curl -sS -i --max-time 20 -F 'file=@hello.txt' http://127.0.0.1:3000/upload
curl -sS -i --max-time 20 -F 'file=@eicar.txt' http://127.0.0.1:3000/upload
)
最初のリクエストでは、HTTP 200 と {"result":"no-detection"} が返るはずです。EICAR のリクエストでは、HTTP 403 と {"result":"detected"} が返るはずです。これらのコマンドでは、拒否レスポンスを確認できるよう、cURL の
-f オプションを意図的に省略しています。PORT を変更した場合は、両方の URL を更新してください。作成したファイルはプロジェクト内に残り、サーバーにアップロードされたコピーだけが削除されます。
失敗の解釈と削除の確認
| HTTP ステータス | 結果 | 意味 |
|---|---|---|
| 200 | no-detection | 設定されたスキャンで、既知の脅威は検出されませんでした。 |
| 403 | detected | スキャナーが検出結果を返しました。 |
| 400 | invalid-upload | マルチパートフィールドが未指定、空、または未対応です。 |
| 413 | invalid-upload | アップロードが 25 MiB を超えました。 |
| 503 | inconclusive | スキャンエラー、アップロード解析エラー、または制限アラートにより結果を得られませんでした。 |
| 503 | busy | 別のリクエストを処理中、またはサーバーを停止中です。 |
| 500 | cleanup-failed | 削除に失敗したため、サーバーは以降のアップロードを拒否します。 |
アップロードの拒否時やスキャンの失敗時も含め、削除処理は JSON レスポンスの送信前に実行されます。ただし、ファイルシステムの障害により削除できない場合はあります。その場合、サーバーは障害を報告し、新たな処理の受け付けを停止します。Ctrl+C は新しい接続を停止し、処理中のリクエストの完了を待って、プロセスの一時ルートを削除します。クラッシュや強制終了では、ファイルが残る場合があります。これはローカルスキャンのデモであり、アップロードの保持、認証、本番環境の可用性保証はありません。
よくある問題のトラブルシューティング
起動に失敗する場合は、CLAMD_SOCKET が待ち受け中のソケットを指していることと、実行ユーザーがその親ディレクトリをたどれることを確認してください。ENOENT はパスの不存在、EACCES は権限の問題、EADDRINUSE は HTTP ポートが使用中であることを示します。原因を修正して再起動してください。アプリケーションが別のスキャナーへ暗黙に切り替わることはありません。
小さなテキストファイルは処理できても、アーカイブで inconclusive が返る場合は、非公開デーモンのログでスキャン制限を確認してください。圧縮された小さなアップロードでも、展開後に MaxFileSize または
MaxScanSize を超える場合があります。HTTP アップロードの上限だけを引き上げても、どちらの制限も変わりません。デーモンが応答しなくなると、アプリケーションはスキャン期限後に
inconclusive を返します。アップロードの受信には、別途 15 秒の HTTP リクエストタイムアウトがあり、JSON の送信前に接続が閉じる場合があります。
スキャン境界の非公開化
このエンドポイントを実際のアップロードパイプラインに組み込む前に、受け付ける形式と、暗号化などで検査できない内容の扱いを決めてください。処理待ちファイルは公開ストレージの外に置き、同時実行数に上限を設け、シグネチャの鮮度とスキャン未完了の両方を監視してください。ファイルの保持を追加する場合は、結果がポリシーを満たした後に限り、スキャンしたものと同じバイト列を保存先へ移動してください。clamd の認証なしプロトコルを、信頼できないクライアントに公開しないでください。
