NetScaler_forensik/README.md

NetScaler Triage

Offline-Analyse von Citrix-NetScaler-Logs und Dateisystem-Sicherungen. Das Werkzeug sucht nach Angriffsversuchen, bekannten IOCs, Webshell-Mustern und Persistenzhinweisen. Es verknüpft Logereignisse und speichert Fundstellen mit Originalkontext.

Originaldaten bleiben unverändert. Verdächtige Inhalte werden niemals ausgeführt oder heruntergeladen. Ein Treffer ist ein Prüfhinweis, kein automatischer Beweis einer Kompromittierung. Auch ein Scan ohne Treffer beweist kein sauberes System.

1. Installieren

Voraussetzung: Python 3.14 oder neuer. Das Repository herunterladen und ein Terminal in dessen Hauptordner öffnen. Alle folgenden lokalen Befehle werden dort ausgeführt. Installation kann Internetzugriff benötigen; die Analyse läuft offline.

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
netscaler-triage --help

Windows PowerShell:

py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install .
netscaler-triage --help

Die folgenden Eingabenamen sind Beispiele und müssen durch die eigenen Dateien ersetzt werden. Ausgabeordner müssen neu sein und außerhalb der untersuchten Verzeichnisse liegen. Originale und Ergebnisse vertraulich aufbewahren.

2. Logs prüfen

Einen Logordner oder ein Logarchiv untersuchen:

netscaler-triage ./logs --output ./log-ergebnis
netscaler-triage ./logs.7z --output ./archiv-ergebnis

Mehrere Exporte gemeinsam analysieren:

netscaler-triage ./appliance-a ./appliance-b export.zip --output ./gemeinsames-ergebnis

Unterstützt werden ZIP einschließlich ZipCrypto/AES, TAR, TAR.GZ/TGZ, GZIP und 7z; verschachtelte Archive innerhalb der Verarbeitungsgrenzen. Bei verschlüsselten Archiven fragt --password das Passwort verdeckt ab:

netscaler-triage ./logs.7z --password --output ./verschluesselt-ergebnis

Die Zuordnung zu Appliances wird aus der Ordnerstruktur abgeleitet. Bei ungewöhnlich aufgebauten Exporten das Vorbereitungsmanifest kontrollieren.

Ergebnisse der Loganalyse lesen

Zuerst SUMMARY.txt öffnen: Abdeckung, Trefferzahlen und Untersuchungslücken. Danach FINDINGS.csv: Treffer mit Erklärung und Verweis auf die Originalquelle. IOCS.csv enthält Suchkandidaten für weitere Prüfungen, keine automatische Sperrliste.

Unter details/ liegen vollständige Ereignisse, Dekodierungen, Korrelationen, Prüfsummen und der SQLite-Index. details/findings.jsonl enthält auch Kontext und Verarbeitungsfehler; zum Durchsehen der Treffer zunächst FINDINGS.csv verwenden. Hash-Treffer stehen in details/file_hash_hits.json. Vorbereitete Eingabekopien liegen gegebenenfalls unter inputs/.

CSV-Zellen werden gegen Tabellenformeln abgesichert; exakte Originalwerte bleiben in JSON erhalten. Eigene Tests und Referenzindikatoren bleiben gekennzeichnet. Bei abgebrochenen Läufen kann nur summary.json im Ausgabeordner vorliegen.

3. Dateisystem-Sicherung prüfen

Die Erweiterung filesystem liest eine TAR.GZ-Sicherung direkt, ohne sie vollständig zu entpacken. Das spart zusätzlichen Speicherplatz:

netscaler-triage filesystem ./snapshot.tar.gz --output ./dateisystem-ergebnis

Bereits entpackte Dateien sind ebenfalls möglich. Als Eingabe den Wurzelordner mit etc/, var/ und netscaler/ angeben, nicht den übergeordneten Sammelordner:

netscaler-triage filesystem ./export-root --output ./ordner-ergebnis

Der Scanner prüft reguläre Dateien einschließlich versteckter Dateien auf:

• Bekannte Pfade, Dateinamen und SHA-256-Werte aus den IOC-Listen.
• Webshell-Inhalte, PHP in ungewöhnlichen Dateitypen und Ausführungsfunktionen.
• Verdächtige HTTP-Zuordnungen, Cron-/Startkonfigurationen und Reverse-Shell-Muster.
• Payloads, Hinweise auf Konfigurationsbereitstellung sowie bekannte IPs, Domains und URLs.
• Dateirechte, Besitzer, Zeitstempel und Linkziele; Symlinks werden nicht verfolgt.

