Zuletzt aktualisiert: 12. September

Web-Uploads mit Magika und einer Python-API verifizieren

Tim Koschützki

Mitgründer · Berlin, Deutschland ·

Dateiendungen und vom Client gelieferte MIME-Typen lassen sich fälschen. Das Open-Source-Tool Magika von Google klassifiziert Dateien anhand ihrer Bytes. In diesem Tutorial läuft Magika auf einem Python-Server: Der Browser lädt die vollständige Datei zu einem Flask-Endpunkt hoch und zeigt dessen Ergebnis an. Die Verarbeitung bleibt nicht auf dem Gerät der Nutzer, und die Identifizierung eines Formats beweist nicht, dass eine Datei harmlos ist.

Herausforderungen bei der herkömmlichen Dateityp-Verifizierung

Gängige Identifizierungsverfahren untersuchen Metadaten oder Dateisignaturen:

Dateiendungen lassen sich in Sekunden umbenennen.
MIME-Typen stammen vom Client und sind häufig falsch.
Magic Numbers funktionieren bei gängigen Formaten, kommen aber bei proprietären oder polyglotten Dateien an ihre Grenzen.

Diese Schwachstellen ermöglichen bösartige Uploads, etwa evil.exe getarnt als holiday.jpg, und schaffen eine echte Angriffsfläche für Web-Apps.

Magika vorgestellt: KI-gestützte Dateiidentifizierung

Magika nutzt ein Deep-Learning-Modell, um Binär- und Textformate zu identifizieren. Es gibt einen vorhergesagten Typ und einen Konfidenzwert zurück. Es validiert nicht jede Struktur innerhalb einer Datei, erkennt nicht jede polyglotte Datei und sucht nicht nach Schadsoftware. Dieses Beispiel verwendet die Python-API in magika==0.6.1, und zwar mit Python 3.9 oder neuer.

So funktioniert Magika

Extrahiert Merkmale aus ausgewählten Teilen der Datei. Die folgende API liest die hochgeladene Datei zunächst in den Arbeitsspeicher und erzwingt daher vor der Klassifizierung eine Größenbeschränkung.
Führt diese Daten einem leichtgewichtigen neuronalen Netz zu. Es bietet verschiedene Identifizierungsmodi, wobei HIGH_CONFIDENCE der Standard ist.
Gibt ein Label, einen MIME-Typ und einen Konfidenzwert zurück. Messen Sie die Latenz in Ihrem Deployment, einschließlich Modellstart und Upload-Zeit.

Magika in eine Browser-Anwendung integrieren

1. Magika installieren

python -m pip install magika==0.6.1 flask==3.1.0

2. Eine minimale Verifizierungs-API erstellen (Flask)

from flask import Flask, request, jsonify
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  # Includes multipart overhead
ALLOWED_TYPES = {'pdf', 'jpeg', 'png'}
magika = Magika()  # Load the model once at startup

@app.errorhandler(RequestEntityTooLarge)
def request_too_large(error):
    return jsonify({'error': 'Upload is too large'}), 413

@app.route('/verify', methods=['POST'])
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,
        'description': result.output.description,
        'score': result.score,
    })

if __name__ == '__main__':  # dev only—use Gunicorn in production
    app.run()

Speichern Sie das Beispiel als app.py und führen Sie für die lokale Entwicklung python app.py aus. Liefern Sie das Frontend über denselben Ursprung aus wie /verify (oder konfigurieren Sie einen Entwicklungs-Proxy). Setzen Sie im Produktivbetrieb einen WSGI-Server sowie Request-Timeouts, Authentifizierung und Ratenbegrenzungen ein. Dieser Endpunkt analysiert ausschließlich die übermittelten Bytes; ein separater Upload- oder Speicher-Endpunkt muss dieselben Prüfungen selbst durchsetzen.

3. Das Frontend anbinden

Fügen Sie ein Datei-Eingabefeld mit id="fileInput" und ein Ergebniselement mit id="result" hinzu und führen Sie diesen Code aus, sobald diese Elemente vorhanden sind:

