karankantaria/binvizBinärer Visualisierer und Triage-Werkzeug — Entropie-, Byte-Klassen- und Hilbert-Oberflächen, Punktdiagramme und Kontrollflussgraphen über einem gemeinsamen Adressraum-Modell.
Binärvisualisierungs- und Triage-Tool: verknüpfte interaktive Ansichten (Entropie, Histogramme, Bild-/Punktdiagramm-Oberflächen, Kontrollflussgraphen) über einem gemeinsamen Adressraummodell.
pipx install binviz && binviz serve
Öffnen Sie eine Datei, und jede Ansicht betrachtet denselben Adressraum. Wählen Sie einen Bereich in einer aus, und die übrigen folgen — das Ziel ist es, die Frage „Was ist diese Region?“ zu beantworten, indem man sie gleichzeitig auf mehrere Arten betrachtet.
binviz model parst ELF/PE/Mach-O über LIEF in Regionen, Symbole und eine Offset↔virtuelle-Adress-Zuordnung und materialisiert Lücken und Überlagerungen. Fehlerhafte Eingaben fallen auf ein Rohmodell zurück, statt zu scheitern.binviz triage sagt, wie die Datei aussieht und warum; in der UI führt jeder Befund per Klick zu den Bytes, aus denen er abgeleitet wurde.Die UI besteht aus fünf Arbeitsbereichen — Übersicht, Bytes, Muster, Code und Alles — über derselben Auswahl. Nur statische Analyse: Proben werden geparst, niemals ausgeführt.
Gerendert mit demselben Code, mit dem die UI zeichnet, direkt aus der CLI — neu generieren mit python docs/make_plates.py.
| Ein statisches Binärprogramm | Dasselbe Programm, UPX-gepackt |
|---|---|
 |  |
| Code, Strings und Padding trennen sich in sichtbare Territorien. | Die Struktur kollabiert zu gleichförmigem Rauschen — das Kennzeichen von Packen. |
 |  |
| Fensterbasierte Entropie bleibt gebändert und niedrig. | Flach und hoch, bis direkt zum Entpack-Stub. |
| Richtige Zeilenlänge | Falsche Zeilenlänge |
|---|---|
 |  |