Dateiinhalte und gzip-Inhalte werden nach Mustern durchsucht, auch enthaltene Logs. Für zusätzliche strukturierte Auswertung und Korrelation ausgewählter System-, Authentifizierungs-, HTTP- und Call-Home-Logs --analyze-logs ergänzen:

netscaler-triage filesystem ./snapshot.tar.gz --output ./dateisystem-mit-logs --analyze-logs --timezone Europe/Berlin

Die Zeitzone muss zum Gerät passen. Ergebnisse der zusätzlichen Loganalyse stehen unter loganalyse/. Dafür werden höchstens 16 MiB temporäre Original-Logkopien angelegt und anschließend entfernt. Fehlende Jahresangaben werden nicht geraten. Diese Logauswertung kann unvollständig sein, obwohl der Dateisystemscan fertig ist.

Eigene IOCs und früheren Stand ergänzen

Zusätzliche IOCs als CSV laden; Format siehe Abschnitt 5:

netscaler-triage filesystem ./snapshot.tar.gz --output ./ioc-ergebnis --ioc-file ./private/IOC.csv

Mit einem früheren Dateiverzeichnis vergleichen:

netscaler-triage filesystem ./snapshot.tar.gz --output ./vergleich-ergebnis --baseline ./previous-files

Ein früherer Stand ist keine unabhängig bestätigte, saubere Herstellerreferenz.

Mehrere Sicherungen parallel prüfen

Im Repository-Hauptordner mit aktivierter Python-Umgebung ausführen. Dieses Beispiel verwendet zwei Prozesse und funktioniert auch ohne Shell-Platzhalter:

python scripts/analyze_filesystem_exports.py ./export-a.tar.gz ./export-b.tar.gz --output ./batch-ergebnis --workers 2

Es sind ein bis vier Prozesse möglich. Optional --ioc-file ./private/IOC.csv ergänzen. Ergebnisse liegen pro Archiv in einem Unterordner; batch_summary.json fasst die Exitcodes zusammen. Die Batch-Prüfung sucht auch in Log-Inhalten, startet aber keine zusätzliche strukturierte Logkorrelation über --analyze-logs.

Ergebnisse der Dateisystemprüfung lesen

Zuerst summary.json prüfen: Vollständigkeit, Fehler, Grenzen und Integritätsprüfung. Dann die folgenden Dateien auswerten:

• artifact_checks.json: bekannte Pfade und Dateinamen, vorhanden oder nicht gefunden.
• findings.jsonl: Inhalts- und IOC-Treffer mit Kontext, Position und gegebenenfalls Hash.
• inventory.jsonl: Dateiinventar mit SHA-256 und Metadaten.
• selected_content.jsonl: begrenzte Textauszüge ausgewählter kritischer Dateien.
• baseline_changes.jsonl: Änderungen gegenüber einer übergebenen Vergleichsbasis.

Ein IOC in einem Log oder Installationspaket beweist kein aktives Implantat. PHP-Bibliotheken und reguläre Herstellerdateien können ebenfalls Treffer erzeugen. Fundstellen vor einer Bewertung im Zusammenhang prüfen.

4. Dateisystem auf dem NetScaler sichern

Nur diesen Exportbefehl auf der Appliance ausführen, in der BSD-Shell als root. Er erzeugt ein neues Archiv unter /var/tmp. Genügend freien Speicher vorsehen. Quelldateien werden nicht gelöscht; ein bereits vorhandener Zielname wird abgelehnt.

sh -c 'f="/var/tmp/netscaler-filesystem-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"; test ! -e "$f" || exit 1; umask 077; tar -czf "$f" --exclude=./dev --exclude=./proc --exclude=./kern --exclude=".$f" --exclude="./var/tmp/netscaler-filesystem*.tar.gz" -C / . && sha256 "$f"'

Das Archiv anschließend über den vorhandenen sicheren Übertragungsweg auf den Analyse-Rechner kopieren und dort wie in Abschnitt 3 prüfen. Fehlerausgabe und Exitstatus des Exports aufbewahren. Eine fehlgeschlagene Sicherung ist nicht vollständig.