async function verifyFile(file) {
  const formData = new FormData()
  formData.append('file', file)

  try {
    const response = await fetch('/verify', {
      method: 'POST',
      body: formData,
    })

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`)
    }

    const result = await response.json()
    return result
  } catch (error) {
    console.error('File verification request failed:', error)
    throw error
  }
}

document.getElementById('fileInput').addEventListener('change', async (event) => {
  const file = event.target.files[0]
  if (!file) {
    return // No file selected
  }

  try {
    const analysisResult = await verifyFile(file)
    document.getElementById('result').textContent =
      `Detected: ${analysisResult.file_type} (${(analysisResult.score * 100).toFixed(1)}% confidence)`
  } catch (error) {
    document.getElementById('result').textContent = 'Verification failed. See console for details.'
  }
})

4. Ergebnisse mit einer Allowlist abgleichen

Die API setzt ihre Allowlist bereits durch. Eine entsprechende clientseitige Prüfung kann das Feedback verbessern, darf einen späteren Upload aber niemals eigenständig autorisieren.

// Assuming 'analysisResult' is available from the previous step
const allowedFileTypes = ['pdf', 'jpeg', 'png'] // Using Magika's labels

if (!allowedFileTypes.includes(analysisResult.file_type)) {
  alert(
    `File type "${analysisResult.file_type}" is not allowed. Allowed types are: ${allowedFileTypes.join(', ')}.`,
  )
  // Or throw new Error(`File type ${analysisResult.file_type} is not permitted.`);
}

Magika im Vergleich zu herkömmlichen Methoden

Merkmal	Endung / MIME	Magic Numbers	Magika
Erkennt gefälschte Endungen	❌	✅/Teilweise	✅
Tempo (Millisekunden pro Datei)	✅	✅	✅
Open Source & gepflegt	k. A.	Manche	✅

Praktische Anwendungsfälle

Sichere Upload-Formulare

Validieren Sie Uploads, bevor Sie sie speichern oder an die weitere Verarbeitung übergeben. Diese Prüfung sollte in erster Linie auf Ihrem Server erfolgen, nachdem dieser die Datei und Magikas Analyse erhalten hat.

// Example client-side feedback based on server verification result
// const analysisResult = await verifyFile(file); // from server
if (!['jpeg', 'png', 'pdf'].includes(analysisResult.file_type)) {
  // Display error to user: Only images and PDFs allowed
  throw new Error('Only images and PDFs allowed')
}

Inhaltsmoderation

Leiten Sie Dateien anhand des Labels von Magika an spezialisierte Pipelines weiter: Bilder an einen KI-Moderationsdienst, Videos an FFmpeg, Dokumente an OCR und so weiter.

Vorabprüfung auf Schadsoftware

Anhand der Datei-Labels lassen sich ausführbare Dateien oder Skripte zur genaueren Prüfung weiterleiten. Eine Denylist allein reicht nicht aus: Auch ein erlaubtes Bild oder PDF kann einen Schadsoftware-Scan und eine Formatvalidierung erfordern.

# Within a server-side classification workflow, after checking result.ok:
risky_file_types = {'pebin', 'elf', 'macho', 'batch', 'shell'}
requires_additional_review = result.output.label in risky_file_types

Fehlerbehandlung & bewährte Verfahren

Prüfen Sie auf dem Server. Clientseitige Prüfungen sind eine Bequemlichkeit, keine robuste Verteidigung.
Setzen Sie Request-Timeouts. Auch bei großen Dateien oder Containern mit Kaltstart braucht Ihr API-Endpunkt Limits.
Protokollieren Sie Konfidenzwerte. Sie helfen bei der Nachverfolgung von Grenzfällen, in denen Magika unsicher ist, sowie bei Audits.
Aktualisieren Sie regelmäßig. Jedes Magika-Release ergänzt Formate und verbessert die Genauigkeit.
Staffeln Sie Ihre Schutzmaßnahmen. Kombinieren Sie Magika mit Antivirensoftware, Denylist-Logik auf Basis weiterer Kriterien und Ratenbegrenzung für Ihren Upload-Endpunkt.

Alternative von Transloadit

Lieber eine fertige SaaS-Lösung? Unser Robot 🤖 /file/verify führt ähnliche inhaltsbasierte Prüfungen in der Cloud durch. Ein minimaler Step sieht so aus:

{
  "robot": "/file/verify",
  "use": ":original",
  "verify_to_be": "pdf",
  "error_on_decline": true,
  "error_msg": "File type verification failed"
}

Kombinieren Sie ihn mit Uppy zu einer vollständigen Upload-Pipeline vom Frontend bis zum Backend.

Fazit

Magika verbessert die Dateityp-Verifizierung erheblich, indem es den Dateiinhalt untersucht, statt Metadaten zu vertrauen. Ob Sie Magika selbst hosten oder den Robot von Transloadit nutzen, inhaltsbasierte Prüfungen können unerwartete Formate abweisen. Kombinieren Sie sie mit Schadsoftware-Scans und einem sicheren Umgang mit akzeptierten Dateien; eine Klassifizierung allein ist kein Urteil über Schadsoftware.