Node.js でマジックナンバーによる API ファイルアップロードの検証
avatar.png という名前のアップロードが PNG とは限りません。このチュートリアルでは、PNG と JPEG のアップロードをバイト列から識別し、検出したほかの形式を拒否して、ファイルとリクエストのバイト数を制限するローカルの Node.js エンドポイントを実行します。成功レスポンスは、シグネチャが許可リストに一致したことを意味するだけで、画像の有効性や安全性を示しません。
拡張子の検証だけでは不十分な理由
ファイル名とファイルパートの Content-Type はクライアントが指定します。ファイル名を変更したり、image/png と宣言したりしても、内容は変わりません。以下のエンドポイントは、検出した形式を許可するかどうかの判断で、意図的に両方を無視します。また、クライアントのファイル名を保存パスに使うこともありません。OWASP のアップロードガイダンスでは、クライアントの MIME タイプをセキュリティ境界にできない理由を説明しています。
マジックナンバーとファイルシグネチャの理解
マジックナンバーは、ファイル形式を推定する手がかりとなる、識別可能なバイト列です。PNG は 89 50 4E 47 0D 0A 1A 0A、JPEG は FF D8 FF で始まります。検出ライブラリは、手書きの短いプレフィックス検査より詳しい形式情報を持っていますが、それでも画像全体をデコードするわけではありません。
file-type のドキュメントでは、検出結果はベストエフォートの手がかりであり、ファイルの有効性を証明するものではないとしています。破損したファイルには、一致しなかったり例外が発生したりするものもあれば、識別可能なシグネチャが残っているものもあります。結果を valid と命名したり、マルウェアの判定として使ったりしないでください。
Node.js でのマジックナンバー検証の実装
Linux 上の Bash、cURL、Node.js 24.15.0 または 24 LTS 系のそれ以降のリリースと、Yarn 4.12.0 を利用できる Corepack を使用してください。この例は Node.js 24.15.0 と 26.8.1 でテスト済みです。デプロイには、最新のパッチを適用した LTS リリースを使用し、テスト済みの最小バージョンをセキュリティ更新の推奨バージョンと捉えないでください。
書き込み可能なディレクトリで開始してください。次のコマンドは、シェルの作業ディレクトリを変えずに、新しい magic-upload プロジェクトを作成します。プロジェクトディレクトリがすでに存在する場合は処理を拒否し、作成や移動に失敗した場合はインストール前に停止します。ローカルの yarn.lock により、独立した Yarn プロジェクトを構成します。node-modules リンカーにより、Yarn Plug’n’Play の親プロジェクト内でも、通常の node コマンドで依存関係を解決できます。
(
mkdir magic-upload &&
cd magic-upload &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
touch yarn.lock &&
YARN_NODE_LINKER=node-modules corepack yarn add --exact \
express@4.22.2 file-type@22.0.0 multer@2.4.0
)
Multer 2.4.0 は、以下で使う streamHandler オプションを提供し、アップロードのクリーンアップに関するセキュリティ修正を含みます。この例を応用する際は、アップロード関連の依存関係に最新のパッチを適用してください。
Express.js でのサイズ制限付きアップロードの検証
プログラム全体を magic-upload/server.mts として保存してください。Node のネイティブの型除去機能は、この .mts ファイルを、コンパイラーや TypeScript ローダーなしで
ES モジュールとして実行します。プログラムの型チェックや、上位ディレクトリの tsconfig.json の読み取りは行いません。
最初のミドルウェアは express.raw を使い、multipart の解析前に、5 MiB + 16 KiB を上限としてリクエスト本文全体を読み取ります。ファイル内容だけでなく、境界、パートヘッダー、本文の末尾のバイト列も対象となり、Content-Length のないリクエストも含みます。その後、Multer が別途 5 MiB のファイル制限を適用し、file という名前のファイルパートを一つだけ受け入れます。テキストフィールドは許可しません。streamHandler は、読み取り済みのリクエストストリームを再び読む代わりに、すでに読み取った本文を multipart パーサーに渡します。
import express, { type ErrorRequestHandler, type Request, type Response } from 'express'
import { fileTypeFromBuffer } from 'file-type'
import multer from 'multer'
const app = express()
const maxFileBytes = 5 * 1024 * 1024
const maxRequestBytes = maxFileBytes + 16 * 1024
const allowedTypes = new Set(['image/png', 'image/jpeg'])
async function identifyUpload(request: Request, response: Response): Promise<void> {
if (!request.file || request.file.size === 0) {
response.status(400).json({ error: 'Send one nonempty file in the file field' })
return
}
const type = await fileTypeFromBuffer(request.file.buffer)
if (type === undefined || !allowedTypes.has(type.mime)) {
response.status(415).json({ error: 'Only detected PNG or JPEG files are allowed' })
return
}
response.json({ detectedMime: type.mime, size: request.file.size })
}
app.post(
'/upload',
express.raw({ type: 'multipart/form-data', limit: maxRequestBytes, inflate: false }),
(request, response, next) => {
if (!Buffer.isBuffer(request.body)) {
response.status(415).json({ error: 'Send multipart/form-data' })
return
}
const body = request.body
const upload = multer({
storage: multer.memoryStorage(),
limits: { fileSize: maxFileBytes, files: 1, fields: 0, parts: 1 },
streamHandler: (_request, parser) => parser.end(body),
})
upload.single('file')(request, response, (error: unknown) => {
if (error) return next(error)
void identifyUpload(request, response).catch(() => {
response.status(400).json({ error: 'Unable to identify the file' })
})
})
},
)
const rejectUpload: ErrorRequestHandler = (error: unknown, _request, response, _next) => {
const tooLarge =
(error instanceof multer.MulterError && error.code === 'LIMIT_FILE_SIZE') ||
(error instanceof Error && 'type' in error && error.type === 'entity.too.large')
response.status(tooLarge ? 413 : 400).json({
error: tooLarge ? 'Upload exceeds byte limit' : 'Malformed upload',
})
}
app.use(rejectUpload)
const port = Number(process.env.PORT ?? '3000')
if (!Number.isInteger(port) || port < 0 || port > 65535) {
throw new Error('PORT must be an integer between 0 and 65535')
}
const server = app.listen(port, '127.0.0.1')
server.on('listening', () => {
const address = server.address()
if (address !== null && typeof address !== 'string') {
console.log(`Listening on http://127.0.0.1:${address.port}`)
}
})
server.on('error', () => {
console.error('Could not start the upload server; check PORT and whether it is in use')
process.exitCode = 1
})
セットアップを実行したディレクトリで、フォアグラウンドのサーバーを起動してください。
node magic-upload/server.mts
待ち受け URL が表示されてからリクエストを送信してください。ポート 3000 が使用中の場合は、同じコマンドの実行時に PORT を別の空きポートに設定し、リクエスト URL もそれに合わせて変更してください。Ctrl+C でサーバーを停止すると、シェルに戻ります。エンドポイントはループバックにバインドし、アップロードをメモリ内に保持します。アップロードされたファイルをディスクに書き込むことはありません。
実装のテスト
別のターミナルで、magic-upload を含むディレクトリに戻ってください。実際の形式とは異なる .bin というファイル名で、一画素の PNG を作成します。新規作成専用の書き込みのため、既存の sample.bin の上書きは拒否されます。再作成する場合は、そのデモファイルを明示的に削除してください。
node --input-type=module -e '
import { writeFileSync } from "node:fs"
const png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQI12P4z8DwHwAFAAH/cpxSZwAAAABJRU5ErkJggg=="
writeFileSync("magic-upload/sample.bin", Buffer.from(png, "base64"), { flag: "wx" })
'
ファイルパートの MIME タイプを意図的に誤った値にしてアップロードします。
curl -fsS -F 'file=@magic-upload/sample.bin;type=text/plain' \
http://127.0.0.1:3000/upload
レスポンスは、.bin や text/plain ではなく、受信したファイルのバイト列に基づきます。
{"detectedMime":"image/png","size":70}
次に、通常のテキストを PNG として申告します。このコマンドは、想定どおりの拒否を cURL の失敗として扱わず、HTTP ステータスを表示します。
printf '%s' 'not an image' | curl -sS -o /dev/null -w '%{http_code}\n' \
-F 'file=@-;filename=avatar.png;type=image/png' http://127.0.0.1:3000/upload
415 が返るはずです。エンドポイントを応用する際は、次の動作もテストしてください。
- 形式と無関係なファイル名の有効な JPEG には、
image/jpegと実際のファイルのバイト数を返す - ファイルがない場合や空の場合は
400を返す。multipart 本文の破損や想定外のフィールドにも400を返す - 不明なシグネチャや、GIF、PDF など識別できても許可されていない形式には
415を返す - 5 MiB 以下のファイル内容はサイズ検査に合格し、一バイトでも超えると
413を返す - 5 MiB + 16 KiB 以下のリクエスト本文はリクエストサイズ検査に合格し、一バイトでも超えると、追加のバイトが multipart の最終境界より後にあっても
413を返す。どちらの上限以下でも、形式とフォームの検査は引き続き適用される
エッジケースとポリグロットファイルへの対応
三バイトの FF D8 FF プレフィックスは、完全な画像を含んでいなくても JPEG として識別されることがあります。内容の後半が破損している画像も、検査に通ることがあります。エンドポイントは、デコードの成功や安全性の判定ではなく、意図的に detectedMime を報告します。ポリグロットファイルは複数の形式として解釈できます。内部の疑わしいバイト列を検索する方法は、信頼できる検出手段ではありません。
シグネチャの識別後に、保守されている形式別のデコーダー、画像寸法とピクセル数の制限、脅威モデルに適したコンテンツのセキュリティスキャンや再構成を組み合わせてください。信頼できないデータを扱うパーサーは、実行制限を強制した隔離環境で実行してください。このローカルの例は、これらを一切行わず、不正な画像をすべて拒否するわけではありません。
メモリとセキュリティの境界の明確化
これは小容量アップロードのデモであり、大容量ファイルのストリーミングパイプラインではありません。生の本文と Multer のファイルバッファーが同時に存在し、さらにパーサーやメモリ割り当てのオーバーヘッドが加わります。ファイルサイズの上限は、プロセス全体のメモリ、同時アップロード数、検出時間の上限ではありません。大容量ファイルには、別の保存先とポリシーが必要です。固定長のプレフィックスも、シグネチャの一致も、アップロードの残りの部分を検査済みとは証明しません。このチュートリアルは全体を通して Node.js を使用し、Python や libmagic は不要です。
マジックナンバー検証とほかの対策の組み合わせ
アップロードエンドポイントを公開する前に、適切なアプリケーションまたはプロキシの境界で、認証、認可、レート制限、同時実行数の制限、リクエストの処理期限を追加してください。依存関係には最新のパッチを適用してください。アップロードを永続化する場合は、保存名を生成し、処理前にファイルを隔離して、アプリケーションのオリジンからアクティブコンテンツを配信しないようにしてください。これらは個別の対策であり、file-type が備える性質ではありません。OWASP のアップロードに関する完全なチェックリストを参照してください。
よくある問題のトラブルシューティング
- 待ち受け URL が表示されない: 起動時の診断情報、
PORT、アドレスが使用中でないかを確認してください。そのポートをすでに使っている無関係なサービスに、テスト用のアップロードを送らないでください。 - パッケージが見つからない:
magic-upload内でインストールを完了し、記載どおりの.mtsというファイル名を使ってください。ESM のインポートを CommonJS のrequire()に置き換えないでください。 - 想定外の
400: 空でないファイルをfileという名前で一つだけ送信し、ほかのフォームフィールドは含めないでください。識別時の例外も、内部エラーを公開せずに報告されます。 - 想定外の
413: ファイルサイズだけでなく、multipart 本文全体を確認してください。パートヘッダーと境界も、リクエスト用に追加された 16 KiB の枠を消費します。
このエンドポイントを保存や処理につなぐ際も、「識別済み」と「検証済み」を区別してください。マネージドなアップロードワークフローについては、当社のファイルアップロードサービスをご覧ください。ただし、アプリケーションが何を受け入れるかのポリシーは、引き続き利用者側で定める必要があります。
