feat: scaffold inicial de web_proxy (proxy de interceptacion liviano)
This commit is contained in:
agent
@@ -0,0 +1,161 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user