---
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.