Initial commit: navegator - Chrome CDP automation for LLMs
Add complete navegator system for stealthy browser automation: - CDP client with WebSocket communication - Browser API with navigation, storage, network, runtime - Stealth flags and anti-detection scripts - Persistent profile support - Examples and comprehensive documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Developer
@@ -0,0 +1,234 @@
|
||||
# Navegator
|
||||
|
||||
Sistema en Go para control de Chrome/Chromium via Chrome DevTools Protocol (CDP) diseñado para automatización sigilosa con LLMs.
|
||||
|
||||
## Características
|
||||
|
||||
- **Control CDP Directo**: Comunicación WebSocket con Chrome sin dependencias de librerías de alto nivel
|
||||
- **Stealth Completo**: Flags optimizadas para evitar detección de automatización
|
||||
- **Perfiles Persistentes**: Gestión de perfiles de usuario con cookies y sesiones reutilizables
|
||||
- **API Completa**: Navegación, interacción, cookies, storage, interceptación de red, evaluación de JavaScript
|
||||
|
||||
## Instalación
|
||||
|
||||
```bash
|
||||
# Clonar repositorio
|
||||
git clone <repo-url>
|
||||
cd navegator
|
||||
|
||||
# Descargar dependencias
|
||||
go mod download
|
||||
|
||||
# Compilar ejemplo básico
|
||||
go build -o navegator-basic examples/basic.go
|
||||
|
||||
# Ejecutar
|
||||
./navegator-basic
|
||||
```
|
||||
|
||||
## Requisitos
|
||||
|
||||
- Go 1.21+
|
||||
- Chrome o Chromium instalado en el sistema
|
||||
- WebSocket support (gorilla/websocket)
|
||||
|
||||
## Uso Básico
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log"
|
||||
"navegator/pkg/browser"
|
||||
)
|
||||
|
||||
func main() {
|
||||
ctx := context.Background()
|
||||
|
||||
// Configuración por defecto
|
||||
config := browser.DefaultConfig()
|
||||
config.ProfileName = "mi-perfil"
|
||||
|
||||
// Lanzar navegador
|
||||
b, err := browser.Launch(ctx, config)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
defer b.Close()
|
||||
|
||||
// Navegar
|
||||
b.Navigate(ctx, "https://example.com", nil)
|
||||
|
||||
// Obtener HTML
|
||||
html, _ := b.GetHTML(ctx, "")
|
||||
log.Println(html)
|
||||
}
|
||||
```
|
||||
|
||||
## Estructura del Proyecto
|
||||
|
||||
```
|
||||
navegator/
|
||||
├── bin/ # Binarios compilados
|
||||
│ ├── screenshot # Capturador de pantalla
|
||||
│ ├── buscar # Motor de búsqueda
|
||||
│ └── navegar # Navegador interactivo
|
||||
├── cmd/ # Código fuente de binarios
|
||||
│ ├── screenshot.go
|
||||
│ ├── buscar.go
|
||||
│ └── navegar.go
|
||||
├── pkg/ # Librerías reutilizables
|
||||
│ ├── cdp/ # Cliente CDP de bajo nivel
|
||||
│ ├── browser/ # API de alto nivel del navegador
|
||||
│ └── stealth/ # Configuración de flags stealth
|
||||
├── scripts/ # Scripts de utilidad
|
||||
│ ├── clonar_perfil.sh # Clonar perfiles para uso paralelo
|
||||
│ ├── demo_paralelo.sh # Demo de múltiples usuarios
|
||||
│ └── ejemplos_perfiles.sh
|
||||
├── docs/ # Documentación
|
||||
│ ├── STEALTH_FLAGS.md # Flags anti-detección
|
||||
│ ├── BINARIOS.md # Guía de binarios
|
||||
│ ├── PERFILES_AVANZADO.md # Gestión de perfiles
|
||||
│ └── TESTING.md # Guía de testing
|
||||
├── e2e/ # Tests E2E
|
||||
│ ├── e2e_test.sh # Tests de binarios
|
||||
│ └── integration_test.sh # Tests de integración
|
||||
├── examples/ # Ejemplos de código
|
||||
│ ├── basic.go
|
||||
│ └── advanced.go
|
||||
├── Makefile # Comandos de build y test
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Capacidades
|
||||
|
||||
### Navegación
|
||||
- Navigate, Reload, GoBack, GoForward
|
||||
- WaitForSelector con timeout
|
||||
- Click, Type, Focus
|
||||
- Screenshot (viewport o página completa)
|
||||
- GetHTML, GetText
|
||||
|
||||
### Cookies & Storage
|
||||
- GetCookies, SetCookie, DeleteCookie, ClearCookies
|
||||
- LocalStorage: Get, Set, Remove, Clear
|
||||
- SessionStorage: Get, Set, Remove, Clear
|
||||
- ClearDataForOrigin
|
||||
|
||||
### Network
|
||||
- EnableNetworkInterception
|
||||
- BlockURLs, BlockResourceTypes
|
||||
- ModifyHeaders
|
||||
- SetExtraHTTPHeaders
|
||||
- SetUserAgent
|
||||
- EmulateNetworkConditions
|
||||
- DisableCache
|
||||
|
||||
### JavaScript
|
||||
- Evaluate (sync)
|
||||
- EvaluateAsync (promises)
|
||||
- CallFunction con argumentos
|
||||
- AddBinding (exponer funciones Go a JS)
|
||||
- OnConsole (monitorear console.log)
|
||||
- WaitForFunction
|
||||
|
||||
## Perfiles Persistentes
|
||||
|
||||
Los perfiles se guardan en `~/.navegator/profiles/<nombre>/`:
|
||||
|
||||
```go
|
||||
config := browser.DefaultConfig()
|
||||
config.ProfileName = "session-1" // Reutilizable entre ejecuciones
|
||||
```
|
||||
|
||||
Cada perfil mantiene:
|
||||
- Cookies
|
||||
- LocalStorage/SessionStorage
|
||||
- Historial
|
||||
- Extensiones
|
||||
- Preferencias
|
||||
|
||||
## Stealth Flags
|
||||
|
||||
Ver `docs/STEALTH_FLAGS.md` para documentación completa de todas las flags.
|
||||
|
||||
Configuración básica:
|
||||
```go
|
||||
config.StealthFlags.Headless = true
|
||||
config.StealthFlags.NoSandbox = false // Solo en Docker
|
||||
config.StealthFlags.UserAgent = "Mozilla/5.0 ..."
|
||||
config.StealthFlags.WindowSize = [2]int{1920, 1080}
|
||||
```
|
||||
|
||||
## Ejemplos
|
||||
|
||||
### Ejemplo 1: Navegación Básica
|
||||
```bash
|
||||
go run examples/basic.go
|
||||
```
|
||||
|
||||
### Ejemplo 2: Capacidades Avanzadas
|
||||
```bash
|
||||
go run examples/advanced.go
|
||||
```
|
||||
|
||||
## Para LLMs
|
||||
|
||||
Este sistema está diseñado para ser controlado por LLMs. La API es:
|
||||
|
||||
1. **Declarativa**: Métodos claros como `Navigate()`, `Click()`, `Type()`
|
||||
2. **Contextual**: Usa selectores CSS estándar
|
||||
3. **Asíncrona**: Manejo de timeouts y esperas automáticas
|
||||
4. **Completa**: Todas las capacidades CDP disponibles
|
||||
|
||||
Ejemplo de prompt para LLM:
|
||||
```
|
||||
Usando el sistema navegator:
|
||||
1. Lanza un navegador con perfil "agent-123"
|
||||
2. Navega a https://example.com
|
||||
3. Obtén el texto del h1
|
||||
4. Toma un screenshot
|
||||
5. Cierra el navegador
|
||||
```
|
||||
|
||||
## Flags Stealth Críticas
|
||||
|
||||
**SIEMPRE ACTIVADAS**:
|
||||
- `--disable-blink-features=AutomationControlled`
|
||||
- `--exclude-switches=enable-automation`
|
||||
- `--user-data-dir=<path>` (perfiles persistentes)
|
||||
|
||||
**CONTEXTUALES**:
|
||||
- `--headless=new` (modo headless moderno)
|
||||
- `--no-sandbox` (SOLO en Docker/containers)
|
||||
- `--disable-web-security` (SOLO en testing)
|
||||
|
||||
## Debugging
|
||||
|
||||
```go
|
||||
config.StealthFlags.EnableLogging = true
|
||||
config.StealthFlags.LogLevel = 0 // INFO
|
||||
```
|
||||
|
||||
URL de debugging disponible en `b.DebugURL()`:
|
||||
```
|
||||
http://127.0.0.1:<port>
|
||||
```
|
||||
|
||||
## Seguridad
|
||||
|
||||
⚠️ **IMPORTANTE**:
|
||||
- `--no-sandbox` es PELIGROSO - solo usar en entornos confiables
|
||||
- `--disable-web-security` desactiva CORS - solo para testing
|
||||
- Los perfiles pueden contener datos sensibles - proteger adecuadamente
|
||||
|
||||
## Licencia
|
||||
|
||||
MIT
|
||||
|
||||
## Referencias
|
||||
|
||||
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
|
||||
- [Chrome Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/)
|
||||
- [Puppeteer Stealth Plugin](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth)
|
||||
Reference in New Issue
Block a user