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.1.0	impure	class Rotator — mitmproxy addon loaded via mitmdump -s	Addon de mitmproxy que rota el archivo de captura de flows cada N minutos y aplica retencion (borra capturas viejas por edad y por tamaño total). 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. Al rotar, purga las capturas que superen max_age_days o que hagan que el directorio supere max_total_mb.	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. name desc exclude_hosts Hosts o host:port separados por coma que nunca se graban (ej. la propia UI del proxy). Se pasa via --set exclude_hosts=127.0.0.1:8081,localhost:8081. Default: vacio. name desc max_total_mb Tope de tamaño total del directorio de capturas en MB. Al rotar, borra las .mitm mas antiguas hasta bajar del limite. Se pasa via --set max_total_mb=2048. Default: 0 (sin limite). name desc max_age_days Antiguedad maxima de una captura en dias. Al rotar, borra las .mitm mas viejas que este valor. Se pasa via --set max_age_days=7. Default: 0 (sin limite).	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. Las capturas viejas se purgan automaticamente segun max_age_days y max_total_mb.

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.
• Retencion: la purga (max_total_mb, max_age_days) solo se ejecuta al rotar, es decir, dentro de _roll. Si el trafico cesa, no hay rotacion y por tanto no hay purga hasta el siguiente flujo. El archivo activo nunca es candidato a borrado, asi que el directorio puede quedar hasta ~un archivo por encima del tope max_total_mb entre rotaciones. A escala normal (ventanas de 20 min, tope en GB) la desviacion es despreciable. Ambos topes son independientes y se aplican a la vez (lo que se cumpla primero); 0 desactiva cada uno por separado.
• El cap max_total_mb borra los archivos mas antiguos primero (por mtime), no por nombre. Verificado en test: con tope de 1 MB y 8 dias, purga por tamaño y por edad de forma independiente.

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.

Capability growth log

• v1.1.0 (2026-06-02) — anade retencion: opciones max_total_mb y max_age_days que purgan capturas viejas al rotar (por tamaño total del directorio y por antiguedad). Evita llenar el disco en captura continua. Tambien anade exclude_hosts para no grabar la propia UI del proxy.