Das Archiv enthält möglicherweise Zugangsdaten und private Schlüssel. Die Sicherung eines laufenden Systems ist kein konsistentes Datenträgerabbild. Der Exportbefehl wurde im dokumentierten Testumfang nicht auf einer echten Appliance ausgeführt.

5. Regeln und IOCs ergänzen

Vertrauliche Regelpakete unter private/ speichern; dieser Ordner ist von Git und Release-Archiven ausgeschlossen. Keine Kundendaten oder Analyseergebnisse ins öffentliche Repository übernehmen. Die Beispiele hier sind synthetisch.

CSV-Beispiel für zusätzliche IOCs:

type,value,status,source,description
ipv4,192.0.2.42,reference_only,local-review,Matching events require review
path,/example/suspicious-file,reference_only,local-review,Check file context

Originalwerte verwenden, keine entschärften Schreibweisen wie [.]. Die Dateisystemprüfung lädt eine zusätzliche CSV über --ioc-file. Die Loganalyse unterstützt darüber hinaus Sigma YAML, JSON, CSV und TXT über --config, auch rekursiv aus Verzeichnissen:

netscaler-triage rules --config ./private/my-rules
netscaler-triage ./logs --config ./private/my-rules --output ./eigene-regeln-ergebnis

--config kann wiederholt werden. TXT erlaubt einen Indikator pro Zeile. Die unterstützte Sigma-Teilmenge steht in RULES.txt; nicht unterstützte Funktionen werden gemeldet. Regelpakete werden nicht als Programmcode ausgeführt.

Quellen und Stand der öffentlichen IOC-Sammlung: THREAT_INTELLIGENCE.txt und config/threat_intel.json. Konkrete Dateisystemregeln und Abdeckung: FILESYSTEM_COVERAGE.txt.

Grenzen und Exitcodes

Exitcode 0 bedeutet erfolgreiche Verarbeitung innerhalb der dokumentierten Grenzen, nicht „nicht kompromittiert“. Bei jedem unvollständigen Lauf die Fehler prüfen:

• Loganalyse: Exitcode 2 bei Fehlern oder unvollständiger Verarbeitung.
• Dateisystemprüfung: Exitcode 1 bei gemeldeten Scanproblemen; Exitcode 2 bei allgemeinen CLI-Fehlern.
• Batch-Helfer: Exitcode 1, sobald mindestens ein Einzelscan einen Fehlerstatus liefert.

Die Loganalyse hat standardmäßig 2 GiB Vorbereitungsbudget, 100.000 Archiveinträge, Verschachtelungstiefe 3, 1 MiB je Zeile und 512 MiB entpackte Daten je Logdatei. Binäre Appliance-Logs benötigen gegebenenfalls einen externen Decoder.

Der Dateisystemscanner begrenzt rohe Dateidaten und entpackte gzip-Daten auf jeweils 128 GiB, die Ausgabe auf 128 MiB und Archive auf eine Million Einträge. Pro Regel, Ansicht und Datei speichert er höchstens 24 Fundauszüge; weitere Treffer werden gezählt. Ausgewählte Textkopien sind auf jeweils 256 KiB begrenzt. Der Batch-Helfer setzt das Ausgabelimit pro Archiv auf 256 MiB. Optionen: filesystem --help-all.

Eingebettete TAR-/ZIP-/7z-/Paketdateien werden nicht vollständig rekursiv inventarisiert. Gzip-Daten werden durchsucht, ohne daraus auf eine aktiv installierte Datei zu schließen. Archivfehler und erreichte Byte-/Ausgabegrenzen werden als Untersuchungslücken gemeldet.

Bei TAR.GZ wird das Originalarchiv während der Verarbeitung und nochmals danach gehasht; außerdem werden Größe, Änderungszeit und Inode verglichen. Bei einem Verzeichnis gibt es keinen Archivhash oder atomaren Schnappschuss. Entpacken kann Metadaten verändern. Originalarchive deshalb erhalten.

Live-Sicherungen enthalten weder den vollständigen RAM noch gelöschte Dateien. Keine IOC-Liste deckt unbekannte Angriffe vollständig ab. Es gibt keine automatische Wiederaufnahme unterbrochener Scans und kein hartes Gesamtlimit für RAM oder CPU.

Zeitangaben in Logs

Jahr und Zeitzone nur mit belegten Geräteeinstellungen ergänzen:

netscaler-triage scan --input ADC-A=./logs --year 2026 --timezone ADC-A=UTC

