# Baffle Hub

**Rails 8 WAF analytics and automated rule management system** ⚠️ **Experimental**

Baffle Hub provides intelligent Web Application Firewall (WAF) analytics with automated rule generation. It combines real-time threat detection with SQLite-based local storage for ultra-fast request filtering.

## Features

- **Real-time Analytics** - Process WAF events and detect attack patterns
- **Automated Rule Generation** - Create rules automatically from threat intelligence
- **Fast Local Storage** - SQLite for sub-millisecond request evaluation
- **Forward Auth Integration** - Compatible with Caddy, Traefik, and NGINX
- **Docker Ready** - Containerized deployment with Kamal

## Status

### ✅ Complete
- Event ingestion API with DSN authentication
- Comprehensive data normalization (hosts, paths, IPs)
- Basic analytics dashboard
- Background job processing system
- Docker deployment setup

### 🚧 In Progress
- Rule management framework
- IP range blocking rules
- Country-based blocking (via IP ranges)
- Forward auth endpoint implementation

### 📋 TODO
- Advanced pattern analysis and threat detection
- Automatic rule generation algorithms
- Rate limiting engine
- Challenge/redirect mechanisms
- Unix socket support for ultra-low latency
- Multi-node rule synchronization
- Advanced analytics visualizations
- Real-time rule updates

## Quick Start

### Prerequisites

- Ruby 3.x
- Docker (optional)

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd baffle-hub

# Install dependencies
bundle install

# Copy environment files
cp .env.example .env

# Setup database
rails db:create db:migrate

# Start the server
rails server
```

### With Docker

```bash
# Build and run
docker-compose up -d
```

## Architecture

```
Request → Reverse Proxy → Baffle (SQLite check) → Decision
                            ↓
                    Async analytics processing
                            ↓
                    Pattern detection → New rules
```

## Configuration

Key environment variables:

- `DATABASE_URL` - PostgreSQL connection string
- `RAILS_ENV` - Environment (development/production)
- `SECRET_KEY_BASE` - Rails secret key

## API Endpoints

- `POST /api/:project_id/events` - Ingest WAF events
- `GET /projects/:id` - View project analytics
- `GET /dashboard` - Analytics dashboard

## Deployment

Deploy with Kamal:

```bash
# Setup deployment
kamal setup

# Deploy to production
kamal deploy
```

## Development

```bash
# Run tests
rails test

# Run background jobs
rails jobs:work

# View analytics
rails console
```

## License

MIT License - see LICENSE file for details.