feat(cybersecurity): auto-commit con 10 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bash/functions/cybersecurity/start_mitm_capture.md

@@ -0,0 +1,80 @@
+---
+name: start_mitm_capture
+kind: function
+lang: bash
+domain: cybersecurity
+version: "1.0.0"
+purity: impure
+signature: "start_mitm_capture([--port N] [--out DIR] [--rotate-min N] [--addon PATH] [--mitmdump BIN] [--log PATH]) -> string"
+description: "Arranca mitmdump en modo headless en segundo plano como proxy de interceptación liviano, con rotación de capturas cada N minutos vía el addon rotate_capture_flows.py del registry. El proceso sobrevive al cierre de la shell (setsid). Emite JSON con PID, puerto, directorio de salida y ruta del log."
+tags: [bash, cybersecurity, mitmproxy, proxy, capture, web-proxy, network, interception, mitmdump]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "--port N"
+    desc: "Puerto TCP donde mitmdump escucha conexiones del cliente proxy. Default: 8080."
+  - name: "--out DIR"
+    desc: "Directorio donde se guardan los archivos .mitm rotados. Se crea automáticamente si no existe. Default: $HOME/captures."
+  - name: "--rotate-min N"
+    desc: "Minutos de duración de cada archivo de captura antes de rotar. Default: 20."
+  - name: "--addon PATH"
+    desc: "Ruta al addon Python de rotación (rotate_capture_flows.py). Default: derivado desde FN_REGISTRY_ROOT o desde la ubicación del propio script (3 niveles arriba)."
+  - name: "--mitmdump BIN"
+    desc: "Ruta al binario mitmdump. Default: autodetectado con command -v mitmdump, luego $HOME/.local/bin/mitmdump. Si no se encuentra, falla con instrucción de instalación."
+  - name: "--log PATH"
+    desc: "Archivo de log del proceso mitmdump. Default: <out>/mitmdump.log."
+output: "JSON en stdout: {\"pid\": <pid>, \"port\": <port>, \"out_dir\": \"<dir>\", \"rotate_min\": <n>, \"log\": \"<log>\"}. Exit 1 en error (binario no encontrado, addon ausente, proceso muerto al arrancar)."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/cybersecurity/start_mitm_capture.sh"
+---
+
+## Ejemplo
+
+```bash
+source bash/functions/cybersecurity/start_mitm_capture.sh
+
+# Arranque con defaults (puerto 8080, capturas en ~/captures, rotación cada 20 min)
+start_mitm_capture --port 8080 --out /home/enmanuel/captures --rotate-min 20
+
+# Salida esperada:
+# {"pid": 123456, "port": 8080, "out_dir": "/home/enmanuel/captures", "rotate_min": 20, "log": "/home/enmanuel/captures/mitmdump.log"}
+
+# Puerto alternativo y rotación más frecuente
+start_mitm_capture --port 9090 --out /tmp/mitm_session --rotate-min 5
+
+# Pasando addon y binario explícitos
+start_mitm_capture \
+  --port 8080 \
+  --out /home/enmanuel/captures \
+  --addon /home/enmanuel/fn_registry/python/functions/cybersecurity/rotate_capture_flows.py \
+  --mitmdump /home/enmanuel/.local/bin/mitmdump
+
+# Leer el PID para poder parar el proceso más adelante
+info=$(start_mitm_capture --port 8080 --out /home/enmanuel/captures)
+pid=$(echo "$info" | python3 -c "import sys,json; print(json.load(sys.stdin)['pid'])")
+echo "Proxy corriendo con PID $pid"
+# Para parar: kill "$pid"
+```
+
+## Cuando usarla
+
+Cuando necesites un proxy de interceptación pasivo siempre activo en segundo plano que capture y rote el tráfico HTTP/HTTPS de forma continua sin supervisión manual. Úsala antes de lanzar pruebas de integración, sesiones de auditoría web o scraping supervisado donde quieras replay o análisis posterior de las capturas `.mitm`.
+
+## Gotchas
+
+- **HTTPS requiere instalar el CA de mitmproxy en el cliente.** El certificado raíz está en `~/.mitmproxy/mitmproxy-ca-cert.pem` tras el primer arranque. En navegadores: importar como CA de confianza. En curl/httpx: `--cacert ~/.mitmproxy/mitmproxy-ca-cert.pem`. En Chrome/Chromium headless: `--ignore-certificate-errors` (solo para pruebas).
+- **El proceso queda en background.** Para pararlo: `kill <pid>` (el PID se devuelve en el JSON) o `port_kill 8080` si tienes la función del registry disponible.
+- **El addon rotate_capture_flows.py debe existir.** La función lo busca en la raíz del registry derivada automáticamente; si el registry está en una ubicación no estándar, pasa `--addon` explícitamente o setea `FN_REGISTRY_ROOT`.
+- **setsid desacopla el proceso de la shell.** Si cierras la terminal, mitmdump sigue corriendo. Necesitas matar el PID manualmente o via systemd/supervisor si quieres ciclo de vida gestionado.
+- **El log crece sin límite.** El log de mitmdump no rota; solo rotan los archivos `.mitm` de capturas. Monitoriza el tamaño de `<out>/mitmdump.log` en sesiones largas.
+- **Solo funciona con mitmdump >= 9.x** (API de addons `--set` con parámetros por nombre). Versiones anteriores usan sintaxis distinta.
+
+## Notas
+
+La derivación de la raíz del registry cuando `FN_REGISTRY_ROOT` no está seteado asciende 3 niveles desde `bash/functions/cybersecurity/` hasta la raíz usando `dirname "${BASH_SOURCE[0]}"`. Esto funciona siempre que el script se sourcee desde su ubicación original en el registry.