Ein stabiler Remote-Snapshot ergänzt den gemeinsamen Prüfvertrag
SFTP-Schnittstellen automatisch testen: Dateien sicher validieren
Eine Datei auf einem SFTP-Server ist nicht automatisch ein fertiger Datensatz. Während des Uploads kann sie noch wachsen, der Host kann unerwartet sein und ein formal erreichbarer Transport sagt nichts über den Inhalt aus. Iteration 4 von ZEUS Interface Quality macht aus genau diesem Ablauf einen reproduzierbaren Prüfbaustein.
Der neue Adapter prüft Host-Key und Schlüsselzugang, wartet auf einen stabilen Remote-Snapshot, lädt genau eine Datei temporär herunter, vergleicht bei Bedarf ihren SHA-256-Hash und delegiert die Inhaltsprüfung an die bereits vorhandenen JSON-, CSV- oder Fixed-Width-Adapter. Erst danach entscheidet der gemeinsame Vertrag zwischen VALID, INVALID und einem technischen Fehler.
Die übergeordnete Idee steht im Hauptartikel zur automatischen Schnittstellenqualität. Iteration 1 beschreibt JSON Schema als lokalen Prüfvertrag; Iteration 2 ergänzt CSV und Fixed-Width; Iteration 3 führt HTTP-Status, Header und JSON-Response zusammen. Nun kommt der geschützte Datei-Transport hinzu.
KI-generierte Illustration für tiny-tool.de: Eine zentrale Validierungsstation prüft eine geschützte SFTP-Datei auf stabilen Snapshot, Integrität und Inhaltsvertrag.
Was Iteration 4 liefert
Die Ausbaustufe ist ein vertikaler Durchstich für genau eine erwartete SFTP-Datei. Sie ist kein Directory-Watcher und kein vollständiges Datei-Transfer-Management.
- Vertrauen: ein explizites
known_hostsund ein lokaler privater Schlüssel sind Pflicht. - Stabilität: Typ, Größe und Änderungszeit des Remote-Objekts werden mehrfach beobachtet.
- Integrität: ein optionaler SHA-256-Hash wird gegen die tatsächlich geladenen Bytes geprüft.
- Inhalt: JSON, CSV und Fixed-Width nutzen ihre vorhandenen, bereits getesteten Validatoren.
- Fehlerbehandlung: ungültige Lieferungen können opt-in in ein Remote-Quarantäneverzeichnis verschoben werden.
- Automation: Exit 0 bedeutet gültig, Exit 1 Vertragsverletzung, Exit 2 nicht zuverlässig durchführbar.
Das SFTP-Profil als lokaler Vertrag
Das Profil beschreibt die Gegenstelle und die Prüfregeln, die für diesen Lauf gelten. Es liegt lokal und wird wie die bisherigen Adapter mit --schema beziehungsweise --profile ausgewählt. Die lokalen Dateien für Host-Key, privaten Schlüssel und Inhaltsprofil müssen innerhalb des Profilverzeichnisses liegen.
{
"format": "sftp",
"version": 1,
"host": "sftp.example.org",
"port": 22,
"username": "quality-check",
"remotePath": "/inbox/delivery.json",
"knownHosts": "known_hosts",
"privateKey": "id_ed25519",
"privateKeyPassphraseEnv": "SFTP_KEY_PASSPHRASE",
"contentFormat": "json",
"contentProfile": "delivery.schema.json",
"quarantineRemoteDirectory": "/quarantine",
"stabilityChecks": 2,
"stabilityDelaySeconds": 1,
"maxAttempts": 2,
"retryDelaySeconds": 1,
"connectTimeoutSeconds": 10
}remotePath ist ein absoluter POSIX-Pfad auf genau eine Datei. Punkte, Traversal-Segmente, Backslashes und abschließende Schrägstriche werden abgewiesen. Das verhindert keine fachlich falsche Datei, aber es verhindert, dass der Adapter aus einem kleinen Profil unbemerkt einen anderen Pfad interpretiert.
Host-Key und Schlüssel statt stiller Ausnahmen
Der Transport verwendet JSch mit strikt aktiviertem known_hosts-Abgleich. Der Server wird nicht über eine beliebige neue Host-Key-Antwort akzeptiert. Die Authentifizierung ist in dieser ersten SFTP-Version bewusst auf einen privaten Schlüssel begrenzt. Eine Passphrase darf aus einer Umgebungsvariable kommen; sie landet weder im Profil-Report noch in den Findings.
🔐 Vertrauensgrenze
Ein SFTP-Login ist noch kein Qualitätsnachweis. Der Prüfjob sollte den Host-Key und den privaten Schlüssel über die CI-Umgebung bereitstellen, das Profil aber als versionierbare, geheime-freie Regel behandeln. Die Implementierung unterstützt deshalb weder Klartextpasswörter noch beliebige Pfade außerhalb des Profilverzeichnisses.
Warum Größe und Änderungszeit nicht nebensächlich sind
Viele Dateiübergaben schreiben direkt in den später erwarteten Namen. Ein schneller Download kann dann eine formal gültige, aber unvollständige Momentaufnahme erwischen. ZEUS fragt deshalb vor dem Download nach dem Remote-Objekt und vergleicht Typ, Byte-Größe und Änderungszeit über mehrere Beobachtungen.
Bleibt die Datei nicht stabil, wartet der Adapter nur so lange, wie es das Profil erlaubt. Danach ist die Prüfung kein fachliches INVALID, sondern ein technischer Fehler mit Exit-Code 2: Der Prüfjob konnte keinen verlässlichen Snapshot herstellen.
"stabilityChecks": 2,
"stabilityDelaySeconds": 1,
"maxAttempts": 2,
"retryDelaySeconds": 1Die Grenzen sind Absicht: Ein Testlauf soll nicht unendlich auf eine Lieferung warten und auch keinen stillen Polling-Dienst simulieren. Für komplexere Anlieferungsprozesse wäre ein eigener Orchestrator mit einer eigenen Zustands- und Auswahlregel sinnvoller.
SHA-256 und Quarantäne
Nach dem stabilen Snapshot schreibt der Adapter die Bytes in ein temporäres lokales Verzeichnis. Wenn das Profil sha256 enthält, wird der Hash genau über diese heruntergeladene Datei gebildet. Ein abweichender Hash wird an /remote/hash gemeldet; die Inhaltsprüfung wird in diesem Fall nicht als scheinbar aussagekräftiger Ersatz fortgesetzt.
{
"status" : "INVALID",
"valid" : false,
"findings" : [ {
"instancePath" : "/remote/hash",
"schemaPath" : "/sha256",
"keyword" : "sha256",
"message" : "Downloaded SFTP file does not match the expected SHA-256 hash"
} ]
}Optional kann ein ungültiger Inhalt oder Hash in ein Remote-Verzeichnis verschoben werden. Die Zieldatei erhält einen UTC-Zeitstempel und das Suffix .invalid. Gültige Dateien werden nicht bewegt; bei einem Verbindungs- oder Stabilitätsfehler findet ebenfalls keine Quarantäne statt.
JSON, CSV und Fixed-Width wiederverwenden
Der SFTP-Adapter erfindet keine zweite Inhaltslogik. contentFormat wählt den bereits vorhandenen Validator, contentProfile verweist auf dessen lokales Profil. So bleibt klar, welcher Teil des Laufs den Transport und welcher Teil den eigentlichen Datenvertrag verantwortet.
| Format | Lokaler Vertrag | Pfad im Report |
|---|---|---|
json |
JSON Schema Draft 2020-12 | /content/... |
csv |
CSV-Profil mit Header- und Spaltenregeln | /content/... |
fixed-width |
Positions- und Längenprofil | /content/... |
Ein fehlerhaftes Pflichtfeld aus dem JSON-Beispiel erscheint daher beispielsweise als /content/quantity. Damit bleibt der Befund maschinenlesbar von einem Hash- oder Transportproblem getrennt.
Der CI-Lauf ohne lokale Eingabedatei
Bei lokalen Datei- und HTTP-Prüfungen war --input je nach Adapter ein wichtiger Teil des Aufrufs. SFTP ist anders: Die Datei wird durch das Profil eindeutig bestimmt. Deshalb darf der SFTP-Lauf keine zusätzliche lokale Eingabedatei vortäuschen.
🟢 Der erste garantierte Erfolg
Wer dem Artikel ohne SFTP-Konto folgen möchte, startet mit dem isolierten Adaptertest. Er benötigt nur JDK 21 und den Maven Wrapper aus dem Repository:
mvnw.cmd -B -Dtest=SftpValidatorTest testDieser Lauf kontaktiert keinen SFTP-Server und endet mit sechs erfolgreichen SFTP-Tests. Der produktive Lauf gegen eine reale Gegenstelle bleibt weiter unten als umgebungsspezifischer Aufruf gekennzeichnet.
mvnw.cmd -B -Dtest=SftpValidatorIntegrationTest testDieser zweite Lauf startet einen eingebetteten Testserver und prüft den produktiven JSch-Transport mit Host-Key und Private Key. Auch dafür werden weder Docker noch ein externer SFTP-Account benötigt.
$jar = "target/zeus-interface-quality-0.1.0-SNAPSHOT.jar"
$profile = "docs/examples/sftp-profile.json"
java -jar $jar validate --input-format sftp --schema $profile --report json
$LASTEXITCODEWichtig: docs/examples/sftp-profile.json ist eine Konfigurationsvorlage. Für einen echten Lauf müssen Host, Benutzername, Remote-Pfad, known_hosts, privater Schlüssel und Inhaltsprofil zur eigenen Umgebung passen. sftp.example.org ist bewusst nur ein Platzhalter. Die automatisierten Tests greifen nicht auf dieses Beispielsystem zu; sie ersetzen den Transport kontrolliert durch einen Test-Port.
Ergebnisse und Exit-Codes
| Fall | Beispiel | Ergebnis |
|---|---|---|
| VALID | stabile Datei, Hash und Inhaltsvertrag passen | Report, Exit 0 |
| INVALID | Hash oder JSON-, CSV- beziehungsweise Fixed-Width-Vertrag bricht | Report, Exit 1 |
| nicht durchführbar | Profil-, Key-, Verbindungs-, Download- oder Stabilitätsfehler | kein fachlicher Report, Exit 2 |
Diese Trennung ist für CI wertvoll. Ein fehlerhafter Datensatz kann den Lieferprozess kontrolliert stoppen und in Quarantäne gehen. Ein nicht erreichbarer Server bleibt dagegen ein Betriebsproblem, das nicht mit einem fachlichen Datenbefund verwechselt werden darf.
Der automatisierte Nachweis
Die Unit-Tests verwenden einen kleinen Transport-Port und einen deterministischen Fake. Zusätzlich startet der Integrationstest einen eingebetteten Apache-MINA-SSHD-SFTP-Server und lässt den produktiven JSch-Transport dagegen laufen. Dadurch werden Host-Key-Prüfung, Private-Key-Login, Download und Quarantäne realistisch geprüft, ohne einen öffentlichen SFTP-Server oder externe Zugangsdaten anzusprechen.
🟢 Reproduzierbarer Ablauf
Im Repository lässt sich der neue Strang mit mvnw.cmd -B -Dtest=SftpValidatorTest test isoliert prüfen. Der vollständige Testlauf umfasst nach Iteration 4 insgesamt 76 Tests; zwei bestehende Windows-Fälle für symbolische Links bleiben übersprungen, wenn die lokale Berechtigung fehlt. mvnw.cmd -B package erzeugt anschließend das ausführbare JAR.
Das ist ein belastbarer Nachweis für die Profil- und Adapterlogik, aber kein Verfügbarkeitsversprechen für eine produktive Gegenstelle. Ein Live-Server-Test gehört in eine geschützte, umgebungsspezifische Pipeline mit verwalteten Zugangsdaten und Host-Keys.
Was bewusst noch nicht enthalten ist
- keine Passwort-Authentifizierung, kein OpenSSH-Agent und keine automatische OpenSSH-Konfiguration;
- kein Directory-Polling, kein Glob und keine Auswahl aus mehreren gleichzeitig eintreffenden Dateien;
- kein automatisches Archivieren gültiger Lieferungen und keine Mehrdatei-Korrelation;
- keine fachlichen Regeln über mehrere Dateien oder mehrere Transportläufe;
- kein Live-SFTP-Server in den Standardtests und keine Aussage über produktive Verfügbarkeit.
Diese Grenzen machen die Iteration handhabbar. Der Adapter beweist zuerst einen klaren, sicheren Ein-Datei-Ablauf. Directory-Watcher, Lieferfenster, Mehrdatei-Korrelation und Betriebsorchestrierung können später als eigene Verträge ergänzt werden.
Fazit: Transport wird zum prüfbaren Teil des Vertrags
Iteration 4 verbindet SFTP nicht einfach mit einem Download-Befehl. Sie beschreibt, welchem Host vertraut wird, wann eine Datei als stabil gilt, wie ihre Integrität geprüft wird und welcher Inhaltsvalidator anschließend zuständig ist.
Der Nachweis bleibt reproduzierbar: Ein lokales Profil, ein begrenzter Retry-Ablauf und ein gemeinsamer Report machen aus einer oft impliziten Übergabe einen klaren CI-Baustein. Ungültige Lieferungen können quarantänisiert werden, technische Ausfälle bleiben technische Ausfälle.
Die nächsten Entscheidungen sind damit vorbereitet: Verzeichnis-Polling, Mehrdatei-Korrelation, weitere Authentifizierungsmodelle oder ein vollständiger Betriebsworkflow sind eigene Iterationen. Der Hauptartikel hält den Gesamtstand fest.
Code und Quellen
Technischer und redaktioneller Stand: 25. September 2026. Die Beispiele beziehen sich auf den lokalen Stand von Iteration 4 im Repository.
tiny-tool.de
tiny-tool.de