Dieselben Bytes, eine Zahl anders. Genau deshalb gibt es den Zeilenlängen-Vorschläger: Die falsche Zeilenlänge verwandelt ein Foto in diagonales Rauschen, und man schließt daraus, dass es kein Foto gibt.
ARCHITECTURE.md beschreibt, wie es zusammengesetzt ist: was ausgeliefert wird, das Branding, das jede Oberfläche erbt, die Konventionen, denen ein neuer Bildschirm folgen muss, und die Einschränkungen, die bewusst gewählt sind. SECURITY.md ist die Sicherheitslage.
python -m venv .venv
# -c pinnt auf die exakten Versionen, gegen die die Suite grün ist; pyproject.toml
# veröffentlicht Bereiche, also ohne -c bekommt man, was heute aufgelöst wird
.venv/Scripts/pip install -e ".[dev]" -c constraints-dev.txt # POSIX: .venv/bin/pip
# Ground-Truth-Korpus bauen (verwendet zig cc aus dem ziglang-Pip-Paket;
# benötigt UPX im PATH, in $UPX oder entpackt in corpus/tools/upx-*/)
make -C corpus # oder: python corpus/build.py
# Schwellenwerte werden gemessen, nie hartkodiert (siehe ARCHITECTURE.md §2.1)
python corpus/calibrate.py # schreibt corpus/calibration.json
pytest # funktionale Suite
pytest -m perf -s # 100-MB-Leistungsziele
binviz probe corpus/out/hello_O2
binviz model corpus/out/hello_upx
binviz signal corpus/out/hello_upx --name entropy_4096 --png out.png
binviz hist corpus/out/ramp16.bin --n 2 --dtype u16le --png bigram.png
# Oberflächen: -p übergibt Oberflächenparameter
binviz surface corpus/out/hello_static --name hilbert -p mode=byteclass --png h.png
binviz surface corpus/out/rgb_raw.bin --name image -p mode=rgb8 -p width=320 --png i.png
binviz surface corpus/out/repeats.bin --name dotplot -p mode=exact --png d.png
binviz stride corpus/out/bayer_raw.bin --mode bayer_RGGB_RGB_12
# Code
binviz disasm corpus/out/hello_O2 --limit 20
binviz functions corpus/out/hello_static --sort size
binviz cfg corpus/out/hello_O2 --func main --dot main.dot
# Das Urteil und warum
binviz triage corpus/out/hello_upx
binviz serve # 127.0.0.1:8000
Er gibt eine URL mit einem Sitzungstoken aus — öffnen Sie diese. Jede /api-Route erfordert das Token, denn „es lauscht nur auf localhost“ ist keine Verteidigung gegen eine Webseite in einem anderen Tab, die 127.0.0.1 genauso erreicht wie jeder andere Ursprung. SECURITY.md enthält die Begründung.
Der Dateizugriff ist auf --root beschränkt (Standard: das Arbeitsverzeichnis), daher werden Pfade außerhalb davon verweigert.
Alle vier haben ein Flag und eine Umgebungsvariable, und alle vier existieren, um zu verhindern, dass ein lokaler Aufrufer mehr verbraucht, als beabsichtigt. Die Standardwerte sind für ein Laptop gewählt; erhöhen Sie sie, wenn Ihre Maschine größer ist.
| Flag | Env | Standard | Was es begrenzt |
|---|---|---|---|
--max-cache BYTES | BINVIZ_MAX_CACHE | 5 GiB | Gesamtgröße der gecachten Analysen. Darüber hinaus werden am wenigsten zuletzt verwendete Einträge entfernt — niemals einer, der gerade analysiert oder angezeigt wird. |
--max-upload BYTES | BINVIZ_MAX_UPLOAD | 8 GiB | Größter akzeptierter Upload. |
--max-analyses N | — | 4 | Gleichzeitige Analysen; darüber hinaus gibt /api/open 503 zurück. |
--root DIR | — | cwd | Verzeichnis, aus dem der Server Dateien lesen darf. |
Analysen werden unter ~/.cache/binviz (oder $BINVIZ_CACHE) gecacht, schlüsselbasiert auf dem Inhalts-Hash, sodass das erneute Öffnen eines Binärprogramms sofort erfolgt. Erhöhen Sie --max-cache, wenn Sie lieber mehr davon behalten möchten; der Cache kann jederzeit von Hand gelöscht werden — der schlimmste Fall ist, dass das nächste Öffnen neu analysiert.
Weitere Flags: --token, um ein Token über Neustarts hinweg zu fixieren (nützlich mit dem Vite-Dev-Proxy, der BINVIZ_TOKEN liest), --port, --cache und --no-auth für CI. --no-auth gibt ein Banner aus, das sagt, was es deaktiviert hat; verwenden Sie es nicht auf einer Maschine, die Sie teilen.
pip install "binviz[app]"
binviz app # natives Fenster; --browser für Ihren Browser
Derselbe Server, dasselbe Token, dieselbe --root-Beschränkung wie bei binviz serve — der einzige Unterschied ist, was es anzeigt. Ohne installiertes pywebview öffnet binviz app stattdessen Ihren Browser.
Es gibt die URL aus, auf der es läuft, bewusst: Die UI in ein Fenster zu packen, entfernt den Netzwerk-Listener nicht, es macht nur leichter zu vergessen, dass es einen gibt. Der Listener ist in beiden Fällen authentifiziert, und es gibt kein --no-auth bei binviz app.
Das Fenster stellt der Seite genau eine Funktion zur Verfügung — einen nativen Dateiauswähler — und sonst nichts. Siehe src/binviz/app.py, warum diese Liste so kurz ist, wie sie ist.
Releases liefern ein Wheel und sonst nichts. Ein unsigniertes eingefrorenes Python-Programm, das capstone und lief bündelt und dazu dient, gepackte Binärdateien zu sezieren, ist genau das Profil, auf das SmartScreen- und AV-Heuristiken falsch positiv reagieren — also liefert das Repo statt dessen, was Sie brauchen, um es selbst zu bauen, was Code-Signierung vollständig umgeht.
pip install pyinstaller # 6.x
python tools/build_ui.py # baut web/ und stagt es in das Paket
pyinstaller packaging/binviz.spec # -> dist/binviz/
Erwarten Sie ~100 MB, dominiert von numpy und lief. Es ist ein Onedir-Bundle, keine einzelne selbstextrahierende Datei: Starten Sie dist/binviz/binviz.exe (oder doppelklicken Sie darauf) für das Desktop-Fenster, oder geben Sie ihm einen beliebigen Unterbefehl — dist/binviz/binviz.exe triage sample.exe — denn der eingefrorene Build ist die gesamte CLI, nicht nur das Fenster.
Der Staging-Schritt ist nicht optional. web/dist liegt außerhalb des Python-Pakets, sodass das Überspringen eine App erzeugt, deren Fenster auf einem JSON-404 öffnet; die Spec weigert sich zu bauen, statt das stillschweigend zuzulassen.
Auf macOS erzeugt derselbe Befehl auch dist/Striate.app, gebrandet aus packaging/icons/icon.icns. Keines von beiden wurde auf einem Mac ausgeführt — siehe ARCHITECTURE.md §5.
--root ist standardmäßig weiterhin das Arbeitsverzeichnis, sodass ein doppelgeklicktes Programm auf den Ordner beschränkt ist, in dem es startet — was normalerweise der eigene Ordner der App ist. Setzen Sie „Start in“ der Verknüpfung oder starten Sie es mit --root DIR.
Ein doppelgeklicktes Programm fragt nach einer Anmeldeinformation. Ohne Argumente führt der eingefrorene Build binviz app --auth local aus, was der eine Unterschied zum Standard des Wheels ohne Anmeldebildschirm ist. Die beiden beantworten unterschiedliche Fragen: binviz app, in ein Terminal getippt, ist bereits eine bewusste Handlung dessen, der die Sitzung besitzt, während ein Doppelklick nichts etabliert — es ist der einzige Startpfad ohne Terminal, ohne getippten Befehl und ohne Beschränkungsentscheidung dahinter. Nach der Anmeldeinformation zu fragen, ist die Art, wie das Fenster laut ausspricht, was das Terminal gesagt hätte. Führen Sie zuerst binviz passwd aus, um eine zu setzen, oder übergeben Sie --auth none explizit, um sie zu überspringen; alles, was Sie in der Befehlszeile angeben, gewinnt weiterhin.
Standardmäßig gibt es keinen Anmeldebildschirm und nichts zu kopieren: Der Server erzeugt ein Sitzungstoken und injiziert es in die Seite, die er ausliefert, sodass das Öffnen von http://127.0.0.1:8000/ einfach funktioniert, während jeder API-Aufruf weiterhin authentifiziert ist.
Auf einer Maschine, die Sie teilen, aktivieren Sie den Anmeldebildschirm:
binviz passwd # fragt ab; scrypt-Digest, Modus 0600
binviz serve --auth local
Wenn Sie binviz passwd überspringen, beansprucht die erste Anmeldung die Installation — das Startbanner warnt davor, denn wer zuerst den Port erreicht, wird zum Konto.
Ein doppelgeklicktes eingefrorenes Programm aktiviert --auth local für sich selbst; siehe Eine eigenständige App bauen, warum dieser Standard sich vom Wheel unterscheidet.
Der Anmeldebildschirm ist nicht die Sicherheitsgrenze; die Token-Prüfung auf jeder /api-Route ist es. Alles auf der Maschine kann das Formular überspringen und die API direkt aufrufen, was genau der Grund ist, warum das Token existiert. Siehe SECURITY.md.
binviz öffnet Dateien, die ein Angreifer gewählt hat — das ist der Job, kein Randfall, und ein Triage-Tool, bei dem die Analyse von Malware den Analysten kompromittiert, ist das schlimmste verfügbare Versagen. Proben werden geparst, niemals ausgeführt. Was mit dem Rest geschieht:
Gegen ein feindseliges Binärprogramm
id in jeder /api/{id}/…-Route muss exakt 64 Hexadezimalzeichen sein, bevor sie zum Erstellen eines Pfads verwendet wird.Gegen einen feindseligen Browser — die Bedrohung, die „es lauscht nur auf localhost“ nicht adressiert, denn eine Seite in einem anderen Tab erreicht 127.0.0.1 wie jeder andere Ursprung:
/api-Route erfordert ein Token. Es wird beim Start erzeugt und in die Seite injiziert, sodass nichts von Hand eingefügt wird und keine Route offen bleibt.--root beschränkt, was standardmäßig das Arbeitsverzeichnis ist. Pfade außerhalb davon werden verweigert.Host-Zulassungsliste und enge CORS, sodass der Ursprung, der Zugriff benötigt, der einzige ist, der ihn erhält.Das Desktop-Fenster entfernt den Netzwerk-Listener nicht, es macht nur leichter zu vergessen. Also gibt es kein --no-auth bei binviz app, und die js_api-Brücke legt genau eine Methode offen — pick_file(), die keine Argumente annimmt und einen Pfad durch dieselbe --root-Beschränkung zurückgibt. Ein Test schlägt fehl, wenn jemals eine zweite Methode erscheint.
Anmeldeinformationen für --auth local sind scrypt-Digests, geschrieben im Modus 0600; binviz speichert kein Klartext-Passwort.
SECURITY.md enthält das Bedrohungsmodell, die Begründung hinter jeder Kontrolle, was bewusst noch nicht getan ist und wie eine Schwachstelle privat gemeldet wird.
MIT — siehe LICENSE.
Das Korpus cross-kompiliert ELF-Proben mit zig cc, sodass keine Linux-Toolchain auf Windows/macOS benötigt wird — Proben werden geparst, niemals ausgeführt.