baffle-hub/README.md

# 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 PostgreSQL-based database 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
- Forward auth endpoint implementation ( see Baffle-agent )

### 🚧 In Progress
- Rule management framework
- IP range blocking rules
- Country-based blocking (via IP ranges)
- Path based blocking
- Rate limiting engine
- Real-time rule updates ( 10 - 20 second )

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

### Unlikely to Do
- Complete OSWAP capabilities

## Quick Start

### With Docker

```yaml
services:
  # PostgreSQL database
  postgres:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: baffle_hub_production
      POSTGRES_USER: baffle_hub
      POSTGRES_PASSWORD: ${BAFFLE_HUB_DATABASE_PASSWORD:-abcbafflehub123}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U baffle_hub -d baffle_hub_production"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Web instance
  web:
    image: git.booko.info/dkam/baffle-hub:v0.1.3-dev
    environment:
      RAILS_ENV: production
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      BAFFLE_HUB_DATABASE_PASSWORD: ${BAFFLE_HUB_DATABASE_PASSWORD:-bafflehub123}
      DATABASE_URL: postgres://baffle_hub:${BAFFLE_HUB_DATABASE_PASSWORD:-bafflehub123}@postgres:5432/baffle_hub_production
      # Disable Solid Queue in Puma for web instance
      SOLID_QUEUE_IN_PUMA: false
      BAFFLE_HOST: ${BAFFLE_HOST}
      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      OIDC_DISCOVERY_URL: ${OIDC_DISCOVERY_URL}
    ports:
      - "${HOST_IP}:3003:3000"
    volumes:
      - ./log:/app/log
      - ./tmp:/app/tmp
      - ./storage:/rails/storage
#    depends_on:
#      postgres:
#        condition: service_healthy
    restart: unless-stopped
#    command: bundle exec puma -C config/puma.rb

  # Jobs instance (Solid Queue worker)
  jobs:
    image: git.booko.info/dkam/baffle-hub:v0.1.3-dev
    environment:
      RAILS_ENV: production
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      BAFFLE_HUB_DATABASE_PASSWORD: ${BAFFLE_HUB_DATABASE_PASSWORD:-bafflehub123}
      DATABASE_URL: postgres://baffle_hub:${BAFFLE_HUB_DATABASE_PASSWORD:-bafflehub123}@postgres:5432/baffle_hub_production
    volumes:
      - ./log:/app/log
      - ./tmp:/app/tmp
      - ./storage:/rails/storage
#    depends_on:
#      postgres:
#        condition: service_healthy
    restart: unless-stopped
    command: bin/jobs

volumes:
  postgres_data:
```


### 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
```


## 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.