Getting Started

Advanced

Introduction

ssf is an enterprise-grade, asynchronous security auditing framework for Supabase projects. It goes beyond simple configuration checks to actively test for vulnerabilities like SQL Injection, IDOR, and Information Leakage.

Why SSF?

  • 🛡️ Active Verification: Attempts safe exploits (e.g., time-based SQLi) to confirm risks.
  • 🤖 AI-Powered Context: Integrates with Gemini, OpenAI, and others for deep insights.
  • ⚙️ CI/CD Ready: JSON output and diffing capabilities make it perfect for pipelines.

Installation

# 1. Install Environment
python3 -m venv .venv
source .venv/bin/activate
# 2. Install supabase-audit-framework
pip3 install supabase-audit-framework --upgrade

Usage

Basic Scan

ssf <SUPABASE_URL> <ANON_KEY>

Advanced Scan (Recommended)

Enable AI analysis, brute-forcing

# Using Gemini
ssf <URL> <KEY> --agent-provider <PROVIDER> --agent <MODEL> --agent-key "<API_KEY>" --brute
# Using OpenAI
ssf <URL> <KEY> --agent-provider <PROVIDER> --agent <MODEL> --agent-key "<API_KEY>" --brute

Supported Models

Provider Argument (`--agent-provider`) Example Models (`--agent`)
Google Gemini gemini gemini-2.5-flash, gemini-2.5-pro , gemini-3-pro-preview, gemini-2.5-flash-lite
OpenAI openai gpt-4-turbo, gpt-4o , gpt-oss-120b , gpt-4o-mini
Anthropic anthropic claude-sonnet-4-5-20250929 , claude-sonnet-4-5 , anthropic.claude-sonnet-4-5-20250929-v1:0 , claude-opus-4-5
DeepSeek deepseek deepseek-chat
Ollama (Local) ollama llama3, mistral, phi3

CI/CD Integration

Block regressions by comparing against a baseline:

# 1. Generate baseline
ssf <URL> <KEY> --json > baseline.json
# 2. Compare in CI
ssf <URL> <KEY> --json --diff baseline.json

Static Code Analysis

Scan your local source code for Supabase-specific vulnerabilities:

ssf <URL> <KEY> --agent-provider <PROVIDER> --agent <MODEL> --agent-key "<API_KEY>" --analyze ./path/to/your/project

Automated Remediation

Generate a SQL script to fix identified vulnerabilities:

ssf <URL> <KEY> --agent-provider <PROVIDER> --agent <MODEL> --agent-key "<API_KEY>" --gen-fixes

Web Management UI

Launch a browser-based interface for managing scans and viewing results:

ssf --webui
# Custom port
ssf --webui --port 3000

Multi-Role Testing

Test for vertical privilege escalation by providing multiple role tokens:

# roles.json: {"user1": "eyJ...", "admin": "eyJ..."}
ssf <URL> <KEY> --roles roles.json

This enables testing of access control boundaries between different user roles.

Automated Threat Modeling

Generate a comprehensive threat model including Data Flow Diagrams and Attack Paths:

ssf <URL> <KEY> --agent-provider <PROVIDER> --agent-key "<API_KEY>" --threat-model

Tamper Scripts (WAF Bypass)

Use built-in tamper scripts or custom ones to bypass Web Application Firewalls:

# Use built-in tamper
ssf <URL> <KEY> --tamper randomcase
# Use custom tamper script
ssf <URL> <KEY> --tamper /path/to/custom_tamper.py

Available Built-in Tampers:

  • • randomcase - SeLECt * fRoM...
  • • charencode - URL encode
  • • doubleencode - Double URL encode
  • • unionall - UNION SELECT → UNION ALL SELECT
  • • space2plus - space → +
  • • version_comment - space → /*!50000*/

Other Advanced Options

Knowledge Base & Risk Acceptance

Create a knowledge.json file to ignore known safe patterns:

{ "accepted_risks": [ { "pattern": "public_stats", "type": "rls", "reason": "Intentionally public dashboard data" } ] }
# Use knowledge base
ssf <URL> <KEY> --knowledge knowledge.json
# Verify if accepted risks have been remediated
ssf <URL> <KEY> --knowledge knowledge.json --verify-fix

Other Useful Flags

Flag Description
--verbose, -v Enable verbose logging
--json Save report to JSON file
--html Generate HTML report
--brute [LIST] Enable Bruteforce (optional: path to wordlist)
--exploit Automatically run generated exploits
--gen-fixes Generate SQL fix script from AI analysis
--verify-fix Verify remediation of accepted risks
--analyze PATH Run Static Code Analysis on file or directory
--plugins LIST Select plugins to run (comma-separated or 'all')
--dump-all Dump all rows found in RLS scan (default: limit 5)
--sniff [SEC] Enable Realtime Sniffer for N seconds (default: 10)
--check-config Check PostgREST configuration (max_rows)
--proxy URL Route traffic through an HTTP proxy
--random-agent Use a random User-Agent header
--level LEVEL Level of tests to perform (1-5, default 1)
--wizard Run in wizard mode for beginners
--compile Compile tool to standalone executable
--stealth Enable Stealth Mode (JA3 Spoofing via curl_cffi)
--sarif Generate SARIF report for GitHub Security
--ngrok Expose Web UI via ngrok
--auth Enable authentication for Web UI (e.g., admin:secret)

New in v1.2.16

🚀 Advanced Stealth & Deep Logic

  • Stealth Mode: Uses curl_cffi to spoof JA3/TLS fingerprints, mimicking a real Chrome browser to bypass WAFs.
  • Smart Proxy Rotation: Automatically rotates proxies on failure or every N requests. Supports proxy lists.
  • JWT Attack Module: Checks for "None" algorithm, weak secrets (offline brute-force), and KID injection vulnerabilities.
  • PostgREST Fuzzer: Advanced fuzzing of filter operators (eq, in, ov, sl, etc.) with heuristic analysis for SQLi/Bypass.
  • GraphQL Batching: Detects batching support and calculates the maximum allowed batch size to prevent DoS attacks.
  • SARIF Output: Generate standard SARIF reports for integration with GitHub Advanced Security.