{"id":51702550,"url":"https://github.com/xeland314/catsplash","last_synced_at":"2026-07-16T12:35:58.868Z","repository":{"id":362099221,"uuid":"1254767271","full_name":"xeland314/catsplash","owner":"xeland314","description":"Lightweight, fail-secure Linux captive portal in pure Go. Zero dependencies, optimized for embedded routers (\u003c25MB RAM).","archived":false,"fork":false,"pushed_at":"2026-07-06T16:10:51.000Z","size":245,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T12:35:39.368Z","etag":null,"topics":["captive-portal","go","golang","iptables","linux-networking","network-namespaces","networking","router","sysadmin"],"latest_commit_sha":null,"homepage":"https://xeland314.github.io/catsplash-docs/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xeland314.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T01:27:09.000Z","updated_at":"2026-07-06T21:56:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xeland314/catsplash","commit_stats":null,"previous_names":["xeland314/catsplash"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xeland314/catsplash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeland314%2Fcatsplash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeland314%2Fcatsplash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeland314%2Fcatsplash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeland314%2Fcatsplash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xeland314","download_url":"https://codeload.github.com/xeland314/catsplash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeland314%2Fcatsplash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35544514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["captive-portal","go","golang","iptables","linux-networking","network-namespaces","networking","router","sysadmin"],"created_at":"2026-07-16T12:35:58.216Z","updated_at":"2026-07-16T12:35:58.861Z","avatar_url":"https://github.com/xeland314.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catsplash 🐱\n\n\u003e Catsplash es un portal cautivo ligero para Linux que permite abrir una red temporal, bloquear el acceso a Internet hasta que el usuario acepta los términos y liberar el tráfico de forma segura con Go, SQLite y iptables.\n\n![demo](assets/demo.svg)\n\n## Features\n- Portal cautivo compatible con el flujo de Captive Network Assistant de Android e iOS.\n- Gestión de sesiones y clientes con SQLite, expiración por tiempo absoluto e inactividad.\n- Herramienta de control `catsctl` para revisar estado, listar clientes y gestionar sesiones.\n- Instalador guiado con `setup.sh` que prepara hostapd, dnsmasq, reglas de firewall y la configuración del sistema.\n- Panel de administración con contraseña:\n\n![admin_panel](assets/admin_panel.jpg)\n\n## Architecture\n\n```text\nCliente Wi‑Fi ──\u003e Punto de Acceso (hostapd) ──\u003e Catsplash\n                           │                         │\n                           │                         ├─\u003e Firewall (iptables)\n                           │                         ├─\u003e Base de datos SQLite\n                           │                         └─\u003e Portal web /auth\n```\n\n## Requerimientos\n- Linux con privilegios de root.\n- Debian/Ubuntu recomendado para el asistente de instalación.\n- Dependencias del sistema: `hostapd`, `dnsmasq`, `iptables`, `gcc`, `make`, `sqlite3` y Go 1.26+.\n- Compilador compatible con CGO, ya que el driver de SQLite requiere compilación nativa.\n\n## Instalación\n```bash\ngit clone https://github.com/xeland314/catsplash.git\ncd catsplash\nmake build\nsudo ./setup.sh\n```\n\nEl build deja los binarios en la carpeta `bin/` y el instalador copia los artefactos a `/opt/catsplash`. Sigue los pasos que te indica setup.sh hasta el final. Recuerda que es muy probable que necesites lo básico en configuración de redes.\n\n## Uso\n```bash\nsudo ./bin/catsplash\nsudo ./bin/catsctl status\nsudo ./bin/catsctl list\n```\n\n![catsctl](assets/catsctl_example.jpg)\n![setup.sh](assets/setup.sh.jpg)\n\n\n## Configuración\nEl asistente crea un archivo de configuración en `/opt/catsplash/config.toml` y una base de datos en `/opt/catsplash/catsplash.db`. Si prefieres ajustar manualmente el entorno, puedes editar la configuración generada y reiniciar el servicio.\n\n## Performance\n\n### Rendimiento y Pruebas de Estrés (Performance \u0026 Stress Testing)\n\nCatsplash está diseñado bajo una filosofía de consumo mínimo de recursos, haciéndolo ideal para operar de manera robusta en entornos de producción sobre hardware heredado o routers empotrados de bajos recursos.\n\nPara validar su estabilidad, control de concurrencia y eficiencia en el manejo de memoria bajo escenarios críticos, se diseñó un arnés de pruebas automatizado basado en **Network Namespaces aislados**.\n\n### Arquitectura del Laboratorio de Pruebas\nLas pruebas simulan una topología de red real completa dentro del Kernel de Linux, evitando alterar el entorno de red de la máquina anfitriona:\n* **`ns_router`**: Contenedor de red aislado que ejecuta Catsplash clonando interfaces de producción (`wlx...` para el Access Point y `enp...` para la salida WAN).\n* **`ns_wan`**: Servidor que simula internet público mapeando destinos externos falsos (ej. `8.8.8.8`).\n* **`ns_client [1..100]`**: 100 espacios de red independientes, cada uno configurado con su propia IP y dirección MAC única, interactuando en paralelo.\n\n**Hardware de prueba:**\n\n| Componente | Detalle |\n|---|---|\n| CPU | Intel Core 2 Duo E7400 @ 2.79 GHz (2 núcleos) |\n| RAM | 3.58 GiB (ya al 83% de uso antes de la prueba) |\n| Disco | ext4, 100 GiB |\n| OS | Debian GNU/Linux 13 (trixie), kernel 6.12 |\n\n---\n\n### Test 1: Concurrencia por Ráfaga Masiva (Burst Concurrency)\nEste escenario simula el \"peor caso posible\": **100 clientes concurrentes** enviando una petición de autenticación HTTP POST simultáneamente en el mismo segundo.\n\n#### Monitoreo de Recursos del Proceso (Catsplash Backend)\n\n| Estado / Evento | % CPU | RAM Real (RSS) | RAM Virtual (VIRT) |\n| :--- | :---: | :---: | :---: |\n| **Reposito Inicial** | 0.0% | ~8.7 MB | ~1.7 GB |\n| **Pico Ráfaga #1** | 13.6% | ~11.0 MB | ~2.3 GB |\n| **Estabilización Post-Ráfaga #1** | 0.0% | ~17.0 MB | ~2.4 GB |\n| **Pico Ráfaga #2 (Re-auth)** | 10.0% | ~23.5 MB | ~3.1 GB |\n\n#### Análisis de Métricas de Recursos:\n* **Eficiencia de CPU:** El procesamiento de las 100 solicitudes concurrentes (apertura de sockets TCP, parseo HTTP, consultas de seguridad e inyección de reglas de firewall) apenas requirió un pico máximo del **13.6% de CPU**, demostrando un excelente aprovechamiento de la concurrencia nativa de las Goroutines.\n* **Gestión de Memoria (Residente vs Virtual):** El consumo real físico (RSS) se mantuvo contenido por debajo de los **24 MB** inclusive tras ráfagas consecutivas. El incremento escalonado de 8.7MB a 17MB y finalmente 23.5MB refleja el comportamiento óptimo del asignador de memoria de Go, el cual retiene páginas del sistema para mitigar la sobrecarga de futuras asignaciones.\n\n#### Tiempos de Respuesta y Latencia (Métricas HTTP)\n\nLas peticiones fueron inyectadas en paralelo a través de curls nativos desde cada namespace de cliente. A continuación se detallan los percentiles de respuesta obtenidos en dos ráfagas sucesivas:\n\n| Métrica de Latencia | Ráfaga #1 (Limpia) | Ráfaga #2 (Concurrencia Sobrepuesta) |\n| :--- | :---: | :---: |\n| **Peticiones Exitosas (HTTP 200)** | 100 / 100 | 100 / 100 |\n| **Tiempo Mínimo** | 0.1875 s | 0.4167 s |\n| **Percentil 50 (p50)** | 1.3362 s | 4.7038 s |\n| **Percentil 95 (p95)** | 1.9375 s | 5.3209 s |\n| **Percentil 99 (p99) / Máximo** | 2.3379 s | 5.7166 s |\n\n#### Conclusiones del Test de Estrés:\n1. **Tolerancia a Fallos del 100%:** En ninguna de las corridas se registraron caídas de sockets, timeouts o errores internos (0% de fallos HTTP). Todos los clientes fueron procesados exitosamente.\n2. **Cola de Espera Estructural (I/O Bound):** El incremento en la latencia de la segunda corrida (p50 de 4.7s) demuestra que el cuello de botella del sistema no es el código del portal, sino el bloqueo secuencial a nivel de kernel durante la inserción masiva de reglas de `iptables` y las colas de escritura sincrónica en el almacenamiento de SQLite. Este comportamiento es esperable y perfectamente seguro para la experiencia del usuario final en despliegues reales.\n\n## Contribuir\nConsulta [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Licencia\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxeland314%2Fcatsplash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxeland314%2Fcatsplash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxeland314%2Fcatsplash/lists"}