1# harkaq — banco de pruebas y piezas
2
3## Las piezas (Fase 1)
4
5| Fichero | Qué es | Dónde corre |
6|---|---|---|
7| `harkaq-audit.c` | el lector de evidencia; emite el `Verdict` JSON | **host**, junto a hammerd; necesita `CAP_AUDIT_READ` |
8| `harkaq-exec.c` | aplica la política y ejecuta el builder | **dentro** de bwrap, estático (rootfs musl) |
9| `harkaq-run.sh` | encadena lector + bwrap + exec + canario | host |
10
11```sh
12mkdir -p ~/.cache/harkaq
13gcc -O1 -Wall -o ~/.cache/harkaq/harkaq-audit harkaq-audit.c
14gcc -O1 -Wall -static -o ~/.cache/harkaq/harkaq-exec harkaq-exec.c
15sudo setcap cap_audit_read,cap_audit_control+ep ~/.cache/harkaq/harkaq-audit   # 1 vez
16
17printf 'ro /usr\nro /bin\nro /lib\nro /lib64\nro /etc\n' > /tmp/p.txt
18./harkaq-run.sh /tmp/p.txt '/bin/echo hola'
19```
20
21**`setcap` se pierde al recompilar** el lector: hay que repetirlo. Es a propósito que el
22privilegio viva en un helper chico y no en hammerd (§8 Q1c): `CAP_AUDIT_*` es superficie de más
23para el daemon entero.
24
25### El hito de Fase 1 (2026-07-15)
26
27```json
28limpio  {"estado":"Hermetico","canario_visto":true,"contador_kernel":1,"denials":[]}
29impuro  {"estado":"Impuro","canario_visto":true,"contador_kernel":2,
30         "denials":[{"blockers":"fs.read_file","path":"/mnt/vvv/takana/README.md",…}]}
31```
32
33Canario visto en ambos (la evidencia está *ganada*, no supuesta), contador del kernel coherente
34en ambos, y el impuro nombra el path exacto. Falta el acto real: derivar la política de la
35clausura de una receta de verdad (`harkaq-policy`) y contrastar una receta de-Alpinizada contra
36una que no lo está.
37
38### Sutileza: lo que DAC ya bloquea es invisible
39
40Un acceso que los permisos Unix rechazan **no genera registro de Landlock** — el hook del LSM ni
41llega a correr. Descubierto probando con `/root/.bashrc` (drwx------): el escenario "impuro" dio
42`Hermetico` porque DAC lo bloqueó antes.
43
44No rompe la afirmación de D2 (si DAC lo bloqueó, el build tampoco lo usó ⇒ `Hermetico` sigue
45siendo cierto), pero acota el **diagnóstico**: harkaq no te dice que el build lo *intentó*. Para
46la de-Alpinización da igual — el rootfs Alpine es todo world-readable — pero al escribir tests
47hay que elegir paths que DAC permita, o el control no controla nada.
48
49---
50
51## Banco de pruebas
52
53Ver `docs/16-harkaq-jaula.md`. Acá viven los experimentos que sostienen las afirmaciones del SDD:
54si el doc dice "medido", el que lo midió está en este directorio.
55
56## `q1-audit.c` — el gate del proyecto (Q1, ✅ cerrado 2026-07-15)
57
58Responde: *¿llegan los registros `AUDIT_LANDLOCK_*` a un lector?* Todo harkaq cuelga de eso — su
59producto es la evidencia, no la jaula.
60
61```sh
62gcc -O1 -Wall -o q1-audit q1-audit.c
63for s in same-exec new-exec new-exec-logon; do sudo ./q1-audit $s; done
64```
65
66Necesita root (`CAP_AUDIT_READ` para leer el multicast, `CAP_AUDIT_CONTROL` para encender el
67audit). **Enciende `audit_enabled=1` globalmente y no lo restaura** — reversible, no persiste al
68reboot (no toca el cmdline), pero deja `dmesg` más ruidoso mientras tanto.
69
70### Resultados en el laptop (ABI 10, kernel 7.2.0-rc3)
71
72| Escenario | Registros `ACCESS` | Qué prueba |
73|---|---|---|
74| `same-exec` | 2 | el kernel loguea por defecto sin `execve` |
75| `new-exec` | **0** | **flags por defecto ⇒ ciego tras `execve`** — el caso real de harkaq |
76| `new-exec-logon` | 4 | `LOG_NEW_EXEC_ON` lo arregla |
77
78Los registros traen `blockers=fs.read_file path="/etc/passwd" dev="nvme1n1p6" ino=4458369` y el
79`exe=` que lo intentó. Análisis completo en `docs/16-harkaq-jaula.md` §3.4.
80
81### Por qué aborta con código 4
82
83Si no puede **confirmar** `audit_enabled=1`, aborta en vez de reportar 0 registros. No es
84paranoia: la primera corrida dio 0 en los tres escenarios y parecía confirmar la hipótesis. Era un
85bug del instrumento (`AUDIT_GET` con `NLM_F_ACK` → el ACK llegaba antes que la respuesta → nunca
86se encendía el audit). Se detectó sólo porque el **control** (`same-exec`) también dio 0, y eso era
87imposible.
88
89Es el modo de falla de harkaq sobre su propio banco de pruebas: un sistema cuyo producto es la
90*ausencia* de algo no falla ruidosamente — dice que todo está bien. De ahí sale D9 (el canario
91deliberado), y de ahí sale la regla de este directorio: **todo experimento lleva un control que
92debe dar positivo.** Un experimento sin control no mide, tranquiliza.
93
94## `q1b-attrib.c` — userns y atribución (Q1b, ✅ cerrado 2026-07-15)
95
96Responde: *¿el lector del host ve las denegaciones de adentro de bwrap, y se puede atribuir cada
97registro a SU build con la granja en paralelo?*
98
99```sh
100gcc -O1 -Wall -o ~/.cache/harkaq/q1b q1b-attrib.c   # NO compilar bajo /tmp: --tmpfs /tmp lo tapa
101sudo ~/.cache/harkaq/q1b
102```
103
104Lanza 2 víctimas concurrentes en bwrap `--unshare-all` (los ns de `Sandbox::bwrap_args`), cada una
105con un canario de nonce distinto, y escucha desde el host. Las víctimas bajan a `$SUDO_UID`: el
106despliegue real es lector privilegiado + builds sin privilegio.
107
108Resultado: los registros **cruzan** el userns/pidns/mountns, y el canario con nonce **atribuye**
109sin ambigüedad (`AAAA=1 BBBB=1`, cero cruces). Análisis en `docs/16-harkaq-jaula.md` §3.5.
110
111### Los tres rastrillos de este banco, para el próximo que lo toque
112
1131. **No compilar bajo `/tmp`**: el sandbox hace `--tmpfs /tmp` y tapa el binario.
1142. **El canario necesita un punto de montaje escribible.** Con `--ro-bind / /`, bwrap no puede
115   crear `/harkaq-canary-X` en la raíz de sólo lectura (el sandbox real usa `--tmp-overlay /` y no
116   tendría el problema). Va bajo `/tmp`, y por eso `/tmp` **no** entra en la clausura de la víctima.
1173. **Root + `--unshare-all` no atraviesa un home `drwx------`.** bwrap mapea sólo uid 0→0; los
118   ficheros de uid 1000 quedan sin mapear y `CAP_DAC_OVERRIDE` en un userns sólo vale sobre uids
119   **mapeados**. De ahí `drop_privs()`.
120
121### Por qué también aborta con código 4
122
123Mismo gate que `q1-audit`, más uno: **si alguna víctima no sale con status 0, aborta** en vez de
124contar registros. La corrida que lo motivó imprimió *"NADA cruzó ⇒ harkaq-audit no puede vivir en
125el host: replantear"* cuando bwrap ni siquiera había podido ejecutar el binario. Una conclusión
126arquitectónica falsa, a partir de cero estímulo.
127
128Van tres veces en una sola sesión (`NLM_F_ACK`, el redirect a `/dev/null`, el exec) que un cero
129resultó ser el instrumento y no el kernel. Un veredicto que no verifica su propio estímulo es el
130falso `Hermetico` de D9, pero del lado del banco.
131
132## `harkaq-policy.sh` + `q2-runtime-base.sh` — la clausura y el runtime base
133
134`harkaq-policy.sh <dir-dep>...` deriva la política de la clausura (D1: no se escribe, se deriva).
135Enumera **fichero a fichero** —no por directorio— porque el sandbox funde las deps y Alpine en el
136mismo `/usr` (§4.1). Emite `list` de los directorios para que pkgconf/configure puedan escanear
137sin poder leer lo no declarado.
138
139`q2-runtime-base.sh` responde Q2 midiendo, no adivinando: corre un build real en el sandbox real
140con `política = clausura` y deja que las denegaciones nombren el runtime base. Se itera con
141`BASE_EXTRA` (una línea por regla), y **cada línea que se añade ahí debe venir de una denegación
142que el kernel denunció, nunca de una corazonada** — si se define de más, la política concede
143Alpine entero y la evidencia deja de valer.
144
145```sh
146export BASE_EXTRA='ro /bin/sh
147ro /bin/busybox
148ro /lib/ld-musl-x86_64.so.1'
149HARKAQ_TIMEOUT=25 scripts/harkaq/q2-runtime-base.sh
150```
151
152Resultado (2026-07-15, contra la dep `zlib` del store):
153
154```
155estado: Impuro | canario: True | contador kernel: 3
156    fs.read_file /usr/bin/env
157    fs.read_file /usr/lib/libz.so.1.3.2      ← ¡la zlib de ALPINE, no la dep declarada!
158```
159
160### Dos rastrillos más, aprendidos acá
161
1621. **El canario no puede depender de un binario.** Con `cat $CANARY` moría en `/bin/cat` (applet
163   de busybox fuera de la clausura) y el probe no probaba nada. Ahora usa sólo builtins:
164   `read _ < $CANARY || true`.
1652. **El canario no puede vivir en `/tmp`.** La política concede `rw /tmp` (es el HOME del build),
166   así que un canario ahí cae DENTRO de la clausura, se lee sin problema y no deniega nada ⇒
167   `SinEvidencia` eterno. Va en la raíz, donde la política no alcanza por construcción.
168
169El segundo lo cazó **D9 mismo**: el lector se negó a certificar (`SinEvidencia`) en vez de decir
170`Hermetico`. El canario funcionando como se diseñó, sobre un bug de quien lo diseñó.
171
172### Q2 resuelta: el runtime base son 5 paths (2026-07-15)
173
174`MODE=base` corre **sin ninguna dep declarada**: sin clausura que pueda explicarlas, toda
175denegación es runtime base por definición. Eso aísla la respuesta sin juicio de valor.
176
177```sh
178export BASE_EXTRA='ro /bin/sh
179ro /bin/busybox
180ro /lib/ld-musl-x86_64.so.1
181ro /usr/bin/env
182ro /usr/lib/os-release
183rw /dev/null
184ro /dev/urandom'
185MODE=base scripts/harkaq/q2-runtime-base.sh   # rc=0, sólo queda /usr/bin/gcc (esperada)
186MODE=zlib scripts/harkaq/q2-runtime-base.sh   # Impuro: [/usr/lib/libz.so.1.3.2] — deuda pura
187```
188
189Tres categorías, todas medidas (detalle en `docs/16-harkaq-jaula.md` §4.2):
190
191- **Contrato**: `/src /out /tmp /dev/null(rw) /dev/urandom /proc /opt/zig` — los monta bwrap, no
192  son Alpine.
193- **Runtime base Alpine**: `/bin/sh /bin/busybox /lib/ld-musl /usr/bin/env /usr/lib/os-release`.
194  Cinco. El resto de Alpine es deuda genuina.
195- **Denegación esperada**: `/usr/bin/gcc` — `zig cc` lo sondea y el build sale `rc=0` igual.
196  Concederla dejaría a zig usar el gcc de Alpine por detrás. **Se deniega y se clasifica** (D3).
197
198Ojo con dos: `/dev/null` es destino de **escritura** (`rw`, no `ro` — con `ro` quedan
199`fs.write_file` colgando), y el piso duro es `/bin/sh`→`busybox`→`ld-musl`: sin eso ni el canario
200corre y no hay diagnóstico, sólo `SinEvidencia`.
201
202### ¿Aguantan los 5 paths en otra forma de build? No — pero converge (§4.3)
203
204`MODE=configure` corre un `configure` de autotools **real** (`work/sources/libgpg-error-*`,
205override con `Q2_SRC`). Iterando con el mismo método:
206
207| Ronda | Deuda restante (paths únicos) |
208|---|---|
209| 1 | `/bin/bash`, `/bin/coreutils` |
210| 2 | `libacl`, `libattr`, `libcrypto`, `libreadline`, `libutmps` |
211| 3 | `libncursesw`, `libskarnet` |
212| 4 | `/usr/bin/c89`, `/usr/bin/c99`, `/usr/bin/ldd`, `/usr/bin/make` |
213
214El runtime base es **por forma de build** (~16 entradas para autotools, no 5), pero **converge en
2153 rondas y se queda chico** ⇒ la métrica de <5% de la Fase 2 sigue siendo plausible.
216
217Lo importante: **el runtime base no es una lista de binarios, es su cierre de `.so`** (bash
218arrastra libreadline+libncursesw; coreutils arrastra libacl+libattr). Es computable con `ldd`, no
219adivinable — `harkaq-policy` debería derivarlo igual que deriva la clausura de las deps.
220
221Y el residuo es todo señal: `c89`/`c99`/`ldd` son sondas de compilador de Alpine (→ esperadas,
222como `gcc`), y `/usr/bin/make` es una decisión de diseño real — hoy los builds usan el `make` de
223Alpine sin declararlo. **Es la misma lista que reemplazan los swaps del `selfhost-verify`**,
224descubierta por otro camino.
225
226### El clasificador va FUERA del lector
227
228`harkaq-verdict.py <verdict-crudo> <politica> [--human]`. El lector tiene `CAP_AUDIT_READ`;
229clasificar es política, no privilegio. Mantenerlo tonto es el argumento de Q1c, y de yapa se
230itera la clasificación sin recompilar el binario capabilitado (sin perder el `setcap`).
231
232Las expectativas viajan en la política como `# expect <path>` — una sola fuente de verdad, y
233`harkaq-exec` las ignora como comentario. `SinEvidencia` manda sobre todo: si el lector no es
234confiable no se clasifica nada, porque reinterpretarlo sería el falso `Hermetico` que el canario
235existe para impedir.
236
237### `harkaq-base-closure.py` — el runtime base, derivado
238
239```sh
240scripts/harkaq/harkaq-base-closure.py .dev-fs/alpine /bin/sh /bin/busybox /bin/bash /bin/coreutils /usr/bin/env
241```
242
243Emite `ro <path>` para cada binario **y todo su cierre transitivo de `.so`**, en rutas del
244sandbox. No usa `ldd` (resolvería contra el host): lee los `DT_NEEDED` del ELF y resuelve dentro
245del rootfs por las rutas de musl. Emite symlink **y** destino — el kernel denuncia el fichero real
246(`libz.so.1.3.2`) pero el build abre por el nombre corto (`libz.so.1`).
247
248**Validación:** reproduce exactamente las 7 librerías que las rondas 2 y 3 de §4.3 habían
249descubierto a mano, en una pasada, y además caza los symlinks y `libc.musl-x86_64.so.1` que se
250habían escapado.
251
252### El diagnóstico sobre un `configure` real (§4.4)
253
254Con el entorno del sandbox replicado (`CC="zig cc -mcpu=baseline"`, `AR`, `SOURCE_DATE_EPOCH`,
255`LC_ALL=C`), 205 denegaciones del kernel se clasifican en:
256
257```
258esperadas (170): /usr/bin/gcc, /usr/bin/ldd
259DEUDA (34) en 8 paths:
260    /usr/bin/{ld,nm,objdump,strip}   ← binutils de ALPINE
261    /usr/bin/{make,getconf}
262    /usr/lib/gcc/x86_64-alpine-linux-musl
263    /opt                             ← bug de política: falta `list` en los ancestros
264```
265
266Sin clasificar son 205 líneas planas; clasificado, 8 paths accionables. **Regla que salió de acá:
267todo directorio concedido necesita `list` en sus ancestros**, o el escaneo del padre es un falso
268positivo.
269
270## Fase 2 — el barrido
271
272`fase2-barrido.sh <receta.toml>...` + `harkaq-suggest.py`. La métrica del SDD (<5% de recetas
273necesitan excepción) medía otra cosa: una deuda que el store YA PROVEE no es una excepción, es
274una línea en `[deps]`. Sólo la deuda **irreducible** cuenta.
275
276```sh
277scripts/harkaq/harkaq-base-closure.py .dev-fs/alpine /bin/sh /bin/busybox /bin/bash /bin/coreutils /usr/bin/env > ~/.cache/harkaq/base.policy
278printf "ro /usr/lib/os-release\n# expect /usr/bin/gcc\n# expect /usr/bin/ldd\n" >> ~/.cache/harkaq/base.policy
279scripts/harkaq/fase2-barrido.sh recipes/zlib.toml recipes/brotli.toml ...
280```
281
282Primer barrido (6 recetas C, fuentes cacheadas): **5 con sólo deuda declarable —y las 5 por el
283MISMO path, `/usr/bin/make`—** y 1 irreducible (brotli: `libstdc++`/`libgcc_s`, el runtime C++ de
284Alpine = la frontera que *matar gcc* ya tenía identificada). No hay cola larga de excepciones,
285que era el riesgo de muerte del §7.
286
287**Gotcha del barrido:** copiar la receta a otro directorio rompe la resolución de `deps.build`
288(son relativas al dir de la receta) ⇒ se descartaban en silencio justo las recetas CON deps. La
289copia va al lado del original.
290
291## El bucle cerrado (§4.7)
292
293Diagnosticar no vale nada si no se puede accionar. Sobre `recipes/zlib.toml`, cada paso guiado
294SÓLO por lo que dijo harkaq:
295
296| Paso | Veredicto | harkaq dijo | Acción |
297|---|---|---|---|
298| zlib tal cual | `Impuro` | `/usr/bin/make` → declarar dep: make | `[deps] build=["make"]` |
299| + make | `Impuro` | `/usr/bin/ranlib` → declarar dep: binutils | `build=["make","binutils"]` |
300| + binutils | `Impuro` | `liblto_plugin.so` → irreducible | clasificar como esperada |
301| final | **`Hermetico` ×3** | — | `b3:adc5c251…` sellado |
302
303Cada capa destapa la siguiente y **todas convergen en el gcc de Alpine**. El último hallazgo no se
304encuentra a mano: **los binutils DE HAMMER cargan el plugin LTO del gcc DE ALPINE** — un agujero
305de soberanía dentro de un artefacto que hammer construye, no un fallo de la receta.
306
307**El hash del artefacto es idéntico antes y después de clasificar** (`b3:adc5c251…` las dos veces):
308clasificar cambia el veredicto, no el build. La evidencia es comportamiento, no identidad.
309
310**NO modificar `recipes/zlib.toml`** para probar esto: cambiaría su hash e invalidaría el
311artefacto sellado y todo lo aguas abajo. Se prueba en una copia `recipes/.harkaq-*.toml` (al lado
312del original, o se rompe la resolución de deps).