---
name: rotate_capture_flows
kind: function
lang: py
domain: cybersecurity
version: "1.0.0"
purity: impure
signature: "class Rotator — mitmproxy addon loaded via mitmdump -s"
description: "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."
tags: [mitmproxy, capture, rotate, proxy, web-proxy, cybersecurity, flows, traffic]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["mitmproxy.io", "mitmproxy.ctx", "os", "time", "datetime"]
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/cybersecurity/rotate_capture_flows.py"
params:
  - name: rotate_min
    desc: "Minutos por archivo antes de rotar. Se pasa via --set rotate_min=N al invocar mitmdump. Default: 20."
  - name: capture_dir
    desc: "Directorio donde se escriben los archivos .mitm rotados. Se pasa via --set capture_dir=/ruta. Default: directorio de trabajo actual."
output: "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

```bash
# 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.