ale
8a4fde51c7
- Fixed TypeScript errors and build issues - Added comprehensive README.md with documentation - Created .env.example with all configuration options - Improved .gitignore with CSF-specific entries - Added VS Code configuration for development - Fixed next.config.mjs configuration - Corrected API route type issues - Added CHANGELOG.md with version history - All components now compile without errors - Ready for production deployment Features included: - Modern web interface for CSF firewall management - Real-time monitoring with WebSockets - JWT authentication system - Complete API for CSF control - Responsive UI with Tailwind CSS - TypeScript support throughout - Docker-ready configuration Signed-off-by: ale <ale@manalejandro.com>
406 líneas
10 KiB
Markdown
406 líneas
10 KiB
Markdown
# CSF Web Interface
|
|
|
|
Interfaz web moderna para **ConfigServer Security & Firewall (CSF)** construida con Next.js 15, React 19 y TypeScript.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 🚀 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=<ip>&type=allow|deny
|
|
```
|
|
|
|
### Logs del Sistema (`/api/logs`)
|
|
```typescript
|
|
// Obtener logs
|
|
GET /api/logs?type=firewall|lfd|system|blocked&limit=100&since=<timestamp>
|
|
```
|
|
|
|
### 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
|
|
<Dashboard />
|
|
```
|
|
|
|
### Autenticación
|
|
```tsx
|
|
// Wrapper de autenticación
|
|
<AuthWrapper>
|
|
<App />
|
|
</AuthWrapper>
|
|
|
|
// Formulario de login
|
|
<LoginForm onLogin={handleLogin} />
|
|
```
|
|
|
|
### Firewall
|
|
```tsx
|
|
// Estado del firewall
|
|
<FirewallStatusCard />
|
|
|
|
// Gestión de reglas
|
|
<FirewallRules />
|
|
|
|
// Estadísticas del servidor
|
|
<ServerStats />
|
|
```
|
|
|
|
### Utilidades
|
|
```tsx
|
|
// Indicador de conexión en tiempo real
|
|
<RealtimeIndicator />
|
|
|
|
// Visor de logs (placeholder)
|
|
<LogViewer />
|
|
```
|
|
|
|
## 🪝 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.**
|