binviz

Visualizador y herramienta de triaje de binarios: vistas interactivas vinculadas (entropía, histogramas, superficies de imagen/dot-plot, grafos de flujo de control) sobre un único modelo de espacio de direcciones compartido.

pipx install binviz && binviz serve

Qué hace

Abre un archivo y cada vista observa el mismo espacio de direcciones. Selecciona un rango en una y el resto lo sigue: la idea es responder "¿qué es esta región?" mirándola de varias formas a la vez.

• Mapearlo. binviz model analiza ELF/PE/Mach-O mediante LIEF en regiones, símbolos y un mapeo offset↔dirección virtual, materializando huecos y superposiciones. La entrada malformada cae en un modelo crudo en lugar de fallar.
• Encontrar las partes que merecen atención. Entropía por ventanas y otras señales con nombre, superficies de clases de bytes y Hilbert, y clasificación de ventanas contra umbrales medidos a partir de un corpus de referencia en lugar de elegidos (ARCHITECTURE.md §2.1). Empaquetado, cifrado, código y relleno no se ven iguales.
• Identificar una codificación. Histogramas de bigramas y trigramas dispersos, un dot plot para repeticiones y autosimilitud, y una vista de imagen sobre 15 formatos de píxeles empaquetados y 24 modos Bayer — con un sugeridor de stride, porque un stride de fila incorrecto convierte una fotografía en ruido diagonal y concluyes que no hay fotografía.
• Leer el código. Decodificación Capstone por barrido lineal y descenso recursivo (probado diferencialmente contra objdump), una cascada de descubrimiento de funciones de cinco niveles que incluye tablas de salto, y grafos de flujo de control dispuestos en un worker — con la incertidumbre de un límite recuperado dibujada en lugar de oculta.
• Obtener un veredicto. binviz triage dice cómo se ve el archivo y por qué; en la interfaz, cada hallazgo enlaza con los bytes de los que se derivó.

La interfaz tiene cinco espacios de trabajo — Overview, Bytes, Patterns, Code y All — sobre la misma selección. Solo análisis estático: las muestras se analizan, nunca se ejecutan.

Capturas de pantalla

Láminas

Renderizadas por el mismo código que usa la interfaz, directamente desde la CLI — regenera con python docs/make_plates.py.

Un binario estático	El mismo programa, empaquetado con UPX
Código, cadenas y relleno se separan en territorios visibles.	La estructura colapsa en ruido uniforme — la firma del empaquetado.
La entropía por ventanas se mantiene en bandas y baja.	Plana y alta, hasta el stub de desempaquetado.

Stride de fila correcto	Stride de fila incorrecto

Los mismos bytes, un número diferente. Por eso existe el sugeridor de stride: el stride de fila incorrecto convierte una fotografía en ruido diagonal, y concluyes que no hay fotografía.

ARCHITECTURE.md es cómo está ensamblado: qué se distribuye, la marca que hereda cada superficie, las convenciones que debe seguir una nueva pantalla y las limitaciones que son deliberadas. SECURITY.md es la postura de seguridad.

Inicio rápido

python -m venv .venv
# -c fija las versiones exactas contra las que la suite está en verde; pyproject.toml
# publica rangos, así que sin él obtienes lo que se resuelva hoy
.venv/Scripts/pip install -e ".[dev]" -c constraints-dev.txt   # POSIX: .venv/bin/pip

# construye el corpus de referencia (usa zig cc del paquete pip de ziglang;
# necesita UPX en PATH, en $UPX, o descomprimido en corpus/tools/upx-*/)
make -C corpus                            # o: python corpus/build.py

# los umbrales se miden, nunca se codifican (ver ARCHITECTURE.md §2.1)
python corpus/calibrate.py                # escribe corpus/calibration.json

pytest                                    # suite funcional
pytest -m perf -s                         # objetivos de rendimiento de 100 MB

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

# superficies: -p pasa parámetros de superficie
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

# código
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

# el veredicto, y por qué
binviz triage corpus/out/hello_upx

Ejecutar el servidor

binviz serve                              # 127.0.0.1:8000

Imprime una URL que contiene un token de sesión — ábrela. Cada ruta /api requiere el token, porque "solo escucha en localhost" no es una defensa contra una página web en otra pestaña, que llega a 127.0.0.1 igual que cualquier otro origen. SECURITY.md tiene el razonamiento.

El acceso a archivos está confinado a --root (por defecto: el directorio de trabajo), por lo que las rutas fuera de él se rechazan.

Límites

Los cuatro tienen una bandera y una variable de entorno, y los cuatro existen para evitar que un llamador local consuma más de lo que pretendías. Los valores por defecto están elegidos para un portátil; súbelos si tu máquina es más grande.