---
name: rotate_capture_flows
kind: function
lang: py
domain: cybersecurity
version: "1.1.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 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."
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."
  - name: exclude_hosts
    desc: "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: max_total_mb
    desc: "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: max_age_days
    desc: "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)."
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. Las capturas viejas se purgan automaticamente segun max_age_days y max_total_mb."
---

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