fn_registry/bash/functions/cybersecurity/start_mitm_capture.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
start_mitm_capture	function	bash	cybersecurity	1.0.0	impure	start_mitm_capture([--port N] [--out DIR] [--rotate-min N] [--addon PATH] [--mitmdump BIN] [--log PATH]) -> string	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.	bash cybersecurity mitmproxy proxy capture web-proxy network interception mitmdump				false	error_go_core		name desc --port N Puerto TCP donde mitmdump escucha conexiones del cliente proxy. Default: 8080. name desc --out DIR Directorio donde se guardan los archivos .mitm rotados. Se crea automáticamente si no existe. Default: $HOME/captures. name desc --rotate-min N Minutos de duración de cada archivo de captura antes de rotar. Default: 20. name desc --addon PATH 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 desc --mitmdump BIN 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 desc --log PATH Archivo de log del proceso mitmdump. Default: <out>/mitmdump.log.	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).	false			bash/functions/cybersecurity/start_mitm_capture.sh

Ejemplo

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.