77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
## Flow replay: guardar un flujo web como función reproducible
|
|
|
|
Cuando una acción web se hace **más de una vez** (login en un panel, reiniciar un servidor
|
|
desde su consola, rellenar un formulario recurrente, descargar un export), deja de hacerse a
|
|
mano: se **graba una vez y se promueve a función del registry**. Es la doctrina del issue 0087
|
|
aplicada a la navegación — el registry crece convirtiendo secuencias repetidas en operaciones
|
|
de un solo paso, no inflando funciones existentes.
|
|
|
|
Grupo de capacidad: `flow-replay`. Página madre: `docs/capabilities/flow-replay.md`. Graba con
|
|
el grupo `web-proxy`; destila y reproduce con `flow-replay`.
|
|
|
|
### El patrón: grabar → destilar → reproducir
|
|
|
|
1. **Grabar** (una vez, con browser + proxy): `web_proxy` ON, haces la acción a mano,
|
|
exportas el tramo a HAR (`query_mitm_flows --har`).
|
|
2. **Destilar**: `har_filter_flows_py_cybersecurity` (quita ruido) →
|
|
`har_extract_calls_py_cybersecurity` (call specs reproducibles).
|
|
3. **Reproducir**, en esta jerarquía de preferencia (de barato a caro):
|
|
|
|
| Nivel | Mecanismo | Cuándo |
|
|
|---|---|---|
|
|
| **1 — HTTP puro** | `http_replay_sequence_py_infra` | **Por defecto.** Rápido, headless, scriptable. La mayoría de paneles admin funcionan con cookie de sesión + requests. |
|
|
| **2 — headless chromium** | action recipe (reutiliza `cdp_extract_recipe` + `cdp_save_storage_state`) | Token dinámico firmado en cliente, challenge JS obligatorio, WAF con fingerprint. |
|
|
| **3 — chromium visible + humanizado** | `cdp_click_xy_human`, `cdp_move_mouse_human` | Headless detectado/bloqueado. Último recurso. |
|
|
|
|
**Empieza SIEMPRE por el Nivel 1.** Solo baja de nivel cuando el anterior demuestre no
|
|
reproducir el efecto. Construir el runner de Nivel 2/3 por adelantado, sin un caso que lo
|
|
exija, es especular (KISS): se monta cuando un flujo real falle en HTTP puro.
|
|
|
|
### Flujo de autoría (cómo guardar una función-acción nueva)
|
|
|
|
1. Grabar el flujo y exportar el HAR del tramo.
|
|
2. `har_filter_flows` + `har_extract_calls` → boceto de la secuencia. El agente **lee** el
|
|
HAR (es texto) e identifica los 2-4 requests que producen el efecto (auth + acción +
|
|
confirmación), descartando el resto.
|
|
3. Parametrizar: marcar los valores variables (ids, tokens) como `{{param}}`; definir las
|
|
reglas `extract` para los tokens que una respuesta genera y otro request consume.
|
|
4. Validar el replay con `http_replay_sequence`. Si reproduce el efecto sin navegador → Nivel 1.
|
|
5. **Promover a función del registry**: delegar a `fn-constructor` una función-acción nombrada
|
|
con verbo (`reboot_vps_server_<panel>`, `login_<panel>`, `export_<panel>_report`) que
|
|
internamente llama a `http_replay_sequence` con su secuencia fija, recibe los parámetros
|
|
del caller y resuelve los secretos desde `pass`/vault. Tag de grupo `flow-replay` + el
|
|
dominio que toque (infra, cybersecurity, …). `fn index` + usar en el mismo turno.
|
|
|
|
### Reglas duras de seguridad
|
|
|
|
- **El HAR es un secreto**: lleva cookies/tokens en crudo. Gitignored, no subir a Gitea, no
|
|
indexar, borrar tras destilar. El output de `har_extract_calls` también, hasta sustituir por
|
|
`{{param}}`.
|
|
- **Secretos a `pass`/vault**, jamás hardcodeados en la función-acción.
|
|
- **Replay con efectos = peligroso.** Una acción destructiva o irreversible (reiniciar, borrar,
|
|
pagar, enviar) NUNCA se reproduce a ciegas: la función-acción exige confirmación o un flag
|
|
explícito (`confirm=True` / `--yes`) antes de disparar.
|
|
- `http_replay_sequence` usa `verify_tls=True` y sigue redirects por defecto; la extracción
|
|
JSON es dot-path simple, no JSONPath completo.
|
|
|
|
### Anti-patrones
|
|
|
|
| Anti-patrón | Por qué es malo | Sustituir por |
|
|
|---|---|---|
|
|
| Repetir el flujo a mano cada vez | No capitaliza; lento; propenso a error | Grabar una vez → función-acción |
|
|
| Reescribir requests inline en un heredoc/app cada vez | Reinvento, sin telemetría | Función-acción que llama `http_replay_sequence` |
|
|
| Empezar por chromium headless "por si acaso" | Más caro y frágil que HTTP puro | Nivel 1 primero, bajar solo si falla |
|
|
| Hardcodear cookie/token del HAR en el código | Secreto filtrado + caduca | `{{param}}` desde `pass`/vault |
|
|
| Commitear el HAR o el output crudo de extract | Filtración de credenciales | Tratar como secreto, gitignored |
|
|
| Replay ciego de un POST destructivo | Daño irreversible | Confirmación / flag explícito |
|
|
|
|
### Relación con otras reglas
|
|
|
|
- [[registry_first]] — buscar/reutilizar antes de escribir; la función-acción se delega a
|
|
`fn-constructor`, no se escribe inline.
|
|
- [[function_growth_and_self_docs]] — el registry crece por promoción de composiciones
|
|
repetidas a funciones one-shot (issue 0087); esto es ese patrón para la navegación.
|
|
- [[registry_calls]] — invocar las funciones del grupo por los patrones canónicos (MCP /
|
|
`fn run` / heredoc que importa).
|
|
- Grupo `web-proxy` (`docs/capabilities/web-proxy.md`) — la captura que alimenta la Fase 0.
|