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":"/home/sergio/hammer/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ñó.