Name, Jahr und Zeitzone sind Beispiele. Explizite Zeitstempel bleiben erhalten; mehrdeutige Sommerzeitangaben werden nicht stillschweigend aufgelöst. Für mehrere Geräte oder dateispezifische Jahre siehe examples/time.json und --time-config. Annahmen stehen in details/configuration.json.

Aktualisieren, Hilfe und Entwicklung

Bei einem Git-Checkout die virtuelle Umgebung aktivieren und im Repository ausführen:

git pull
python -m pip install --upgrade .
netscaler-triage rules

Bei uv-Verwaltung stattdessen nach git pull mit uv sync --locked aktualisieren. Bei älteren Installationen mit invalid perl operator: (?= oder SigmaRegularExpressionError neu installieren und betroffene Scans wiederholen. Die kompatible pySigma-Version wird durch die Paketabhängigkeiten festgelegt.

Weitere Hilfe:

netscaler-triage --help
netscaler-triage scan --help-all
netscaler-triage filesystem --help-all
python scripts/analyze_filesystem_exports.py --help

Entwicklungsprüfungen:

uv sync --locked
uv run python -W error -m unittest discover -s tests
uv run mypy
uv run ruff check src tests typing_stubs
uv run ruff format --check src tests typing_stubs
uv build

Tests wurden auf macOS/ARM64 ausgeführt. Windows und Linux wurden im dokumentierten Testumfang nicht validiert. Details stehen in VALIDATION.txt. Direkte Python-Aufrufe von engine.scan liefern flache technische Exporte statt der oben beschriebenen CLI-Berichtsstruktur.

Lizenz

Der Programmcode steht unter der MIT-Lizenz. Für Abhängigkeiten und zitierte Materialien gelten deren eigene Lizenzen. Quellenangaben bedeuten keine Zugehörigkeit zu Citrix oder den genannten Forschenden.

Ergänzende Prüfungen und ihre Grenzen

Die zusätzlichen Sigma-Regeln prüfen ungewöhnliche ACS-/WS-Federation-Felder, Core-Datei-Löschbefehle, PHP-Handler, kommentierte Schutzdirektiven und auffällige Webartefakt-Antworten. Sie gelten auch für sicher dekodierte Textansichten. Erfasste Prozess- und Open-File-Listen können nach Prozessen unter Webkonten und NSPPE-Dateireferenzen durchsucht werden. Das Werkzeug erhebt diese Listen nicht live: Ohne entsprechende Sicherung ist dieser Zustand nicht prüfbar.

Im Modus filesystem kommen Pfadprüfungen für PHP-/XHTML-Dateien in Webverzeichnissen, SIG-/DEB-Kandidaten, Startup-Python und BLX-Konfiguration hinzu. Die bestehenden Hash- und SUID/SGID-Prüfungen bleiben aktiv. Ursprüngliche Rechte und Eigentümer sind nur mit verlässlichen Archivmetadaten bewertbar; lokale Kopien können diese verändern. Logregeln werden im Dateisystemmodus auf passende Logpfade begrenzt, damit Zeichenketten in Herstellerpaketen nicht als Logereignisse erscheinen.

Alle ergänzenden Verhaltensprüfungen liefern Prüfkandidaten. Ein HTTP-404, ein PHP-Dateiname, eine auskommentierte Direktive oder nicht-ASCII-Text ist allein kein Angriffsnachweis. Mit einem vertrauenswürdigen Stand desselben Builds vergleichen. Fehlende Logs, Prozesslisten oder Dateien bedeuten fehlende Prüfbarkeit.

Zusätzliche private IOCs als CSV mit type,value,status,description laden:

netscaler-triage ./logs --ioc-file ./private/indicators.csv --output ./new-log-review
netscaler-triage filesystem ./export-root --ioc-file ./private/indicators.csv --output ./new-file-review

Nicht unabhängig bestätigte Indikatoren als reference_only kennzeichnen. Sie werden gesucht, aber nicht automatisch als bösartig bewertet oder als öffentliche Threat Intelligence weitergegeben.

Additional public search indicators

Version 1.0.3 adds seven IP addresses and nine SHA-256 hashes to the default indicator catalog and Sigma rules. No extra IOC file is needed. These additions have no published attribution in the inventory and remain low-confidence search candidates. Review surrounding evidence before classifying a hit as malicious. Existing source attribution is preserved for previously documented indicators.