Dateiinspektions-API: SHA-256, echtes MIME, Virussignal und Metadaten per REST

Dateiinspektions-API: SHA-256, echtes MIME, Virussignal und Metadaten per REST

Anwendungen, die Uploads annehmen, brauchen häufig einen technischen Kontrollpunkt, bevor sie eine Datei an einen Parser, einen Workflow oder eine Speicherpipeline übergeben. Eine Plattform kann Dokumente von Verkäufern erhalten, ein SaaS-Produkt Kundenanhänge akzeptieren oder ein Sharing-Dienst dokumentieren müssen, was in das System gelangt. Hashing, MIME-Erkennung, Metadatenextraktion und ein erstes Malware-Triage-Signal lassen sich jeweils selbst bauen, doch ein konsistenter Betrieb kostet Entwicklungszeit. FileInspection bündelt diese Schritte in einem asynchronen REST-Vertrag und liefert einen JSON-Bericht.

Die Multipart-Anfrage

Authentifizierte Clients senden eine Multipart-Anfrage an POST /api/files/start-process. Verwenden Sie actionName=FileInspection, übertragen Sie eine Datei im Feld file, setzen Sie parameters=[] und async=true. Pro Aufruf ist genau eine nicht leere Datei bis 50 MB erlaubt; eine Endungs-Allowlist gibt es nicht. Die Servervalidierung prüft Anfrage und Größe selbst. Ein HTML-Attribut, ein Dateiname oder der vom Browser behauptete MIME-Typ ist keine Sicherheitsgrenze.

Die erste Antwort bedeutet, dass eine Aktion eingereiht wurde, nicht dass der Bericht schon fertig ist. Speichern Sie die Prozess-ID und trackingUrl und fragen Sie /api/actions/get-action-infos/{id} im authentifizierten Kontext ab. Die Anfrage bleibt dadurch nicht offen, während MIME-Erkennung, Antivirus-Triage, Metadatenextraktion oder Medienanalyse läuft.

Inhalt des JSON-Berichts

Ein erfolgreicher FileInspection-Lauf erzeugt eine einzelne JSON-Datei. Sie enthält den ursprünglichen Dateinamen, die Größe, einen SHA-256-Hash und den tatsächlich erkannten MIME-Typ. Der MIME-Wert wird aus dem Inhalt abgeleitet und nicht als Beweis vom Browser übernommen. Damit kann eine Anwendung besser protokollieren, routen oder entscheiden, ob ein nachgelagerter Parser die Datei erhalten soll.

Wenn das Format es unterstützt, kann ExifTool gefilterte EXIF-Metadaten ergänzen. Für Audio und Video kann FFprobe Codec, Auflösung, Dauer und Bitrate liefern. Bilder und PDFs können eine auf 500 Zeichen begrenzte OCR-Vorschau erhalten. Felder sind formatabhängig und können fehlen oder leer sein; fehlende Daten dürfen nicht automatisch als fehlgeschlagener Upload gelten.

Triage-Signale und ihre Grenzen

Der Antivirus-Teil meldet für Antivirus-Engine clean, infected oder error. Das ist ein vorläufiges Triage-Signal, niemals eine Antivirus-Garantie. Insbesondere bedeutet clean nur, dass diese Inspektion keine Erkennung gemeldet hat. Eine Benutzeroberfläche oder automatische Regel darf daraus niemals „zertifiziert sicher“ machen. error muss von clean unterscheidbar bleiben, damit eine Anwendung vorsichtig reagieren kann.

Erkennungsregeln meldet clean, matched oder not_run. Das Regelset ist bewusst minimal und keine vollständige Erkennungsbasis. Ein Match kann eine zusätzliche Prüfung auslösen; clean oder not_run beweisen nicht die Abwesenheit einer Bedrohung. Diese Formulierung gehört in Dokumentation, Logs und Nutzerhinweise, damit aus einem technischen Signal kein Sicherheitsversprechen wird.

Eine robuste Integration entwerfen

Speichern Sie die Aktions-ID als dauerhafte Referenz des asynchronen Jobs. Unterscheiden Sie mindestens abgelehnte Validierung, laufende Verarbeitung, fehlgeschlagene Verarbeitung und abgeschlossenen Bericht. Läuft ein Polling-Aufruf ab, lesen Sie zuerst die vorhandene Aktion, bevor Sie eine zweite starten. Ein erneuter Upload nur wegen einer fehlenden Statusantwort kann doppelte Arbeit und unnötige Tokenkosten erzeugen.

Nach Erfolg laden Sie die JSON-Datei über den authentifizierten Ergebnisweg und die vom Server bereitgestellte Referenz herunter. Bauen Sie keine Ergebnis-URL allein aus einer Integer-ID und behandeln Sie eine vom Client gelieferte Aktions-ID niemals als Berechtigung. Auch die eigene Anwendung muss den Besitz prüfen, wenn sie den Bericht mit einem Upload-Datensatz verknüpft. Ein Hash erleichtert Nachverfolgung und Deduplizierung, gewährt aber keinen Zugriff auf die Datei.

Preis und Umfang

Eine erfolgreiche Inspektion kostet 12 Tokens. Validierungsfehler, darunter eine leere Datei oder mehr als 50 MB, werden nicht berechnet. Der Dienst ist damit ein begrenzter technischer Kontrollpunkt vor Parsing oder menschlicher Prüfung, kein Ersatz für eine vollständige Malware-Analyse oder eine eigene Inhaltsrichtlinie.

Mit einer asynchronen REST-Anfrage erhält die Integration SHA-256, echtes MIME, ein vorläufiges Antivirus-Signal, einen minimalen Erkennungsregeln-Status, gefilterte Metadaten und formatabhängige Medien- oder OCR-Details. Die klare Prozessreferenz lässt das aufrufende System seinen eigenen Workflow fortsetzen, ohne den Prüfvertrag zu verlieren.