---
name: query_mitm_flows
kind: function
lang: bash
domain: cybersecurity
version: "1.0.0"
purity: impure
signature: "query_mitm_flows(file_or_glob: string, filter?: string, har?: string, mitmdump?: string) -> void"
description: "Consulta capturas .mitm guardadas con mitmproxy: vuelca los flujos que coinciden con un filtro de mitmproxy a stdout, o exporta la captura a HAR. Acepta uno o varios archivos .mitm (incluyendo globs expandidos por el shell). Autodetecta mitmdump en PATH y $HOME/.local/bin."
tags: [bash, cybersecurity, mitmproxy, web-proxy, query, har, capture, traffic, proxy, network]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: file_or_glob
    desc: "Ruta a un archivo .mitm o glob expandido por el shell (ej. ~/captures/traffic-*.mitm). Acepta múltiples archivos como argumentos posicionales."
  - name: filter
    desc: "Expresión de filtro mitmproxy (ej. '~m POST & ~u /api', '~c 500', '~d example.com'). Si se omite, vuelca todos los flujos."
  - name: har
    desc: "Ruta de salida para exportar en formato HAR (--set hardump=OUT). Si se omite, el volcado va a stdout."
  - name: mitmdump
    desc: "Ruta al binario mitmdump. Si se omite, autodetecta en PATH y luego en $HOME/.local/bin/mitmdump."
output: "Vuelca los flujos capturados a stdout (modo default) o exporta a un archivo HAR (con --har); informa la ruta de exportación en stderr al terminar. Exit code de mitmdump propagado."
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/cybersecurity/query_mitm_flows.sh"
---

## Ejemplo

```bash
source bash/functions/cybersecurity/query_mitm_flows.sh

# Volcar todos los flujos de una captura
query_mitm_flows ~/captures/traffic-20260602.mitm

# Filtrar solo peticiones POST a /api (glob expandido por el shell)
query_mitm_flows ~/captures/traffic-20260602-*.mitm --filter "~m POST & ~u /api"

# Ver solo respuestas con código 500
query_mitm_flows session.mitm --filter "~c 500"

# Exportar a HAR para abrir en el Network tab del browser DevTools
query_mitm_flows ~/captures/traffic-20260602.mitm --har salida.har

# Exportar a HAR con filtro aplicado
query_mitm_flows session.mitm --filter "~d example.com" --har example_flows.har

# Especificar mitmdump manualmente (ej. en un venv de Python)
query_mitm_flows session.mitm --mitmdump ~/.venv/bin/mitmdump --filter "~m POST"
```

## Cuando usarla

Cuando hayas capturado tráfico HTTP/HTTPS con mitmproxy y necesites consultarlo después sin abrir una interfaz interactiva: filtrar flujos específicos por método, dominio, URL o código de respuesta, o exportar la captura a HAR para análisis posterior en herramientas externas (browser DevTools, Insomnia, Postman). Úsala desde scripts de análisis automatizados o pipelines de revisión de seguridad.

## Gotchas

**Sintaxis de filtros mitmproxy** — los filtros se pasan como expresión entre comillas:

| Operador | Significado | Ejemplo |
|---|---|---|
| `~u <regex>` | URL (path + query) | `~u /api/login` |
| `~d <regex>` | Dominio del host | `~d example.com` |
| `~m <método>` | Método HTTP | `~m POST` |
| `~c <código>` | Código de respuesta | `~c 500` |
| `~bq <regex>` | Body del request | `~bq password` |
| `~bs <regex>` | Body del response | `~bs token` |
| `~t <regex>` | Content-Type | `~t application/json` |
| `~s` | Solo respuestas | `~s` |
| `~q` | Solo requests | `~q` |

Combinar con `&` (AND), `|` (OR), `!` (NOT). Ejemplos:
- `"~m POST & ~u /api"` — POST a rutas /api
- `"~c 500 | ~c 503"` — errores de servidor
- `"~d example.com & !~u /static"` — todo de example.com excepto estáticos

**Globs:** el shell expande el glob *antes* de pasar los argumentos a la función. Pasar `~/captures/traffic-*.mitm` sin comillas para que el shell expanda; con comillas el glob llega literalmente y fallará si el archivo no existe.

**Inspección interactiva:** para navegar los flujos con UI, usar `mitmweb -r <file>` (web) o `mitmproxy -r <file>` (TUI), no esta función. Esta función es para consulta programática y scripting.

**Múltiples archivos con `-r`:** mitmdump acepta varios flags `-r` y concatena los flujos en orden. El filtro se aplica sobre el conjunto completo.

**HAR y filtros juntos:** al usar `--har` con `--filter`, solo los flujos que pasen el filtro se exportan al HAR.
