fn_registry/python/functions/cybersecurity/rotate_capture_flows.md

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

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
rotate_capture_flows	function	py	cybersecurity	1.0.0	impure	class Rotator — mitmproxy addon loaded via mitmdump -s	Addon de mitmproxy que rota el archivo de captura de flows cada N minutos. Crea archivos .mitm con timestamp en el nombre (traffic-YYYYmmdd-HHMMSS.mitm) y abre uno nuevo cuando vence el intervalo de rotacion. La rotacion ocurre en el evento response, por lo que solo sucede cuando hay trafico activo.	mitmproxy capture rotate proxy web-proxy cybersecurity flows traffic				false	error_go_core	mitmproxy.io mitmproxy.ctx os time datetime	false			python/functions/cybersecurity/rotate_capture_flows.py	name desc rotate_min Minutos por archivo antes de rotar. Se pasa via --set rotate_min=N al invocar mitmdump. Default: 20. name desc capture_dir Directorio donde se escriben los archivos .mitm rotados. Se pasa via --set capture_dir=/ruta. Default: directorio de trabajo actual.	Archivos .mitm con nombre traffic-<YYYYmmdd-HHMMSS>.mitm en capture_dir, cada uno con los flows HTTP capturados durante una ventana de rotate_min minutos.

Ejemplo

# Capturar trafico HTTP/S en ventanas de 20 minutos en ~/captures/
mitmdump \
  -s python/functions/cybersecurity/rotate_capture_flows.py \
  --set rotate_min=20 \
  --set capture_dir=/home/enmanuel/captures \
  --listen-port 8080

# Ventanas de 5 minutos para analisis rapido
mitmdump \
  -s python/functions/cybersecurity/rotate_capture_flows.py \
  --set rotate_min=5 \
  --set capture_dir=/tmp/proxy_session \
  --listen-port 8080

# Leer un archivo capturado con mitmproxy
mitmproxy -r /home/enmanuel/captures/traffic-20260602-143000.mitm

Cuando usarla

Cuando necesites capturar trafico HTTP/S durante periodos largos y quieras trocear las capturas en ventanas de tiempo manejables. Util antes de analizar el comportamiento de red de una aplicacion movil o web durante horas, cuando un unico archivo .mitm de varios GB seria dificil de navegar.

Gotchas

• La rotacion ocurre en el evento response: si no llega ningun flujo completo durante el intervalo, el archivo no rota hasta que llegue el siguiente. El reloj es wall-clock del proceso, no del servidor.
• El archivo anterior se cierra (flush + close) justo antes de abrir el nuevo, por lo que no se pierden flows ya registrados al rotar.
• El addon hace flush() despues de cada flujo registrado. Esto garantiza que la captura sobrevive a una muerte abrupta del proceso (SIGKILL, crash, corte de energia): sin el flush, el FlowWriter bufferiza y el .mitm queda en 0 bytes si el proceso no llega a ejecutar done(). Verificado en smoke test matando con kill -9 a media captura.
• Los flows que no tienen respuesta (timeouts de servidor, errores de conexion antes de recibir headers) no llegan al evento response y por tanto no se escriben en el archivo. Para capturarlos tambien, habria que sobrescribir adicionalmente el hook error(self, flow).
• Requiere mitmproxy >= 10 en el entorno. Instalable con uv tool install mitmproxy.
• El directorio capture_dir se crea automaticamente con os.makedirs(..., exist_ok=True) si no existe.

Notas

El addon usa la API de opciones de mitmproxy 10+ (loader.add_option). En versiones anteriores la API de opciones era distinta. Verificar version con mitmdump --version antes de cargar.