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

# 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

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>/:

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:

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

go run examples/basic.go

Ejemplo 2: Capacidades Avanzadas

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

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
• Chrome Command Line Switches
• Puppeteer Stealth Plugin