karl/NetScaler_forensik
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add streaming filesystem triage and German usage guide

Browse Source
This commit is contained in:
StasonJatham committed 2026-10-05 14:13:39 +02:00
1 parent ae5a1a1e54
commit 83f53adb29
10 files changed
+1622 -157
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+260 -156
View File
@@ -1,40 +1,265 @@
# NetScaler Triage
Offline forensic triage for Citrix NetScaler ADC and Gateway logs. Point it at a
folder or archive to find suspicious requests, public indicators, encoded
payloads, update records and related events across logs.
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.
Original inputs are not modified. Payloads are decoded as data, never executed
or downloaded. A finding is an investigation lead, **not proof of compromise**.
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.
## Quick start
## 1. Installieren
Requires **Python 3.14 or newer**.
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
git clone https://tea.karlcom.de/karl/NetScaler_forensik.git
cd NetScaler_forensik
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
netscaler-triage ./logs.7z
netscaler-triage --help
```
On Windows PowerShell, create and activate the environment with:
Windows PowerShell:
```powershell
py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install .
netscaler-triage .\logs.7z
netscaler-triage --help
```
Installation may require internet access. Analysis runs offline.
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.
### Update an existing installation
## 2. Logs prüfen
Activate the same virtual environment used to run the tool, then run from the
repository directory:
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
@@ -42,145 +267,23 @@ python -m pip install --upgrade .
netscaler-triage rules
```
For an environment managed by uv, use `uv sync --locked` after `git pull`.
Version 1.0.1 fixes installation failures reporting `invalid perl operator: (?=`
or `SigmaRegularExpressionError` when loading the bundled rules. pySigma 2 changed
its default validation engine to RE2, which rejects lookaheads. The package now
requires compatible pySigma 1.x; detection patterns and timed matching are
unchanged. Reinstalling with the command above also downgrades an incompatible
pySigma installation. Rerun any scan that stopped with this error.
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.
## Everyday use
```sh
# Unpacked logs, an archive, or multiple appliance exports
netscaler-triage ./logs
netscaler-triage export.tar.gz
netscaler-triage ./appliance-a ./appliance-b export.zip
# Discover inputs in the current directory
netscaler-triage
# Encrypted archive: prompt for a password without displaying it
netscaler-triage export.7z --password
```
ZIP (including ZipCrypto/AES), TAR, TAR.GZ/TGZ, GZIP and 7z inputs are supported,
including nested archives within preparation limits. Unsupported formats are
reported. `--password VALUE` is also supported, but can expose the password in
shell history or process listings. Passwords are not stored in results.
The tool prints the result directory. Use `--output PATH` to choose a new one;
existing results are not overwritten. Appliance grouping is inferred from
directories; review the preparation manifest for unusual export layouts.
## Read the results
Start with these three files:
```text
triage-results-.../
SUMMARY.txt Start here
FINDINGS.csv Review matched events
IOCS.csv Search candidates for your SIEM
details/ Full evidence and machine-readable exports
inputs/ Prepared input copies, when preparation was needed
```
| File | Purpose |
| --- | --- |
| `SUMMARY.txt` | Readable overview: coverage, counts, limitations and what to open next |
| `FINDINGS.csv` | Only rule/indicator matches, with explanations and original source references |
| `IOCS.csv` | SIEM search candidates; not an automatic blocklist |
All technical exports are under `details/`: full events in `findings.jsonl`,
URL/Base64 decoding, updates, correlations, checksums, coverage and the SQLite
index. Prepared input copies, if needed, remain in `inputs/`.
`details/findings.jsonl` includes context and processing errors as well as matches;
use `FINDINGS.csv` to browse matched events. A match is not proof of execution.
Original-file SHA-256 matches are counted separately in `SUMMARY.txt`; their
evidence is in `details/file_hash_hits.json`, even when no log event matches.
The CSV keeps authorized-test and reference statuses visible. Spreadsheet-sensitive
cells are prefixed with an apostrophe; exact original values remain in JSON.
This layout applies to CLI scans. Direct Python calls to `engine.scan` retain
flat machine-readable exports. Failed or interrupted scans can also retain the
flat layout; inspect their `summary.json` before using partial results.
## Add indicators and Sigma rules
Put your packs in a directory and validate them before scanning:
```sh
netscaler-triage rules --config ./my-rules
netscaler-triage ./logs --config ./my-rules
```
Directories load Sigma YAML, JSON, CSV and TXT recursively. Repeat `--config`
to combine packs. No Python changes are needed to add an IP, path or rule.
For example, an IOC CSV can contain:
```csv
type,value,status,source,description
ipv4,192.0.2.42,reference_only,local-review,Investigate matching events
path,/example/suspicious-file,reference_only,local-review,Check file context
```
These are synthetic examples. Use original, non-defanged values for matching.
TXT accepts one value per line; unambiguous IP addresses, SHA-256 hashes, URLs
and Unix paths are inferred. Other values remain literal strings.
Sigma is parsed with pySigma and evaluated locally using the subset documented
in [RULES.txt](RULES.txt). Unsupported features fail explicitly. Sigma metadata
does not bypass detection conditions. Rule packs are data, not executable plugins.
Defaults include 47 Sigma rules and 246 public reference indicators. Attribution
and limitations are recorded in [THREAT_INTELLIGENCE.txt](THREAT_INTELLIGENCE.txt)
and [config/threat_intel.json](config/threat_intel.json). This is a dated reference
collection, not a promise of exhaustive intelligence or zero false positives.
Keep confidential packs in `private/`, excluded from Git and release archives.
Load them explicitly. Never put customer logs or generated findings in a public
repository. Examples under [examples/](examples/) use synthetic data.
## Limits and interpretation
- Exit `0`: configured processing completed; **not** a clean-system verdict.
- Exit `2`: an error or incomplete processing; inspect `SUMMARY.txt` and
`details/summary.json`. If the scan failed before presentation, inspect
`summary.json` at the result root instead.
- Missing years/timezones are not guessed. See time configuration below.
- Binary appliance logs may need an external decoder. Decode failures can also come from ordinary text.
- Damaged inputs and regex timeouts are reported. Archive path traversal, unsafe links and exhausted quotas stop preparation.
- Processing uses one worker, incremental reads and disk-backed SQLite. There is no hard process-wide RAM/CPU quota or automatic resume.
- Default limits: 2 GiB preparation budget, 100,000 archive entries, depth 3, 1 MiB per line and 512 MiB expanded per log file. Advanced options can raise limits.
Tests were executed on macOS/ARM64. Windows and Linux instructions are provided,
but those platforms have not yet been validated in the recorded test environment.
## Time configuration
Use known device settings when logs omit their year or timezone:
```sh
netscaler-triage scan --input ADC-A=./logs --year 2026 --timezone ADC-A=UTC
```
The appliance name, year and timezone above are examples. Explicit timestamps
are retained; ambiguous daylight-saving times remain unresolved. Use
`--time-config` for per-device settings and per-file year overrides; see
[examples/time.json](examples/time.json). The effective assumptions are recorded
in `details/configuration.json`.
## Help and development
Weitere Hilfe:
```sh
netscaler-triage --help
netscaler-triage scan --help-all
netscaler-triage decode payload.txt
netscaler-triage inventory ./logs
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
@@ -189,12 +292,13 @@ uv run ruff format --check src tests typing_stubs
uv build
```
See [RULES.txt](RULES.txt) for rule-pack semantics and
[VALIDATION.txt](VALIDATION.txt) for test scope and known coverage limits.
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.
## License
## Lizenz
Project code is licensed under the [MIT License](LICENSE.txt).
Third-party dependencies and referenced external materials retain their own
licenses. Source attribution does not imply affiliation with Citrix or the
referenced researchers, and does not relicense their original publications.
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.