web_proxy/app.md

---
name: web_proxy
lang: bash
domain: cybersecurity
version: 0.1.0
description: "Proxy de interceptacion HTTP/HTTPS liviano y siempre activo (mitmproxy) para capturar todo el trafico de un navegador con rotacion temporal de capturas, alternativa ligera a ZAP/Burp."
tags: [service, web-proxy, mitmproxy, proxy, capture, cybersecurity, chromium]
icon:
  phosphor: "shield-check"
  accent: "#7c3aed"
uses_functions:
  - start_mitm_capture_bash_cybersecurity
  - query_mitm_flows_bash_cybersecurity
  - rotate_capture_flows_py_cybersecurity
  - launch_chromium_proxy_bash_browser
  - port_kill_bash_infra
uses_types: []
framework: ""
entry_point: "web_proxy"
dir_path: "apps/web_proxy"
repo_url: ""
service:
  port: 8080
  health_endpoint: null
  health_timeout_s: 3
  systemd_unit: web_proxy.service
  systemd_scope: user
  restart_policy: always
  runtime: systemd-user
  pc_targets:
    - home-wsl
  is_local_only: true
e2e_checks:
  - id: syntax
    cmd: "bash -n web_proxy"
    timeout_s: 10
  - id: help
    cmd: "./web_proxy help"
    expect_stdout_contains: "proxy de interceptacion"
    timeout_s: 10
  - id: capture_roundtrip
    cmd: "bash tests/e2e_capture.sh"
    expect_stdout_contains: "CAPTURE_OK"
    timeout_s: 40
---

# web_proxy

Proxy de interceptacion HTTP/HTTPS liviano y siempre activo, pensado como
alternativa ligera a OWASP ZAP y Burp Suite. Construido sobre `mitmproxy`
(footprint de decenas de MB frente a la JVM de ZAP/Burp) y compuesto a partir
de funciones del registry `fn_registry`.

## Que hace

- Levanta un proxy local (`mitmdump` headless) que registra **todo** el trafico
  HTTP/HTTPS que pasa por el.
- **Rota las capturas** en archivos `.mitm` por ventanas de tiempo configurables
  (default 20 minutos), de modo que puedas consultar el trafico de cada tramo
  por separado.
- Corre **siempre activo** como servicio `systemd --user` con `Restart=always`,
  o de forma manual con `start`/`stop`.
- Lanza un **Chromium proxeado** en un perfil aislado para no contaminar tu
  navegacion normal.
- Permite **consultar** las capturas guardadas: volcado filtrado, exportacion a
  HAR, o inspeccion visual en `mitmweb`.

## Ejemplo

```bash
cd apps/web_proxy

# Servicio siempre activo en el puerto 8080, capturas en ~/captures, rotando cada 20 min
./web_proxy install-service --port 8080 --out ~/captures --rotate-min 20

# Confiar en el CA de mitmproxy para que HTTPS no rompa
./web_proxy ca

# Navegar con todo el trafico capturado (Chromium en perfil aislado)
./web_proxy browser --url https://example.com

# Consultar la ultima ventana de captura
./web_proxy query "~m POST"          # solo peticiones POST
./web_proxy query "~c 500" --all     # respuestas 5xx en todas las capturas
./web_proxy har ~/captures/sesion.har

# Inspeccion visual en el navegador
./web_proxy inspect

# Estado y logs
./web_proxy status
./web_proxy logs
```

Modo manual (sin servicio):

```bash
./web_proxy start --port 8080 --out ~/captures --rotate-min 20
./web_proxy browser
./web_proxy query "~d api.github.com"
./web_proxy stop
```

## Cuando usarla

Cuando quieras registrar de forma continua y liviana todo lo que hace un
navegador (debug de APIs, auditoria de trafico, inspeccion de requests de una
SPA) sin arrancar la maquinaria pesada de ZAP o Burp, y poder volver a consultar
sesiones pasadas troceadas por ventanas de tiempo.

## Como consultar las capturas

Las capturas son archivos `.mitm` en el directorio de salida (`~/captures` por
defecto), con nombre `traffic-YYYYmmdd-HHMMSS.mitm`, uno por ventana de rotacion.

| Forma | Comando |
|---|---|
| Volcado filtrado (CLI) | `./web_proxy query "~m POST"` |
| Volcado de todas las ventanas | `./web_proxy query "~u /api" --all` |
| Exportar a HAR | `./web_proxy har salida.har` |
| Inspeccion visual (UI web) | `./web_proxy inspect [archivo.mitm]` |
| Directo con mitmproxy | `mitmproxy -r ~/captures/traffic-*.mitm` |

Sintaxis de filtros de mitmproxy: `~u` URL, `~d` dominio, `~m` metodo, `~c`
codigo de estado, `~bq`/`~bs` cuerpo de peticion/respuesta. Combinables con
`&` (y), `|` (o), `!` (no).

## Gotchas

- **HTTPS**: requiere confiar en el CA de mitmproxy. Ejecuta `./web_proxy ca`
  para las instrucciones. El navegador que lanza `./web_proxy browser` usa
  `--ignore-certificate-errors` si no instalas el CA, lo cual es comodo pero
  menos seguro (vale para uso local de captura, no para navegacion sensible).
- **Durabilidad**: el addon de rotacion hace `flush()` tras cada flujo, asi que
  las capturas sobreviven a un `kill -9` o un corte abrupto del proceso.
- **Rotacion por trafico**: la rotacion ocurre al recibir un flujo; si no hay
  trafico durante la ventana, el archivo no rota hasta el siguiente request.
- **Persistencia tras logout**: el servicio `systemd --user` para al cerrar
  sesion salvo que actives linger con `./web_proxy install-service --linger`.
- **Conflicto de puerto**: `start` y el servicio no pueden coexistir en el mismo
  puerto. `install-service` para el proxy manual automaticamente antes de
  arrancar el servicio.
- **Stop fiable**: el `stop` mata por PID guardado en el pidfile (no depende de
  `lsof`/`port_kill`, que en este entorno no siempre detecta el listener a
  tiempo).

## Arquitectura

Orquesta funciones del registry (no reimplementa logica reutilizable):

| Funcion del registry | Rol |
|---|---|
| `start_mitm_capture_bash_cybersecurity` | Arranca `mitmdump` headless con rotacion |
| `rotate_capture_flows_py_cybersecurity` | Addon de mitmproxy que trocea las capturas |
| `query_mitm_flows_bash_cybersecurity` | Consulta capturas guardadas (volcado / HAR) |
| `launch_chromium_proxy_bash_browser` | Lanza Chromium proxeado en perfil aislado |
| `port_kill_bash_infra` | Limpieza de puertos ocupados |

El CLI `web_proxy` aporta solo la logica especifica de la app: gestion del
pidfile, configuracion persistente, generacion del unit `systemd --user` y la
interfaz de subcomandos.