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>
2026-03-24 23:33:07 +01:00
commit 3253828fef
36 changed files with 8116 additions and 0 deletions
@@ -0,0 +1,324 @@
+# Chrome Stealth Flags - Documentación Completa
+
+Esta documentación lista todas las flags necesarias para ejecutar Chrome/Chromium con la menor detección posible de automatización.
+
+## Flags Críticas (Siempre Activadas)
+
+### 1. Desactivar Detección de Automatización
+
+```go
+"--disable-blink-features=AutomationControlled"
+```
+**Propósito**: Elimina `navigator.webdriver = true` que es el indicador más obvio de automatización.
+**Impacto**: CRÍTICO - Sin esto, casi cualquier sitio detectará la automatización.
+
+```go
+"--exclude-switches=enable-automation"
+```
+**Propósito**: Evita que Chrome agregue el flag `--enable-automation` automáticamente.
+**Impacto**: ALTO - Complementa la desactivación de AutomationControlled.
+
+### 2. Gestión de Perfiles y User Data
+
+```go
+"--user-data-dir=/path/to/profile"
+```
+**Propósito**: Especifica dónde Chrome almacena cookies, historial, extensiones, etc.
+**Impacto**: CRÍTICO - Permite persistencia de sesión y reutilización de perfiles.
+**Nota**: Debe ser ruta absoluta única por instancia.
+
+```go
+"--profile-directory=Default"
+```
+**Propósito**: Nombre del perfil dentro de user-data-dir.
+**Impacto**: MEDIO - Permite múltiples perfiles en el mismo user-data-dir.
+
+### 3. Modo Sin Interfaz Gráfica
+
+```go
+"--headless=new"
+```
+**Propósito**: Ejecuta Chrome sin ventana visible (nuevo modo headless estable).
+**Impacto**: ALTO - Mejor rendimiento, pero puede ser detectado.
+**Alternativa**: Omitir para modo con interfaz visible (más sigiloso pero usa más recursos).
+
+```go
+"--disable-gpu"
+```
+**Propósito**: Desactiva aceleración por GPU (necesario en algunos entornos headless).
+**Impacto**: MEDIO - Evita crashes en servidores sin GPU.
+
+### 4. Configuración de Ventana
+
+```go
+"--window-size=1920,1080"
+```
+**Propósito**: Define tamaño de viewport.
+**Impacto**: MEDIO - Sitios pueden detectar tamaños anormales.
+**Recomendación**: Usar resoluciones comunes (1920x1080, 1366x768, 1440x900).
+
+```go
+"--start-maximized"
+```
+**Propósito**: Inicia ventana maximizada (solo modo no-headless).
+**Impacto**: BAJO - Apariencia más natural en modo visible.
+
+## Flags de Evasión Avanzada
+
+### 5. User Agent y Detección de Plataforma
+
+```go
+"--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+```
+**Propósito**: Sobrescribe el user agent del navegador.
+**Impacto**: ALTO - Debe coincidir con la plataforma y versión de Chrome real.
+**Nota**: Actualizar según versión de Chrome instalada.
+
+### 6. Permisos y Notificaciones
+
+```go
+"--disable-notifications"
+```
+**Propósito**: Bloquea solicitudes de notificaciones del navegador.
+**Impacto**: BAJO - Evita interrupciones molestas.
+
+```go
+"--disable-popup-blocking"
+```
+**Propósito**: Permite abrir popups sin bloqueo.
+**Impacto**: BAJO - Útil para algunos flujos de autenticación.
+
+### 7. Seguridad y Privacidad
+
+```go
+"--disable-web-security"
+```
+**Propósito**: Desactiva CORS y otras políticas de seguridad.
+**Impacto**: MEDIO - Útil para testing, pero inseguro.
+**⚠️ COMENTAR POR DEFECTO** - Solo activar si es necesario.
+
+```go
+"--disable-features=IsolateOrigins,site-per-process"
+```
+**Propósito**: Desactiva aislamiento de procesos por sitio.
+**Impacto**: BAJO - Reduce consumo de memoria.
+**⚠️ COMENTAR POR DEFECTO** - Puede afectar estabilidad.
+
+```go
+"--disable-site-isolation-trials"
+```
+**Propósito**: Desactiva experimentos de aislamiento de sitios.
+**Impacto**: BAJO - Complementa flags anteriores.
+
+### 8. Optimización de Rendimiento
+
+```go
+"--disable-dev-shm-usage"
+```
+**Propósito**: Evita uso de /dev/shm en Docker/containers.
+**Impacto**: MEDIO - Crítico en entornos containerizados.
+
+```go
+"--no-sandbox"
+```
+**Propósito**: Desactiva sandbox de Chrome.
+**Impacto**: ALTO - **PELIGROSO** - Solo usar en entornos confiables (Docker, VMs).
+**⚠️ COMENTAR POR DEFECTO** - Riesgo de seguridad.
+
+```go
+"--disable-setuid-sandbox"
+```
+**Propósito**: Desactiva sandbox SUID.
+**Impacto**: MEDIO - Similar a --no-sandbox.
+**⚠️ COMENTAR POR DEFECTO** - Usar solo si --no-sandbox está activo.
+
+### 9. Extensions y Plugins
+
+```go
+"--disable-extensions"
+```
+**Propósito**: Desactiva todas las extensiones de Chrome.
+**Impacto**: BAJO - Reduce superficie de detección.
+
+```go
+"--disable-plugins"
+```
+**Propósito**: Desactiva plugins (Flash, PDF viewer, etc).
+**Impacto**: BAJO - Mejora rendimiento.
+
+### 10. Logs y Debugging
+
+```go
+"--enable-logging"
+```
+**Propósito**: Activa logs de Chrome.
+**Impacto**: BAJO - Útil para debugging.
+**⚠️ COMENTAR EN PRODUCCIÓN**
+
+```go
+"--v=1"
+```
+**Propósito**: Nivel de verbosidad de logs (0-3).
+**Impacto**: BAJO - Combinar con --enable-logging.
+
+```go
+"--log-level=0"
+```
+**Propósito**: Nivel de log (0=INFO, 1=WARNING, 2=ERROR).
+**Impacto**: BAJO - Control fino de logs.
+
+### 11. Características Especiales
+
+```go
+"--disable-background-timer-throttling"
+```
+**Propósito**: Evita throttling de timers en background.
+**Impacto**: BAJO - Útil para scrapers que esperan en background.
+
+```go
+"--disable-backgrounding-occluded-windows"
+```
+**Propósito**: Evita suspensión de ventanas ocultas.
+**Impacto**: BAJO - Mantiene páginas activas aunque no sean visibles.
+
+```go
+"--disable-renderer-backgrounding"
+```
+**Propósito**: Evita que el renderer entre en modo background.
+**Impacto**: BAJO - Mejora consistencia en ejecución.
+
+```go
+"--disable-ipc-flooding-protection"
+```
+**Propósito**: Desactiva protección contra flooding de IPC.
+**Impacto**: BAJO - Útil cuando se envían muchos comandos CDP rápidamente.
+
+### 12. Features de Chrome a Desactivar
+
+```go
+"--disable-features=TranslateUI"
+```
+**Propósito**: Desactiva ofertas de traducción automática.
+**Impacto**: BAJO - Menos interrupciones.
+
+```go
+"--disable-features=PrivacySandboxSettings4"
+```
+**Propósito**: Desactiva configuración de Privacy Sandbox.
+**Impacto**: BAJO - Reduce telemetría.
+
+## Flags para Contextos Específicos
+
+### Docker/Containers
+```go
+"--no-sandbox"
+"--disable-setuid-sandbox"
+"--disable-dev-shm-usage"
+```
+
+### Headless Máximo Sigilo
+```go
+"--headless=new"
+"--disable-gpu"
+"--hide-scrollbars"
+"--mute-audio"
+```
+
+### Debugging
+```go
+"--enable-logging"
+"--v=1"
+"--remote-debugging-port=0"  // Puerto aleatorio, CDP asignará uno
+```
+
+## Configuración Recomendada por Defecto
+
+```go
+var DefaultStealthFlags = []string{
+    // CRÍTICAS - Siempre activadas
+    "--disable-blink-features=AutomationControlled",
+    "--exclude-switches=enable-automation",
+
+    // Headless moderno
+    "--headless=new",
+    "--disable-gpu",
+
+    // Ventana
+    "--window-size=1920,1080",
+
+    // Optimización
+    "--disable-dev-shm-usage",
+    "--disable-extensions",
+
+    // Estabilidad
+    "--disable-background-timer-throttling",
+    "--disable-backgrounding-occluded-windows",
+    "--disable-renderer-backgrounding",
+
+    // Menos ruido
+    "--disable-notifications",
+    "--disable-features=TranslateUI",
+
+    // COMENTADAS - Activar según necesidad:
+    // "--no-sandbox",  // Solo Docker/confiable
+    // "--disable-web-security",  // Solo para testing
+    // "--enable-logging",  // Solo debugging
+}
+```
+
+## JavaScript Injection Anti-Detección
+
+Además de las flags, inyectar este script en cada página:
+
+```javascript
+// Sobrescribir propiedades que delatan automatización
+Object.defineProperty(navigator, 'webdriver', {
+    get: () => undefined
+});
+
+// Eliminar _selenium, _webdriver, callSelenium
+delete window.navigator.__proto__.webdriver;
+
+// Chrome runtime mock
+window.chrome = {
+    runtime: {},
+    loadTimes: function() {},
+    csi: function() {},
+    app: {}
+};
+
+// Permisos mock
+const originalQuery = window.navigator.permissions.query;
+window.navigator.permissions.query = (parameters) => (
+    parameters.name === 'notifications' ?
+        Promise.resolve({ state: Notification.permission }) :
+        originalQuery(parameters)
+);
+
+// Plugin array fix
+Object.defineProperty(navigator, 'plugins', {
+    get: () => [1, 2, 3, 4, 5]
+});
+
+// Languages fix
+Object.defineProperty(navigator, 'languages', {
+    get: () => ['en-US', 'en']
+});
+```
+
+## Orden de Prioridad
+
+1. **CRÍTICO**: `--disable-blink-features=AutomationControlled`
+2. **CRÍTICO**: `--exclude-switches=enable-automation`
+3. **CRÍTICO**: `--user-data-dir` (perfiles persistentes)
+4. **ALTO**: `--headless=new` (o omitir para modo visible)
+5. **ALTO**: User-Agent correcto
+6. **MEDIO**: Window size realista
+7. **MEDIO**: JavaScript injection anti-detección
+8. **BAJO**: Resto de flags según contexto
+
+## Referencias
+
+- [Chrome Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/)
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+- [Puppeteer Extra Stealth Plugin](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth)