binref/refineryHochoktanige Triage-Analyse
# Binary Refinery
[][docs]
[][tests]
[][codecov]
[][pypi]
```
__ __ High Octane Triage Analysis __
|| _||______ __ __________ _____ ||
|| \||___ \__| ____/ ______/___ / ____\ ||
==||=====|| | __/ |/ \ /==| / __ \ __\===]|
'======|| | \ | | \_ _| \ ___/| | ||
||____ /__|___|__/ / | \____]| | ||
=========''====\/=========/ /==|__|=====|__|======'
\ /
\/
```
Die Binary Refinery™ ist eine Sammlung von Python-Skripten, die Transformationen von Binärdaten wie Kompression und Verschlüsselung implementieren.
Wir werden sie oft einfach als _refinery_ bezeichnen, was auch der Name des entsprechenden Pakets ist.
Die Skripte sind darauf ausgelegt, Eingaben ausschließlich von stdin zu lesen und Ausgaben nach stdout zu schreiben.
Die Hauptphilosophie ist, dass jedes Skript eine Einheit sein sollte, in dem Sinne, dass es _eine_ Aufgabe erfüllt,
und einzelne Einheiten können mit dem Pipe-Operator `|` auf der Kommandozeile zu _Pipelines_ kombiniert werden, um komplexere Aufgaben zu erledigen.
Der Hauptfokus des Projekts liegt auf Malware-Triage
und ist der Versuch, so etwas wie [CyberChef](https://github.com/gchq/CyberChef) auf der Kommandozeile zu implementieren.
## Kurzfassung
Erstelle eine virtuelle Python-Umgebung. Du benötigst Python 3.11 oder neuer. Installiere refinery wie folgt:
```
python -m pip install -U pip
python -m pip install -U binary-refinery[extended]
```
Führe Units mit `-h` aus, um zu lernen, wie sie funktionieren, durchsuche die [Dokumentation][docs] oder verwende den Befehl `binref`, um sie zu finden.
Sieh dir [ein aktuelles Video][VOD3] an, wenn du es in Aktion sehen möchtest.
Aber lies auch den Rest dieser Readme.
## Release-Zeitplan
Es gibt keinen Release-Zeitplan, aber Releases erscheinen sehr häufig und es wird empfohlen, regelmäßig zu aktualisieren.
Bugfixes werden außerhalb von GIT nicht dokumentiert, aber alle anderen Änderungen (d. h. neue Funktionen) sind im [Changelog](https://github.com/binref/refinery/blob/master/CHANGELOG.md) dokumentiert.
Folge mir auf [Mastodon][] für Updates zu besonders wichtigen Releases.
## Dokumentation
Der Hilfetext, der angezeigt wird, wenn eine Unit mit dem Schalter `-h` oder `--help` ausgeführt wird, ist ihre Hauptdokumentation.
Die [automatisch generierte Dokumentation][docs] enthält eine Zusammenstellung dieser Ausgabe für jede Unit auf oberster Ebene,
aber auch die Spezifikation für die drei grundlegenden Konzepte des Toolkits:
[Framing][frame], [Multibin-Argumente][argformats] und [Meta-Variablen][meta].
Eine Volltextsuche der Beschreibung und des Hilfetexts für jede Unit ist auch auf der Kommandozeile verfügbar,
über den bereitgestellten Befehl `binref`. In Anerkennung der Tatsache, dass Referenzdokumentation etwas trocken sein kann,
gibt es eine laufende Bemühung, eine Reihe von [Tutorials](https://github.com/binref/refinery/blob/master/tutorials) zu erstellen; ich empfehle sehr, sie sich anzusehen.
Darüber hinaus sammle ich unten zusätzliche Ressourcen (einschließlich einiger von Dritten erstellter).
> [!NOTE]
> Refinery befindet sich noch in der Alpha-Phase und die Schnittstelle kann sich manchmal ändern,
> d. h. Units und Parameter können entfernt oder umbenannt werden.
> Daher kann es vorkommen, dass bestimmte Kommandozeilen aus älteren Videos und Blogbeiträgen nicht mehr funktionieren.
- [`2021/08`] [OALabs][OA] war so freundlich, mich [das Toolkit in einem Feature-Video vorzustellen][VOD1].
Im Video arbeite ich im Wesentlichen den Inhalt von
[dem ersten Tutorial](https://github.com/binref/refinery/blob/master/tutorials/tbr-files.v0x01.netwalker.dropper.ipynb) durch.
- [`2021/11`] [Johannes Bader][JB] schrieb einen großartigen [Blogbeitrag][BLOG] über die Analyse von Malspam mit binary refinery.
- [`2024/03`] [Malware Analysis For Hedgehogs][MH] erstellte [ein Video über das Entpacken einer XWorm-Sample][VOD2] mit refinery.
- [`2024/11`] [the CyberYeti][CY] hatte mich [im Stream, um refinery vorzustellen][VOD3].
- [`2025/06`] Ich war [erneut im Stream][VOD4] mit [the CyberYeti][CY], dieser ist etwas roher.
Alle Fehler, die du hier sehen kannst, wurden behoben. 😉
Die Showcases enthalten wieder Beispiele aus dem Beispielabschnitt unten und den [Tutorials](https://github.com/binref/refinery/blob/master/tutorials).
## Lizenz
Die Binary Refinery ist (c) 2019 Jesko Hüttenhain und unter einer [3-Clause BSD License][license] veröffentlicht.
Dieses Repository enthält auch [eine Kopie des vollständigen Lizenztextes](https://github.com/binref/refinery/blob/master/LICENSE.md).
Wenn du etwas damit machen möchtest, das nicht von dieser Lizenz abgedeckt ist, kannst du dich gerne an den Autor wenden.
## Warnungen & Ratschläge
Die refinery erfordert mindestens **Python 3.11**.
Es wird empfohlen, sie in einer eigenen [virtuellen Umgebung][venv] zu installieren:
Das Paket kann **viele** Abhängigkeiten mitbringen,
und die Installation in dein globales Python ist etwas anfällig für Versionskonflikte.
Da das Toolkit außerdem eine große Anzahl neuer Befehle einführt,
besteht eine gute Chance, dass einige davon auf manchen Systemen kollidieren,
und sie in einer eigenen separaten virtuellen Umgebung zu halten, ist eine Möglichkeit, das zu verhindern.
Wenn du alle refinery-Befehle jederzeit in deiner Shell verfügbar haben möchtest (d. h. ohne in eine benutzerdefinierte virtuelle Umgebung wechseln zu müssen),
hast du auch die Möglichkeit, ein _Präfix_ für die Installation zu wählen,
das vor jeden installierten Befehl-Shim gesetzt wird.
Wenn du beispielsweise `r.` als Präfix wählst, wird die [emit][]-Unit als Befehl `r.emit` installiert.
Ein zusätzlicher Vorteil ist, dass du `r.` eingeben und zweimal <kbd>Tab</kbd> drücken kannst, um eine Liste aller verfügbaren refinery-Befehle zu erhalten.
Beachte jedoch, dass in der Dokumentation kein Präfix angenommen wird und es ein Entwicklungsziel von refinery ist, auf den meisten Systemen _nicht_ zu kollidieren.
Der Autor verwendet kein Präfix und bietet diese Option als Sicherheitsnetz an.
## Installation
Der einfachste Weg, refinery zu installieren und zu aktualisieren, ist über pip.
Stelle zunächst sicher, dass du die neueste Version ausführst:
```
python -m pip install -U pip
```
Dann installiere einfach das refinery-Paket:
```
pip install -U binary-refinery
```
Wenn du ein Präfix für alle Units wählen möchtest, kannst du es über die Umgebungsvariable `REFINERY_PREFIX` angeben.
Der folgende Befehl installiert refinery beispielsweise in die aktuelle Python-Umgebung mit dem Präfix `r.` unter Linux:
```bash
REFINERY_PREFIX=r. pip install -U binary-refinery
```
Unter Windows müsstest du die folgenden Befehle ausführen:
```batch
set REFINERY_PREFIX=r.
pip install -U binary-refinery
```
Die Angabe des speziellen Präfixes `!` hat zur Folge, dass überhaupt keine Shell-Befehle erstellt werden
und binary refinery nur als Bibliothek installiert wird.
Wenn du die aktuelle refinery `HEAD` installieren möchtest, kannst du alle oben genannten Schritte wiederholen und dabei dieses Repository anstelle des pip-Pakets angeben.
Der folgende Befehl installiert beispielsweise den allerneuesten refinery-Commit:
```
pip install -U git+git://github.com/binref/refinery.git
```
Wenn du schließlich [REMnux][remnux-main] verwendest, kannst du deren [refinery Docker-Container][remnux] nutzen.
## Claude Skill Installation
Wenn du deinem lokalen Malware-Analyse-[claude][] beibringen möchtest, binary refinery zu verwenden, sieh dir den [Binary Refinery Skill][agent] an.
## Shell-Unterstützung
Das Folgende ist eine Zusammenfassung, wie gut verschiedene Shell-Umgebungen derzeit unterstützt werden:
| Shell | Plattform | Status | Kommentar |
|:-----------|:----------|:----------------|:-----------------------------------------------------------------|
| Bash | Posix | 🔵 Gut | Wird gelegentlich vom Autor verwendet. |
| CMD | Windows | 🔵 Gut | Wird ausgiebig vom Autor verwendet. |
| PowerShell | Windows | 🟡 Akzeptabel | Es [funktioniert einfach, wenn die PowerShell-Version mindestens 7.4 ist.][psh1] |
| Zsh | Posix | 🟠 Kleinere Probleme | Nach einer [Diskussion][zsh1] gibt es einen [Fix][zsh2]. |
| Fish | Posix | 🟠 Kleinere Probleme | Siehe Issue [#55][fsh1] und Diskussion [#22][fsh2]. |
Wenn du eine andere Shell verwendest und Feedback mitteilen möchtest, [lass es mich wissen](https://github.com/binref/refinery/discussions)!
## Modulare Abhängigkeiten
Es gibt einige sehr situative Units mit (manchmal großen) externen Abhängigkeiten.
Beispielsweise ist [stego][] eine Unit, die die Bildparsing-Bibliothek `Pillow` erfordert.
Einige Bibliotheken werden nicht standardmäßig installiert, um die Installationszeit für refinery für Erstbenutzer auf einem vernünftigen Niveau zu halten.
Die entsprechenden Units sagen dir, was zu tun ist, wenn ihre Abhängigkeit fehlt:
```
$ emit config.png | stego RG
(13:37:00) failure in stego: dependency Pillow is missing; run pip install Pillow
```
Du kannst diese fehlenden Abhängigkeiten dann manuell installieren.
Wenn du nicht durch fehlende Abhängigkeiten gestört werden möchtest und eine lange refinery-Installation nicht scheust, kannst du das Paket wie folgt installieren:
```
pip install -U binary-refinery[all]
```
wodurch _alle_ Abhängigkeiten zusätzlich zu den erforderlichen installiert werden.
Genauer gesagt gibt es die folgenden zusätzlichen Kategorien:
| Name | Enthaltene Abhängigkeiten |
|-----------:|:------------------------------------------------------------------|
| `default` | empfohlene Auswahl vernünftiger Abhängigkeiten, Wahl des Autors |
| `extended` | eine erweiterte Auswahl, wobei nur die obskursten ausgeschlossen werden |
| `all` | alle Abhängigkeiten für alle refinery-Units |
Diese sind hier in aufsteigender Reihenfolge aufgeführt, d. h. `extended` installiert alles, was `default` installieren würde.
## Bleeding Edge
Alternativ kannst du dieses Repository klonen und die Skripte [update.sh](https://github.com/binref/refinery/blob/master/update.sh) (unter Linux) oder [update.ps1](https://github.com/binref/refinery/blob/master/update.ps1) (unter Windows) verwenden, um das refinery-Paket in einer lokalen virtuellen Umgebung zu installieren.
Der Installations- und Aktualisierungsprozess für diese Methode besteht einfach darin, das Skript auszuführen:
- es zieht das Repository,
- aktiviert die virtuelle Umgebung,
- deinstalliert `binary-refinery`,
- und installiert dann `binary-refinery[all]`.
## Dokumentation generieren
Du kannst auch die gesamte Dokumentation lokal generieren.
Führe dazu das Skript [run-pdoc3.py](https://github.com/binref/refinery/blob/master/run-pdoc3.py) aus.
Dies wird **fehlschlagen**, es sei denn, du führst es aus einer Umgebung aus, in der binary refinery als Python-Paket installiert wurde.
Um es auszuführen, musst du den Pfad einer virtuellen Umgebung als erstes Kommandozeilenargument an [run-pdoc3.py](https://github.com/binref/refinery/blob/master/run-pdoc3.py) angeben,
wodurch das Skript sich selbst erneut mit dem Interpreter dieser Umgebung ausführt.
Wenn du sicher bist, dass du [run-pdoc3.py](https://github.com/binref/refinery/blob/master/run-pdoc3.py) ausführen möchtest,
gibt es einen Kommandozeilenschalter, um das Skript zu zwingen, mit dem aktuellen Standard-Python-Interpreter zu laufen.
Das Skript installiert das [pdoc3-Paket][pdoc3] und verwendet es, um eine HTML-Dokumentation für das `refinery`-Paket zu generieren.
Die Dokumentation ist dann im Unterverzeichnis `html` direkt neben dieser Readme-Datei zu finden.
Die [Tutorials](https://github.com/binref/refinery/blob/master/tutorials) sind Jupyter-Notebooks, die du einfach ausführen und ausführen kannst, wenn deine virtuelle Umgebung [Jupyter installiert hat][jupyter].
Es ist erwähnenswert, dass [Visual Studio Code eine sehr komfortable Unterstützung für Jupyter hat][jupyter-vscode].
## Beispiele
### Einfache Beispiele
Die Units [emit][] und [dump][] spielen eine besondere Rolle:
Erstere dient zur Ausgabe von Daten, letztere zum Ablegen von Daten in die Zwischenablage oder auf die Festplatte.
Betrachte als Beispiel die folgende Pipeline:
```
emit M7EwMzVzBkI3IwNTczM3cyMg2wQA | b64 | zl | hex
```
Hier geben wir den String `M7EwMzVzBkI3IwNTczM3cyMg2wQA` aus,
dekodieren ihn mit [b64][] aus Base64,
dekomprimieren das Ergebnis mit [zl][] mittels zlib
und dekodieren schließlich die dekomprimierten Daten mit [hex][].
Jede Unit führt standardmäßig die _"Dekodierungs"_-Operation einer bestimmten Transformation durch, aber einige von ihnen implementieren auch die umgekehrte Operation.
Wenn sie dies tun, geschieht dies immer durch Angabe des Kommandozeilenschalters `-R` oder `--reverse`.
Du kannst den obigen Base64-String mit dem folgenden Befehl erzeugen, da [hex][], [zl][] und [b64][] alle die umgekehrte Operation bereitstellen:
```
emit "Hello World" | hex -R | zl -R | b64 -R
```
Angesichts einer Datei `packed.bin`, die einen Base64-kodierten Payload-Puffer enthält, extrahiert die folgende Pipeline besagten Payload nach `payload.bin`:
```
emit packed.bin | carve -l -t1 b64 | b64 | dump payload.bin
```
Die [carve][]-Unit kann verwendet werden, um Datenblöcke aus dem Eingabepuffer herauszuschneiden;
in diesem Fall sucht sie nach Base64-kodierten Daten, sortiert sie nach Länge (`-l`) und gibt die erste davon zurück (`-t1`),
wodurch der größte Base64-artige Datenblock aus `packed.bin` herausgeschnitten wird.
Die Daten werden dann Base64-dekodiert und in die Datei `payload.bin` geschrieben.
Die Unit [pack][] entnimmt alle numerischen Ausdrücke aus einem Textpuffer und wandelt sie in ihre binäre Darstellung um.
Ein einfaches Beispiel ist die Pipeline
```
emit "0xBA 0xAD 0xC0 0xFF 0xEE" | pack | hex -R
```
die den String `BAADC0FFEE` ausgibt.
### Kurz & Knackig
Extrahiere den größten Teil Base64-kodierter Daten aus einem BLOB und dekodiere ihn:
```
emit file.exe | carve -ds b64
```
Schneide eine ZIP-Datei aus einem Puffer heraus, wähle eine DLL daraus aus und zeige Informationen darüber an:
```
emit file.bin | carve-zip | xtzip file.dll | pemeta
```
Liste PE-Dateisektionen mit ihrem entsprechenden SHA-256-Hash auf:
```
emit file.exe | vsect [| sha256 -t | pf {} {path} ]]
```
Liste rekursiv alle Dateien im aktuellen Verzeichnis mit ihrem jeweiligen SHA-256-Hash auf:
```
ef "**" [| sha256 -t | pf {} {path} ]]
```
Extrahiere Indikatoren aus allen Dateien, die rekursiv im aktuellen Verzeichnis aufgelistet werden:
```
ef "**" [| xtp -n6 ipv4 socket url email | dedup ]]
```
Wandle die fest codierte IP-Adresse `0xC0A80C2A` in Netzwerk-Byte-Reihenfolge in ein lesbares Format um:
```
emit 0xC0A80C2A | pack -EB4 | pack -R [| sep . ]
```
Führe eine Einzelbyte-XOR-Brute-Force durch und versuche in jeder Iteration, einen PE-Datei-Payload zu extrahieren:
```
emit file.bin | rep 0x100 [| xor v:index | carve-pe -R | peek | dump {name} ]
```
### Malware-Konfigurationsbeispiele
Extrahiere einen RemCos-C2-Server:
```
emit c0019718c4d4538452affb97c70d16b7af3e4816d059010c277c4e579075c944 \
| perc SETTINGS [| put keylen cut::1 | rc4 cut::keylen | xtp socket ]
```
Extrahiere eine AgentTesla-Konfiguration:
```
emit fb47a566911905d37bdb464a08ca66b9078f18f10411ce019e9d5ab747571b40 \
| dnfields [| aes x::32 --iv x::16 -T ]] \
| rex -M "((??email))\n(.*)\n(.*)\n:Zone" addr={1} pass={2} host={3}
```
Extrahiere den PowerShell-Payload aus einem bösartigen XLS-Makro-Dropper:
```
emit 81a1fca7a1fb97fe021a1f2cf0bf9011dd2e72a5864aad674f8fea4ef009417b [ \
| xlxtr 9.5:11.5 15.15 12.5:14.5 [ \
| scope -n 3 | chop -t 5 [| sorted -a | snip 2: | sep ] \
| pack 10 | alu --dec -sN B-S ]] \
| dump payload.cmd
```
Und hole die Domains für die nächste Stufe:
```
emit payload.cmd | cmdarg | ps1 | xtp -f domain
```
Extrahiere die Konfiguration von entpackten HawkEye-Samples:
```
emit ee790d6f09c2292d457cbe92729937e06b3e21eb6b212bf2e32386ba7c2ff22c \
| put cfg perc[RCDATA]:c:: [\
| xtp guid | pbkdf2 48 rep[8]:h:00 | cca eat:cfg | aes -Q x::32 --iv x::16 ] \
| dnds
```
Warzone RAT:
```
emit 4537fab9de768a668ab4e72ae2cce3169b7af2dd36a1723ddab09c04d31d61a5 \
| vsect .bss | struct I{key:{}}{} [\
| rc4 eat:key | struct I{host:{}}{port:H} {host:u16}:{port} ]
```
Extrahiere den Payload aus einem Shellcode-Loader und schneide dessen C2 heraus:
```
emit 58ba30052d249805caae0107a0e2a5a3cb85f3000ba5479fafb7767e2a5a78f3 \
| rex yara:50607080.* [| struct LL{s:L}{} | xor -B2 rand[s]:msvc | xtp url ]
```
Hole die bösartigen VBA-Makros aus einer vergessenen Zeit, als dies noch so gemacht wurde:
```
emit ee103f8d64cd8fa884ff6a041db2f7aa403c502f54e26337c606044c2f205394 \
| vbamc
```
Und extrahiere dann den bösartigen Downloader-Payload:
```
emit ee103f8d64cd8fa884ff6a041db2f7aa403c502f54e26337c606044c2f205394 \
| doctxt | repl drp:c: | carve -s b64 | rev | b64 | rev | ppjscript
```
Extrahiere Payload-URLs aus einem bösartigen PDF-Dokument:
```
emit 066aec7b106f669e587b10b3e3c6745f11f1c116f7728002f30c072bd42d6253 \
| xt JS | csd string | csd string | url | xtp url [| urlfix ]]
```
Extrahiere die Payload-URL aus einem Equation-Editor-Exploit-Dokument:
```
emit e850f3849ea82980cf23844ad3caadf73856b2d5b0c4179847d82ce4016e80ee \
| officecrypt | xt oleObject | xt native | rex Y:E9[] | vstack -a=x32 -w=200 | xtp
```
### AES-Verschlüsselung
Angenommen, `data` ist eine Datei, die mit 256-Bit-AES im CBC-Modus verschlüsselt wurde.
Der Schlüssel wurde aus der geheimen Passphrase `swordfish` unter Verwendung der PBKDF2-Schlüsselableitungsroutine mit dem Salt `s4lty` abgeleitet.
Der IV ist dem Puffer als die ersten 16 Bytes vorangestellt.
Er kann mit der folgenden Pipeline entschlüsselt werden:
```
emit data | aes --mode cbc --iv cut::16 pbkdf2[32,s4lty]:swordfish
```
Hier sind sowohl `cut:0:16` als auch `pbkdf2[32,s4lty]:swordfish` Multibin-Argumente, die einen speziellen Handler verwenden.
In diesem Fall extrahiert `cut:0:16` den Slice `0:16` (d. h. die ersten 16 Bytes) aus den Eingabedaten - nach Anwendung dieses Multibin-Handlers
wurden die ersten 16 Bytes aus den Eingabedaten entfernt und das Argument `iv` auf genau diese 16 Bytes gesetzt.
Das letzte Argument gibt den 32-Byte-Verschlüsselungsschlüssel an:
Der Handler `pbkdf2[32,s4lty]` hingegen weist refinery an, eine Instanz der pbkdf2-Unit zu erstellen, als hätte man ihr die Kommandozeilenparameter `32` und `s4lty` in dieser Reihenfolge übergeben, und den Byte-String `swordfish` mit dieser Unit zu verarbeiten.
Als einfacher Test wird die folgende Pipeline einen Beispieltext verschlüsseln und entschlüsseln:
```
emit "Once upon a time, at the foot of a great mountain ..." ^
| aes pbkdf2[32,s4lty]:swordfish --iv md5:X -R | ccp md5:X ^
| aes pbkdf2[32,s4lty]:swordfish --iv cut:0:16
```
[OA]: https://www.youtube.com/c/OALabs
[JB]: https://bin.re/
[MH]: https://www.youtube.com/@MalwareAnalysisForHedgehogs
[CY]: https://www.youtube.com/@jstrosch
[Mastodon]: https://infosec.exchange/@rattle
[BLOG]: https://bin.re/blog/analysing-ta551-malspam-with-binary-refinery/
[VOD1]: https://www.youtube.com/watch?v=4gTaGfFyMK4
[VOD2]: https://www.youtube.com/watch?v=5ZtmYNmVMKo
[VOD3]: https://www.youtube.com/watch?v=-B072w0qjNk
[VOD4]: https://www.youtube.com/watch?v=HuLONk0Rt98
[remnux]: https://hub.docker.com/r/remnux/binary-refinery
[remnux-main]: https://remnux.org/
[pdoc3]: https://pdoc3.github.io/pdoc/
[docs]: https://binref.github.io/
[argformats]: https://binref.github.io/lib/argformats.html
[frame]: https://binref.github.io/lib/frame.html
[meta]: https://binref.github.io/lib/meta.html
[license]: https://opensource.org/licenses/BSD-3-Clause
[tests]: https://github.com/binref/refinery/actions
[codecov]: https://codecov.io/gh/binref/refinery/?branch=master
[pypi]: https://pypi.org/project/binary-refinery/
[venv]: https://docs.python.org/3/library/venv.html
[zsh1]: https://github.com/binref/refinery/discussions/18
[zsh2]: https://raw.githubusercontent.com/binref/refinery/master/shells/zsh
[psh1]: https://github.com/binref/refinery/issues/5
[fsh1]: https://github.com/binref/refinery/discussions/55
[fsh2]: https://github.com/binref/refinery/issues/22
[dump]: https://binref.github.io/
[emit]: https://binref.github.io/
[stego]: https://binref.github.io/
[hex]: https://binref.github.io/
[zl]: https://binref.github.io/
[b64]: https://binref.github.io/
[carve]: https://binref.github.io/
[pack]: https://binref.github.io/
[claude]: https://code.claude.com/docs/en/overview
[agent]: https://github.com/binref/agent/
[jupyter]: https://jupyter.org/install
[jupyter-vscode]: https://code.visualstudio.com/docs/datascience/jupyter-notebooks