Magika と Python API で Web アップロードを検証
photo.jpg という名前のファイルでも、PDF が入っている場合があります。アップロードの種類を確認するには、ファイルのバイト列を
Magika の Python API に送り、返されたラベルに許可リストを適用します。このチュートリアルでは、アップロードページと分類用エンドポイントの両方を提供するローカルの Flask アプリを作成し、現在選択されているファイルに対応するフィードバックを表示します。
ブラウザーはファイル全体を Python に送信します。両方のプロセスを手元のノートパソコンで実行していても、分類はそのサーバー上で行われます。種類が許可されても、ファイルが有効であることや、マルウェアを含まないことの証明にはなりません。
ラベルから判断できる範囲を決める
拡張子とクライアントが指定する MIME タイプは、ファイルが何であると申告しているかを示します。一方、コンテンツ検出ツールはバイト列を調べるため、ファイル名を変更しても入力は変わりません。Magika は学習済みモデルを使ってバイナリ形式やテキスト形式を識別しますが、誤分類する場合もあります。
Python API は、identify_bytes()、result.ok 内の成功フラグ、result.output 内の最終予測を公開しています。許可リストとの照合には result.output.label を使ってください。デフォルトの HIGH_CONFIDENCE モードでは、信頼度の低いモデル予測を汎用ラベルに置き換えることがあります。この例では、そのラベルも許可リストにない他の種類と同様に拒否します。
Magika とシグネチャベースの検出ツールは、ファイル形式を識別するためのものです。その識別結果も高い信頼度スコアも、デコーダーがファイル全体を受け付ける証拠にはなりません。Magika の既知の制限事項にあるとおり、ポリグロットファイルも確実には検出できません。ファイルは複数の形式として解釈できる場合があります。
ブラウザーアプリに Magika を組み込む
Linux 環境で、venv と pip を備えた Python 3.12、および現行のブラウザーを使用します。この例では Magika 0.6.1 と Flask 3.1.0 にバージョンを固定しています。インストールにはインターネット接続が必要です。インストール後は、Magika が同梱のモデルをローカルで読み込むため、分類にクラウドサービスは不要です。以下のコマンドでは Bash を使います。
1. Magika のインストール
新しい magika-upload プロジェクトを作成するディレクトリで、ターミナルに次のコマンドを貼り付けてください。このコマンドは既存のディレクトリを再利用せず、セットアップのいずれかの手順が失敗すると停止します。丸括弧で囲んでいるため、シェルの作業ディレクトリは元の場所のままです。
(
mkdir magika-upload &&
cd magika-upload &&
mkdir static &&
python3.12 -m venv .venv &&
.venv/bin/python -m pip install magika==0.6.1 flask==3.1.0
)
インストールが成功した場合にのみ先へ進んでください。失敗した場合はエラーを確認し、新しいディレクトリで再試行するか、不完全な環境を修復してから先へ進んでください。セットアップを再実行するために既存のプロジェクトを削除しないでください。
2. 最小限の検証 API の作成(Flask)
次のコードを magika-upload/app.py として保存してください。モデルはアプリの起動時に一度だけ読み込まれます。/ ルートは、次に作成するページを提供します。Flask は static ディレクトリも自動的に配信します。
from flask import Flask, jsonify, request, send_from_directory
from magika import Magika
from werkzeug.exceptions import RequestEntityTooLarge
app = Flask(__name__)
MAX_FILE_BYTES = 5 * 1024 * 1024
app.config['MAX_CONTENT_LENGTH'] = 6 * 1024 * 1024
ALLOWED_TYPES = {'pdf', 'jpeg', 'png'}
magika = Magika()
@app.get('/')
def index():
return send_from_directory(app.root_path, 'index.html')
@app.errorhandler(RequestEntityTooLarge)
def request_too_large(error):
return jsonify(error='Upload is too large'), 413
@app.post('/verify')
def verify_file():
if 'file' not in request.files:
return jsonify(error='No file provided'), 400
content = request.files['file'].read(MAX_FILE_BYTES + 1)
if not content:
return jsonify(error='File is empty'), 400
if len(content) > MAX_FILE_BYTES:
return jsonify(error='Upload is too large'), 413
result = magika.identify_bytes(content)
if not result.ok:
return jsonify(error='File analysis failed'), 500
if result.output.label not in ALLOWED_TYPES:
return jsonify(error='Only PDF, JPEG, and PNG files are allowed'), 415
return jsonify(
file_type=result.output.label,
mime_type=result.output.mime_type,
)
ファイルの上限は 5 MiB です。これとは別に設けた 6 MiB のリクエスト上限は、multipart ヘッダーの分を確保しつつ、リクエスト全体のサイズを制限します。Flask のアップロードガイドで説明されているように、アップロードの解析では一時的なディスクストレージが使われる場合があります。このアプリは許可されたファイルを永続的には保存しません。分類前に content へ読み込むデータ量は、最大で 5 MiB に一バイトを加えた分です。
3. フロントエンドとの接続
次のコードを magika-upload/index.html として保存してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Classify a file with Magika</title>
<script src="/static/verify.js" defer></script>
</head>
<body>
<h1>Classify a file with Magika</h1>
<p>PDF, JPEG, or PNG, up to 5 MiB. The file is sent to the local Python server.</p>
<form id="uploadForm" action="/verify" method="post" enctype="multipart/form-data">
<label for="fileInput">File to classify</label>
<input id="fileInput" name="file" type="file">
<button type="submit">Classify file</button>
</form>
<p id="result" role="status">Choose a file, then classify it.</p>
</body>
</html>
次のコードを magika-upload/static/verify.js として保存してください。選択を変更すると、前の結果はすぐにクリアされます。再送信すると前のリクエストが置き換えられるため、遅れて届いたレスポンスが新しい処理のフィードバックを上書きすることはありません。
const form = document.getElementById('uploadForm')
const input = document.getElementById('fileInput')
const result = document.getElementById('result')
const errors = {
400: 'Choose a non-empty file.',
413: 'File exceeds the upload limit.',
415: 'Only PDF, JPEG, and PNG files are allowed.',
}
let requestId = 0
let activeRequest
input.addEventListener('change', () => {
requestId += 1
activeRequest?.abort()
result.textContent = 'Selection changed. Click Classify file to check it.'
})
form.addEventListener('submit', async (event) => {
event.preventDefault()
const id = ++requestId
activeRequest?.abort()
const file = input.files[0]
if (!file) {
result.textContent = 'Choose a file, then classify it.'
return
}
const controller = new AbortController()
activeRequest = controller
const timeout = setTimeout(() => controller.abort(), 30_000)
const data = new FormData()
data.append('file', file)
result.textContent = `Classifying ${file.name}…`
try {
const response = await fetch('/verify', {
method: 'POST',
body: data,
signal: controller.signal,
})
if (id !== requestId) return
if (!response.ok) {
result.textContent = errors[response.status] ??
`Classification failed (HTTP ${response.status}).`
return
}
const analysis = await response.json()
if (id !== requestId) return
result.textContent = `${file.name}: ${analysis.file_type} (${analysis.mime_type}). ` +
'Accepted by the type allowlist.'
} catch {
if (id !== requestId) return
result.textContent = controller.signal.aborted
? 'Request timed out. Click Classify file to retry.'
: 'Could not reach or read the server. Check the terminal, then retry.'
} finally {
clearTimeout(timeout)
}
})
リクエスト ID による制御は、レスポンスと非同期に読み取る JSON 本文の両方に適用されます。AbortController は、後続の送信で置き換えられたリクエストの待機を中止し、30 秒のタイマーがブラウザーでの各試行の時間を制限します。ブラウザーのリクエストを中止しても、Python がすでに受信したバイト列の処理を停止するとは限りません。
セットアップ時と同じ親ディレクトリからアプリを起動してください。
(
cd magika-upload &&
.venv/bin/python -m flask --app app run --host 127.0.0.1 --port 5050
)
Flask の起動メッセージを待ってから、http://127.0.0.1:5050/ を開いてください。ディスク上の HTML ファイルではなく、この URL を開きます。ページ、スクリプト、/verify エンドポイントは同一オリジンである必要があります。File to classify でファイルを選択し、Classify file をクリックしてください。ボタンをもう一度クリックすると、同じファイルで再試行できます。終了したら Ctrl+C でサーバーを停止してください。
4. 結果と許可リストの照合
小さな正常な PNG ファイルの名前を photo.txt に変更して試してください。表示されるはずのメッセージは次のとおりです。photo.txt: png (image/png). Accepted by the type allowlist.
ファイル名によってアップロードが許可されるわけではありません。許可の判断に使うのは、サーバーの pdf、jpeg、png というラベルだけです。JPEG ファイルのラベルは、ファイル名が .jpg で終わる場合でも、jpeg です。
次に、空でないテキストファイルの名前を photo.png に変更して試してください。表示されるはずのメッセージは次のとおりです。Only PDF, JPEG, and PNG files are allowed.
空のファイルと、5 MiB を少し超えるファイルも試してください。これらは Magika の実行前に拒否されます。リクエストの処理中に別のファイルを選択してください。ページ上の処理待ちの結果表示がクリアされ、新たに選択したファイルの分類を実行するまで待機するはずです。
リクエスト失敗時の対処
- インストールまたはモデルの読み込みの失敗: まずターミナルのエラーを確認してください。
.venv内でインストールが完了し、その環境の Python 実行ファイルを起動していることを確認してください。アプリの起動が成功するまで、ページは読み込めません。 - ポートが使用中: Flask はアドレスが使用中であることを示すエラーで終了します。起動コマンドで別のポートを指定し、そのポートの URL を開いてください。これはローカル開発サーバーであり、デプロイ用の構成ではありません。
- サーバーによるリクエストの拒否: HTTP 400 はファイルがないか空であること、413 はサイズ制限、415 は許可リストにないラベルを示します。大きなリクエストでは、開発サーバーが読み取り可能な 413 レスポンスを返す代わりに、接続がリセットされる場合があります。
- ブラウザーがレスポンスを読み取れない: サーバーのターミナルと URL を確認してから再試行してください。HTTP エラー、サーバーの停止、タイムアウトは、許可されたことを意味しません。ページはサーバーのエラーページやスタックトレースではなく、固定のエラーメッセージを表示します。
アップロードワークフローでの結果の利用
このアプリを拡張してファイルを保存する場合は、受信した同じバイト列に対して、許可リストとの照合と保存を行ってください。分類に成功したレスポンスを根拠に、後から検査せずに行うアップロードを許可してはいけません。この例が返すのは分類結果だけであり、アップロードしたファイルの保存も、再利用できる承認の作成も行いません。
許可されたラベルは、後続の画像デコーダー、ドキュメントパーサー、モデレーションサービスの選択に役立ちます。ただし、それぞれの処理には独自の検証とリソース制限が必要です。マルウェアスキャンは別の処理であり、形式の予測を安全性の判定結果として表示してはいけません。
マネージド型のアップロードワークフローについては、ファイル検証リファレンスを参照してください。どちらの設計でも、この区別は変わりません。形式の識別はアップロードを扱う際の判断の一つであり、内容が安全であることの証明ではありません。
