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:

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

Windows PowerShell:

```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:

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

Mehrere Exporte gemeinsam analysieren:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

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

Mit einem früheren Dateiverzeichnis vergleichen:

```sh
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:

```sh
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
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:

```csv
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:

```sh
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](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](THREAT_INTELLIGENCE.txt) und
[config/threat_intel.json](config/threat_intel.json).
Konkrete Dateisystemregeln und Abdeckung:
[FILESYSTEM_COVERAGE.txt](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:

```sh
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](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:

```sh
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:

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

Entwicklungsprüfungen:

```sh
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](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](LICENSE.txt). 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:

```sh
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.