# CSF Web Interface Interfaz web moderna para **ConfigServer Security & Firewall (CSF)** construida con Next.js 15, React 19 y TypeScript. ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![React](https://img.shields.io/badge/React-19-blue) ![TypeScript](https://img.shields.io/badge/TypeScript-5.2-blue) ![Tailwind](https://img.shields.io/badge/Tailwind-4.0-06B6D4) ## 🚀 Características - **🎨 Interfaz Moderna**: UI responsive construida con Tailwind CSS - **⚡ Tiempo Real**: WebSockets para actualizaciones en vivo - **🔐 Autenticación Segura**: Sistema JWT con cookies httpOnly - **📊 Dashboard Completo**: Estadísticas, logs y monitoreo del sistema - **🛡️ Gestión de Reglas**: Control total de reglas allow/deny/temporal - **📈 Monitoreo en Vivo**: CPU, memoria, red y conexiones - **🔄 API REST**: Endpoints completos para control de CSF - **🌐 WebSocket**: Datos en tiempo real sin polling ## 📁 Estructura del Proyecto ``` csf-web/ ├── 📁 public/ # Archivos estáticos ├── 📁 src/ │ ├── 📁 app/ # App Router (Next.js 15) │ │ ├── 📁 api/ # API Routes │ │ │ ├── 📄 auth/route.ts # Autenticación │ │ │ ├── 📄 csf/route.ts # Control CSF │ │ │ ├── 📄 rules/route.ts # Gestión reglas │ │ │ ├── 📄 logs/route.ts # Logs del sistema │ │ │ ├── 📄 stats/route.ts # Estadísticas │ │ │ ├── 📄 config/route.ts # Configuración │ │ │ └── 📄 health/route.ts # Health check │ │ ├── 📄 layout.tsx # Layout principal │ │ ├── 📄 page.tsx # Página principal │ │ └── 📄 globals.css # Estilos globales │ ├── 📁 components/ # Componentes React │ │ ├── 📄 Dashboard.tsx # Dashboard principal │ │ ├── 📄 FirewallStatusCard.tsx # Estado del firewall │ │ ├── 📄 ServerStats.tsx # Estadísticas servidor │ │ ├── 📄 FirewallRules.tsx # Gestión de reglas │ │ ├── 📄 LogViewer.tsx # Visor de logs │ │ ├── 📄 LoginForm.tsx # Formulario login │ │ ├── 📄 AuthWrapper.tsx # Wrapper autenticación │ │ └── 📄 RealtimeIndicator.tsx # Indicador tiempo real │ ├── 📁 hooks/ # Hooks personalizados │ │ ├── 📄 use-auth.ts # Hook autenticación │ │ ├── 📄 use-csf-api.ts # Hook API CSF │ │ └── 📄 use-realtime-data.ts # Hook WebSocket │ ├── 📁 lib/ # Utilidades │ │ └── 📄 utils.ts # Funciones utilitarias │ ├── 📁 store/ # Estado global │ │ └── 📄 csf-store.ts # Store Zustand │ ├── 📁 types/ # Tipos TypeScript │ │ └── 📄 csf.ts # Tipos CSF │ └── 📁 pages/ # Pages API (WebSocket) │ └── 📁 api/ │ └── 📄 socket.ts # WebSocket handler ├── 📄 package.json # Dependencias ├── 📄 next.config.mjs # Configuración Next.js ├── 📄 tailwind.config.js # Configuración Tailwind ├── 📄 tsconfig.json # Configuración TypeScript ├── 📄 jsconfig.json # Configuración JavaScript └── 📄 README.md # Este archivo ``` ## 🛠️ Instalación y Desarrollo ### Prerrequisitos - Node.js 18.17 o superior - npm 9.0 o superior ### Instalación ```bash # Instalar dependencias npm install --legacy-peer-deps # Configurar variables de entorno cp .env.example .env.local ``` ### Variables de Entorno Crear archivo `.env.local` con: ```bash # Seguridad JWT_SECRET=your-super-secret-jwt-key-here NODE_ENV=development # API NEXT_PUBLIC_API_URL=http://localhost:3000 # CSF Paths (para desarrollo local) CSF_CONFIG_PATH=/etc/csf CSF_LOG_PATH=/var/log/lfd CSF_BIN_PATH=/usr/local/csf/bin ``` ### Comandos de Desarrollo ```bash # Desarrollo con hot reload npm run dev # Construir para producción npm run build # Iniciar servidor de producción npm start # Verificar tipos TypeScript npm run type-check # Linting npm run lint # Setup completo npm run setup ``` ## 🔧 Tecnologías Utilizadas ### Frontend - **Next.js 15**: Framework React con App Router - **React 19**: Biblioteca de interfaces de usuario - **TypeScript 5.2**: Tipado estático - **Tailwind CSS 4**: Framework CSS utilitario - **Radix UI**: Componentes primitivos accesibles ### Estado y Datos - **Zustand 5**: Gestión de estado global - **Socket.IO Client**: WebSocket para tiempo real - **React Hooks**: Estado local y efectos ### Autenticación - **JWT**: Tokens de autenticación - **bcrypt**: Hash de contraseñas - **Cookies httpOnly**: Almacenamiento seguro ### Desarrollo - **ESLint**: Linting de código - **Prettier**: Formateo de código - **TypeScript**: Análisis de tipos ## 📡 API Routes ### Autenticación (`/api/auth`) ```typescript // Login POST /api/auth Body: { username: string, password: string } // Verificar sesión GET /api/auth // Logout DELETE /api/auth ``` ### Control CSF (`/api/csf`) ```typescript // Estado del firewall GET /api/csf?action=status|version|check // Ejecutar comandos POST /api/csf Body: { action: "start"|"stop"|"restart"|"enable"|"disable", args?: string[] } ``` ### Gestión de Reglas (`/api/rules`) ```typescript // Obtener reglas GET /api/rules?type=all|allow|deny|temp // Agregar regla POST /api/rules Body: { action: string, ip: string, comment?: string } // Eliminar regla DELETE /api/rules?ip=&type=allow|deny ``` ### Logs del Sistema (`/api/logs`) ```typescript // Obtener logs GET /api/logs?type=firewall|lfd|system|blocked&limit=100&since= ``` ### Estadísticas (`/api/stats`) ```typescript // Estadísticas del servidor GET /api/stats // Estadísticas en tiempo real POST /api/stats Body: { interval: number } ``` ## 🔌 WebSocket Events ### Cliente → Servidor ```typescript // Solicitar estadísticas socket.emit('request-stats') // Solicitar logs socket.emit('request-logs', { limit: 50 }) ``` ### Servidor → Cliente ```typescript // Datos de estadísticas socket.on('stats', (data: ServerStats) => {}) // Nuevos logs socket.on('logs', (data: LogEntry[]) => {}) // Estado de conexión socket.on('connected', (data: { message: string }) => {}) ``` ## 🎨 Componentes Principales ### Dashboard ```tsx // Dashboard principal con navegación ``` ### Autenticación ```tsx // Wrapper de autenticación // Formulario de login ``` ### Firewall ```tsx // Estado del firewall // Gestión de reglas // Estadísticas del servidor ``` ### Utilidades ```tsx // Indicador de conexión en tiempo real // Visor de logs (placeholder) ``` ## 🪝 Hooks Personalizados ### useAuth ```typescript const { user, login, logout, loading, error } = useAuth() ``` ### useCSFApi ```typescript const { status, rules, logs, stats, startFirewall, stopFirewall, addRule, loading, error } = useCSFApi() ``` ### useRealtimeData ```typescript const { connected, stats, logs, connect, disconnect, requestStats } = useRealtimeData() ``` ## 🔒 Seguridad ### Autenticación - JWT con cookies httpOnly y secure - Protección CSRF automática - Validación de tokens en cada request ### API Security - Validación de entrada en todos los endpoints - Rate limiting (recomendado para producción) - Headers de seguridad configurados ### Configuración de Seguridad ```javascript // next.config.mjs headers: [ 'X-Frame-Options': 'DENY', 'X-Content-Type-Options': 'nosniff', 'X-XSS-Protection': '1; mode=block', 'Referrer-Policy': 'strict-origin-when-cross-origin' ] ``` ## 🚀 Despliegue ### Desarrollo Local ```bash npm run dev # Acceso: http://localhost:3000 ``` ### Docker (Ver docker-compose.yml en raíz) ```bash # Desde el directorio raíz del proyecto docker-compose up -d ``` ### Producción ```bash npm run build npm start ``` ## 🐛 Resolución de Problemas ### Error de dependencias ```bash # Limpiar cache e instalar rm -rf node_modules package-lock.json npm install --legacy-peer-deps ``` ### Errores de TypeScript ```bash # Verificar tipos npm run type-check # Reiniciar servidor TypeScript en VS Code Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server" ``` ### Problemas de WebSocket ```bash # Verificar que el servidor WebSocket esté ejecutándose curl http://localhost:3000/api/socket ``` ### Errores de CSF API - Verificar que CSF esté instalado y funcional - Revisar permisos de archivos de configuración - Comprobar rutas de CSF en variables de entorno ## 📈 Monitoreo y Logs ### Logs de la Aplicación ```bash # Desarrollo tail -f .next/server.log # Producción (Docker) docker logs csf-web-interface -f ``` ### Métricas de Rendimiento - Usar herramientas de desarrollo de React - Monitorear WebSocket connections - Revisar uso de memoria en estadísticas ## 🤝 Contribución 1. Fork el repositorio 2. Crear rama feature: `git checkout -b feature/nueva-caracteristica` 3. Commit cambios: `git commit -am 'Agregar nueva característica'` 4. Push a la rama: `git push origin feature/nueva-caracteristica` 5. Crear Pull Request ### Estándares de Código - Usar TypeScript para todo el código - Seguir convenciones de React Hooks - Mantener componentes pequeños y reutilizables - Documentar APIs y componentes complejos ## 📝 Licencia GPL v3 - Ver archivo LICENSE en el directorio raíz. ## 🆘 Soporte - 📧 Email: soporte@ejemplo.com - 🐛 Issues: [GitHub Issues](../../issues) - 📚 Docs: Consultar este README.md --- **Desarrollado con ❤️ para administrar CSF de manera moderna y eficiente.**