Capítulo 03
Controles y registros
Qué significa que un parser esté verificado, qué registra un harness y cómo leer el registro de una ejecución.
Antes de entrar en Parsarium, un parser tiene que leer una entrada válida e informar correctamente sobre ella. Esa entrada es el control, y lo que pasó queda anotado en un registro. Juntos te dicen que el target está bien conectado antes de que pases horas haciéndole fuzzing.
Por qué empezar con una entrada válida
Un harness que rechaza todas las entradas parece muy robusto: nunca falla. Tampoco prueba nada. Lo mismo ocurre cuando el harness llama a la función equivocada, abre el archivo equivocado o captura todos los errores antes de que se ejecute el parser. Un control válido con una salida esperada conocida detecta todos estos problemas de una vez. Si el harness informa de ancho 2 y alto 1 para red-green.png, los bytes llegaron al parser y el parser los entendió.
Qué comprueba la verificación
- Una versión fijada. La versión exacta, instalada desde un archivo de bloqueo o una imagen fijada, con los hashes del código fuente.
- Una API de entrada documentada. La función que el proyecto documenta para analizar este formato. Detectar un tipo MIME o copiar bytes no cuenta.
- Un control válido. Un archivo pequeño en
controls/<format>/, identificado por su SHA-256. - Un resultado observado. Campos propios del formato, como dimensiones, nombres de entradas, número de páginas, etiquetas o valores de cabecera, comparados con la salida esperada.
Hasta que no se cumplen las cuatro, un paquete es una pista, no una entrada. Las pistas se guardan en los datos del catálogo junto con el motivo por el que siguen abiertas.
El registro de verificación
Cada target ejecutable tiene un verification.json junto a su Dockerfile. Registra cuándo se verificó el harness, el ID de la imagen Docker, las versiones de la cadena de herramientas, el hash de cada archivo del proyecto, la salida observada y cuántas líneas del código fuente del parser cubrió el control. Si cambia algún archivo del proyecto, su hash deja de coincidir y el harness se niega a ejecutarse hasta que se vuelva a verificar.
El registro de ejecución
Cuando pasas un archivo por un target, obtienes un registro como este:
{
"schema_version": 1,
"project": "png/python/pillow",
"input": "my.png",
"status": "ok",
"case_sha256": "…",
"case_bytes": 71,
"image_id": "sha256:…",
"exit_code": 0,
"duration_seconds": 0.412,
"stdout_tail": "…",
"stderr_tail": ""
}
El campo status describe el harness, no el parser:
| Estado | Significado |
|---|---|
ok | El harness terminó. El parser puede haber aceptado o rechazado la entrada; su salida está en stdout_tail. |
target_nonzero | El proceso terminó con un error. Merece la pena reproducirlo. |
timeout | La ejecución superó el límite de tiempo (60 segundos por defecto). |
input_too_large | La entrada supera 1 MiB, el límite del harness. |
infrastructure_error | Docker o la preparación del harness fallaron antes de que se ejecutara el parser. |
Conviene mantenerlos separados. Un rechazo es un comportamiento normal del parser. Una salida distinta de cero o un timeout son algo que hay que mirar.
Ideas clave
- Un control válido con una salida esperada conocida demuestra que los bytes llegan al parser y que el parser los entiende.
- Un paquete solo se convierte en target después de cuatro comprobaciones: versión fijada, API de entrada documentada, control válido y resultado observado. Hasta entonces es una pista.
- El estado del registro de ejecución describe el harness, no el parser. La aceptación está en la salida observada.
- Los registros de verificación fijan los hashes de los archivos, así que un harness modificado tiene que verificarse de nuevo antes de ejecutarse.
Comprueba lo que sabes
Responde a las cinco para ver tu resultado
Un registro de ejecución dice status: ok. ¿Qué sabes?
- Que el parser aceptó la entrada.
- Que el harness terminó. Si el parser aceptó la entrada está en su salida.
- Que la entrada es un archivo válido.
ok solo significa que el harness terminó. Un rechazo limpio también es ok; la respuesta del parser está en stdout_tail.
¿Por qué cada target necesita un control válido antes de hacer fuzzing?
- Hace que el fuzzing vaya más rápido.
- Muestra que los bytes llegan al parser y se entienden. Un harness que lo rechaza todo parecería muy robusto.
- AFL++ no arranca sin uno.
Sin un control no puedes distinguir un parser robusto de un harness roto. El control es la forma más barata de descartar lo segundo.
Un paquete aparece en una búsqueda de npm de «png», pero todavía no ha pasado el control. ¿Qué es en Parsarium?
- Un target
- Una pista
- Una familia
Los resultados de búsqueda siguen siendo pistas hasta que pasan las cuatro comprobaciones. Las pistas se guardan en los datos de la celda junto con el motivo por el que siguen abiertas.
Editas el archivo del harness de un proyecto. ¿Qué pasa en la siguiente ejecución?
- Su hash ya no coincide con el registro, así que hay que verificarlo de nuevo.
- Nada; el registro es solo informativo.
- Docker reconstruye la imagen sin avisar.
El registro de verificación enumera el hash de cada archivo del proyecto. Las ejecuciones comprueban esos hashes, lo que mantiene los resultados ligados al harness que se verificó.
Pasas un archivo de 2 MiB por un target. ¿Qué estado obtienes?
timeouttarget_nonzeroinput_too_large
Los harnesses aceptan entradas de hasta 1 MiB. Las entradas más grandes se rechazan antes de que se ejecute el parser.
Ejercicios
Ejercicio 3.1Calentamiento
Ejecuta el target stb_image con su propio control y con un archivo que ni siquiera es un PNG.
$ parsarium show png c stb --json $ parsarium run png c stb "$PARSARIUM/controls/png/red-green.png" --results runs/stb-control $ parsarium run png c stb "$PARSARIUM/controls/zip/hello.zip" --results runs/stb-zip
Abre los dos registros y compara status, exit_code y las finales de la salida. ¿Dónde dice stb_image qué le ha parecido el archivo ZIP?
Pista
Los registros se escriben como <sha256>.json dentro del directorio de --results.
Solución
El registro del control muestra las dimensiones y los píxeles en stdout_tail. El registro del ZIP muestra el rechazo de stb_image, en las finales de la salida o como un código de salida distinto de cero, según cómo informe el harness de los errores. El hábito importante es mirar la salida, no solo status.
Ejercicio 3.2Práctica
Abre los registros de verificación de dos targets PNG en lenguajes distintos y compáralos campo a campo.
cat "$PARSARIUM/projects/png/c/stb/verification.json" cat "$PARSARIUM/projects/png/python/pillow/verification.json"
¿Qué contiene cada lista de la cadena de herramientas? ¿Cuántas líneas del código fuente del parser cubrió cada control? ¿Puedes decir con estas cifras qué parser está mejor probado?
Pista
Busca toolchain, output y parser_source_lines_covered.
Solución
En el momento de escribir esto, el control de stb_image cubre 435 líneas del parser y el de Pillow 2.097. Eso no significa que Pillow esté mejor probado: las dos bases de código tienen tamaños distintos, están escritas en lenguajes distintos y las cifras de líneas salen de herramientas de cobertura distintas. Las cifras sirven para cada target por separado, por ejemplo para comprobar que una entrada nueva llega a más partes del mismo parser.
Ejercicio 3.3Reto
Elige una biblioteca de PNG que conozcas y que no esté en el catálogo. Escribe un harness mínimo para ella: que lea un archivo, llame a la API de parsing documentada e imprima el ancho y el alto. Decide qué debe imprimir y qué código de salida debe usar cuando el parser rechaza la entrada, y cuando ocurre algo inesperado.
Pista
Compara tu borrador con $PARSARIUM/projects/png/python/pillow/harness.py y adapter.py.
Solución
Un buen harness hace cuatro cosas. Llama al parser a través de la API que usaría un usuario real. Imprime campos observables y propios del formato. Trata un rechazo normal como un resultado normal, así que el código de salida sigue siendo cero y el motivo va a la salida. Y deja que los fallos inesperados, como cierres abruptos o errores que no forman parte del comportamiento documentado del parser, salgan como un código distinto de cero, porque esos son los que merece la pena investigar.