feat(cybersecurity): auto-commit con 10 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bash/functions/browser/launch_chromium_proxy.md

@@ -0,0 +1,74 @@
+---
+name: launch_chromium_proxy
+kind: function
+lang: bash
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "launch_chromium_proxy [--proxy URL] [--profile DIR] [--url URL] [--ca-cert PATH] [--extra \"ARGS\"]"
+description: "Lanza Chromium (o Chrome) apuntando a un proxy HTTP/HTTPS local con un perfil completamente aislado del perfil real del usuario. Pensado para capturar trafico con un proxy de interceptacion (mitmproxy, Burp Suite) sin contaminar la sesion normal de navegacion. Emite un JSON con el PID del proceso lanzado."
+tags: [chromium, chrome, proxy, mitmproxy, burp, browser, web-proxy, intercept, tls]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "--proxy URL"
+    desc: "URL del proxy HTTP/HTTPS local, ej. http://127.0.0.1:8080. Se pasa a Chromium como --proxy-server=URL. Default: http://127.0.0.1:8080."
+  - name: "--profile DIR"
+    desc: "Directorio de perfil aislado para Chromium (--user-data-dir). Se crea automaticamente si no existe. Default: /tmp/chromium-proxy. Usar un path distinto por sesion si se quiere aislamiento total entre corridas."
+  - name: "--url URL"
+    desc: "URL inicial a abrir al arrancar el navegador. Opcional. Si se omite, Chromium abre su pagina de nueva pestana."
+  - name: "--ca-cert PATH"
+    desc: "Ruta a un CA cert PEM del proxy (ej. ~/.mitmproxy/mitmproxy-ca-cert.pem). Si se pasa, la funcion NO agrega --ignore-certificate-errors y asume que el usuario ya importo el CA en el perfil o en el sistema. Si se omite, se agrega --ignore-certificate-errors automaticamente para que el proxy MITM no rompa HTTPS (menos seguro)."
+  - name: "--extra \"ARGS\""
+    desc: "Flags extra que se pasan directamente a chromium, ej. --extra \"--disable-gpu --window-size=1280,800\". El valor completo debe ir entre comillas."
+output: "JSON en stdout: {\"pid\": <pid>, \"browser\": \"<binario>\", \"proxy\": \"<url>\", \"profile\": \"<dir>\", \"log\": \"<ruta_log>\"}. Mensajes de estado e informacion de CA en stderr. El navegador corre en background desacoplado de la sesion. Exit codes: 0=lanzado correctamente, 1=binario no encontrado o argumento invalido o error al crear el directorio de perfil."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/browser/launch_chromium_proxy.sh"
+---
+
+## Ejemplo
+
+```bash
+source bash/functions/browser/launch_chromium_proxy.sh
+
+# Caso mas comun: interceptar trafico con mitmproxy corriendo en 8080
+# (sin CA instalado: --ignore-certificate-errors se aplica automaticamente)
+result=$(launch_chromium_proxy --proxy http://127.0.0.1:8080 --url https://httpbin.org/get)
+echo "$result"
+# {"pid":12345,"browser":"chromium","proxy":"http://127.0.0.1:8080","profile":"/tmp/chromium-proxy","log":"/tmp/chromium-proxy-12345.log"}
+
+# Con CA cert instalado (mitmproxy): sin --ignore-certificate-errors
+launch_chromium_proxy \
+  --proxy http://127.0.0.1:8080 \
+  --ca-cert ~/.mitmproxy/mitmproxy-ca-cert.pem \
+  --profile /tmp/mitm-session \
+  --url https://api.ejemplo.com/v1/test
+
+# Con Burp Suite en puerto 8081, perfil aislado y ventana de tamano fijo
+launch_chromium_proxy \
+  --proxy http://127.0.0.1:8081 \
+  --profile /tmp/burp-session \
+  --extra "--window-size=1440,900" \
+  --url https://app.objetivo.com
+```
+
+## Cuando usarla
+
+Cuando necesitas capturar y analizar trafico HTTPS de un navegador con mitmproxy, Burp Suite u otro proxy de interceptacion, sin tocar el perfil real del usuario ni sus cookies/credenciales guardadas. Ideal antes de hacer analisis de trafico de una app web o API, o al reproducir un flujo autenticado desde una sesion limpia.
+
+## Gotchas
+
+- **Deteccion de binario en orden**: la funcion prueba `chromium`, `chromium-browser`, `google-chrome-stable`, `google-chrome`. En sistemas donde solo existe `google-chrome`, ese sera el binario usado. Si ninguno esta en el PATH, retorna exit 1. Instalar con `sudo apt install chromium` o `chromium-browser`.
+- **`--ignore-certificate-errors` sin `--ca-cert`**: este flag desactiva toda la validacion TLS del navegador. Es conveniente para empezar rapido, pero reduce la seguridad de la sesion. Para produccion o analisis de seguridad serio, instalar el CA del proxy en el sistema (`sudo cp mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt && sudo update-ca-certificates`) o en el perfil de Chromium (chrome://settings/certificates), y pasar `--ca-cert` para que la funcion omita el flag inseguro.
+- **`--proxy-bypass-list="<-loopback>"`**: fuerza que el trafico loopback (127.0.0.1, localhost) TAMBIEN pase por el proxy. Sin esto, Chromium excluye loopback del proxy por defecto y no veras esas peticiones en mitmproxy. Si quieres el comportamiento estandar (excluir loopback), elimina este flag via `--extra`.
+- **Perfil persistente entre sesiones**: el perfil en `/tmp/chromium-proxy` (o el directorio que elijas) persiste entre ejecuciones. Si quieres una sesion 100% limpia cada vez, pasa `--profile /tmp/chromium-proxy-$$` (usa el PID del shell como sufijo) o borra el directorio antes de llamar a la funcion.
+- **`setsid` + `disown`**: el navegador se lanza desacoplado de la sesion del agente. Si la shell/sesion que llamo a la funcion termina, el proceso Chromium sigue vivo. Para matarlo, usar `kill <pid>` con el PID del JSON de salida.
+- **Log del navegador**: stdout y stderr de Chromium se redirigen a `/tmp/chromium-proxy-<pid>.log`. Si el navegador no arranca, revisar ese archivo para ver el error.
+- **Chrome STABLE 138+**: al igual que `chrome_load_extensions`, algunos flags de automatizacion estan bloqueados en Chrome STABLE. Para interceptacion de trafico `--proxy-server` y `--user-data-dir` siguen funcionando en todas las versiones. Esta funcion es compatible con Chrome/Chromium en cualquier canal.
+- **Multiples instancias**: si ya hay una instancia de Chromium corriendo con el mismo `--user-data-dir`, Chromium puede reusar esa instancia en lugar de abrir una nueva. Usar un directorio de perfil distinto por sesion concurrente.

bash/functions/browser/launch_chromium_proxy.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# launch_chromium_proxy — Lanza Chromium apuntando a un proxy HTTP/HTTPS local con perfil aislado.
+
+launch_chromium_proxy() {
+    local proxy_url="http://127.0.0.1:8080"
+    local profile_dir="/tmp/chromium-proxy"
+    local start_url=""
+    local ca_cert=""
+    local extra_args=""
+
+    # Parsear argumentos
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --proxy)
+                proxy_url="$2"; shift 2 ;;
+            --profile)
+                profile_dir="$2"; shift 2 ;;
+            --url)
+                start_url="$2"; shift 2 ;;
+            --ca-cert)
+                ca_cert="$2"; shift 2 ;;
+            --extra)
+                extra_args="$2"; shift 2 ;;
+            *)
+                echo "ERROR: argumento desconocido: $1" >&2
+                return 1 ;;
+        esac
+    done
+
+    # Detectar binario del navegador
+    local browser_bin=""
+    for candidate in chromium chromium-browser google-chrome-stable google-chrome; do
+        if command -v "$candidate" &>/dev/null; then
+            browser_bin="$candidate"
+            break
+        fi
+    done
+
+    if [[ -z "$browser_bin" ]]; then
+        echo "ERROR: no se encontro ningun binario Chromium/Chrome en el PATH." >&2
+        echo "       Probados: chromium, chromium-browser, google-chrome-stable, google-chrome." >&2
+        return 1
+    fi
+
+    # Crear directorio de perfil si no existe
+    if [[ ! -d "$profile_dir" ]]; then
+        mkdir -p "$profile_dir" || {
+            echo "ERROR: no se pudo crear el directorio de perfil: $profile_dir" >&2
+            return 1
+        }
+    fi
+
+    # Construir argumentos del navegador
+    local args=(
+        "--proxy-server=${proxy_url}"
+        "--user-data-dir=${profile_dir}"
+        "--proxy-bypass-list=<-loopback>"
+        "--no-first-run"
+        "--no-default-browser-check"
+    )
+
+    # Manejo de certificados TLS
+    if [[ -n "$ca_cert" ]]; then
+        # El usuario instalo el CA en el perfil; no ignorar errores de certificado.
+        # (El CA se instala en el sistema o en el perfil antes de lanzar.)
+        echo "INFO: CA cert declarado: $ca_cert" >&2
+        echo "INFO: Asegurate de haber importado el CA en el perfil o en el sistema antes de navegar HTTPS." >&2
+    else
+        # Sin CA cert: ignorar errores de certificado para que mitmproxy/Burp funcionen sin configuracion extra.
+        # ADVERTENCIA: esto desactiva la validacion TLS completa del navegador.
+        args+=("--ignore-certificate-errors")
+        echo "WARN: --ignore-certificate-errors activo. Usa --ca-cert si instalaste el CA del proxy." >&2
+    fi
+
+    # URL inicial opcional
+    if [[ -n "$start_url" ]]; then
+        args+=("$start_url")
+    fi
+
+    # Argumentos extra pasados por el usuario
+    # shellcheck disable=SC2206
+    local extra_arr=()
+    if [[ -n "$extra_args" ]]; then
+        read -r -a extra_arr <<< "$extra_args"
+        args+=("${extra_arr[@]}")
+    fi
+
+    # Log temporal para stderr/stdout del navegador
+    local log_file="/tmp/chromium-proxy-$$.log"
+
+    # Lanzar en background desacoplado de la sesion del agente
+    setsid "$browser_bin" "${args[@]}" </dev/null >"$log_file" 2>&1 &
+    local browser_pid=$!
+    disown "$browser_pid"
+
+    # Emitir JSON con informacion del proceso lanzado
+    printf '{"pid":%d,"browser":"%s","proxy":"%s","profile":"%s","log":"%s"}\n' \
+        "$browser_pid" "$browser_bin" "$proxy_url" "$profile_dir" "$log_file"
+}
+
+# Ejecutar si se llama directamente (fn run / bash <file>)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    launch_chromium_proxy "$@"
+fi