How protectai/rebuff works
Project type and purpose
• Rebuff.ai is a full-stack, self-hosting AI security platform and open-source SDK suite for detecting prompt injection attacks.
• It consists of:
– A Next.js-based web UI and serverless API (“server” folder)
– A JavaScript/TypeScript SDK (javascript-sdk folder)
– A Python SDK (python-sdk folder)
– Documentation and CI/CD workflows
File structure
• Top-level monorepo with four main “layers”:
– server: Next.js React UI (pages/, components/, styles/) combined with API routes (pages/api/…) implementing detection endpoints, billing, user management
– javascript-sdk: client-side library exposing detectInjections, addCanaryWord, etc. backed by TypeScript interfaces, tests, CI
– python-sdk: pip-installable SDK mirroring TS functionality with detect_pi_heuristics, detect_pi_openai, detect_pi_vectorbase, canary methods
• server contains configuration files for Netlify, TailwindCSS, Supabase (SQL schemas, functions) and Pinecone index integration
• CI workflows: build and publish Python/JS SDKs, run tests
Extract architecture insights from README and detection.puml
• Reads as a layered defense pipeline:
1. Heuristic filtering
2. LLM-based detection via OpenAI
3. VectorDB matching in Pinecone/Chroma
4. Canary token injection and leak detection
Main components
• Client applications:
– Web UI (Next.js front-end)
– JavaScript SDK (npm package)
– Python SDK (pip package)
• API Gateway / Server: Next.js serverless functions (account management, detect endpoint, logging, billing)
• Business logic layer: detection pipeline library (server/lib/*) implementing the four defense layers
• Data stores:
– Relational DB (Supabase/PostgreSQL) for user accounts, API keys, stats, logs
– VectorDB (Pinecone or Chroma) for storing attack embeddings
• External services:
– OpenAI (LLM calls)
– Supabase Auth & Compute
– Pinecone (vector similarity queries)
• Infrastructure & CI/CD: GitHub Actions, Netlify (or Vercel), Makefile for init
Relationships and data flows
• User (or SDK) → HTTP(S) → Next.js API route (/api/detect)
• API route → Heuristic module → Pass/fail →
– If pass, call OpenAI detection model → label
– Insert embeddings in Pinecone (vector DB) → similarity checks
– Canary token insertion and leak check → update vault
• Each stage logs results to Supabase/Postgres via SQL functions or direct queries
• Billing function deducts credits per call (SQL UDF on Supabase)
• UI reads/writes account, stats, prompt history via protected API routes
• SDKs wrap the HTTP API for embedding in external apps
Architectural patterns & design principles
• Layered pipeline: sequence of filters and detectors
• Monorepo modularization: separate SDKs vs. server code
• Serverless functions (Next.js API routes) for scalable endpoints
• Event-driven logging: functions and SQL triggers for billing and metrics
• SDK abstraction: clients never call OpenAI or Pinecone directly; they go through Rebuff API
Technologies, frameworks, and libraries
• Frontend/UI: Next.js, React, TypeScript, Tailwind CSS
• Backend: Node.js, Next.js API routes, serverless
• Databases: Supabase (Postgres + SQL functions), Pinecone (vector similarity)
• LLM: OpenAI GPT-3.5 Turbo (configurable)
• SDKs: TypeScript (axios/fetch), Python (httpx/requests, dataclasses)
• CI/CD: GitHub Actions, Makefile
• Testing: Mocha/Chai for JS, pytest for Python