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.

• 🛡️ Active Verification: Don't just guess; verify. ssf attempts safe exploits (e.g., time-based SQLi) to confirm risks.
• 🤖 AI-Powered Context: Integrates with Google Gemini to understand your specific schema and business logic for deeper insights.
• ⚙️ CI/CD Ready: JSON output and diffing capabilities (--diff) make it perfect for automated security pipelines.
• 🧠 Smart Fuzzing: Uses context-aware payloads to detect hidden data leaks in RPCs.

You can install ssf directly from PyPI using pip:

pip3 install supabase-audit-framework --upgrade

You can also run ssf using Docker. This ensures a consistent environment and avoids dependency conflicts.

1. Build the Docker image:

   docker build -t ssf .

2. Run the container:

   docker run ssf --help

3. Running in Interactive Mode (Wizard): If you use the --wizard mode or any feature requiring user input, you must use the -it flags to allocate a pseudo-TTY and keep stdin open:

   docker run -it ssf --wizard

1. Clone the repository:

   git clone https://github.com/ThemeHackers/ssf cd ssf

2. Install locally:

   python3 -m venv .venv source .venv/bin/activate pip3 install -e .

Once installed, you can use the ssf command globally.

ssf <SUPABASE_URL> <ANON_KEY>

Enable AI analysis, brute-forcing, and HTML reporting:

# Using Gemini (Cloud) ssf <URL> <KEY> --agent-provider gemini --agent gemini-2.0-flash --agent-key "YOUR_API_KEY" --brute --html --json # Using OpenAI (GPT-4) ssf <URL> <KEY> --agent-provider openai --agent gpt-4-turbo --agent-key "sk-..." --brute --html --json # Using Anthropic (Claude) ssf <URL> <KEY> --agent-provider anthropic --agent claude-3-5-sonnet-20240620 --agent-key "sk-ant-..." --brute --html --json # Using DeepSeek (DeepSeek-V3) ssf <URL> <KEY> --agent-provider deepseek --agent deepseek-chat --agent-key "sk-..." --brute --html --json # Using Ollama (Local) ssf <URL> <KEY> --agent-provider ollama --agent llama3 --brute --html --json

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

Automatically run security audits on every push and pull request using GitHub Actions.

Create .github/workflows/supabase-security.yml:

name: Supabase Security Audit on: push: branches: [ "main" ] pull_request: branches: [ "main" ] schedule: - cron: '0 0 * * 0' jobs: security-audit: name: SSF Scan & Report runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install SSF Framework run: pip3 install supabase-audit-framework --upgrade - name: Run Security Scan continue-on-error: true env: SUPABASE_URL: ${{ secrets.SUPABASE_URL }} SUPABASE_KEY: ${{ secrets.SUPABASE_ANON_KEY }} run: |  if [[ -z "$SUPABASE_URL" ]]; then  echo "::error::Secret SUPABASE_URL is empty! Check Environment settings."  exit 1  fi   set +e    ssf $SUPABASE_URL $SUPABASE_KEY \  --ci \  --ci-format github \  --fail-on HIGH \  --sarif \  --json    EXIT_CODE=$?    mv audit_report_*/*.sarif results.sarif  mv audit_report_*/*.json scan_results.json    exit $EXIT_CODE   - name: Upload SARIF to GitHub Security if: always() uses: github/codeql-action/upload-sarif@v4 with: sarif_file: results.sarif category: ssf-audit - name: Upload Raw JSON Report if: always() uses: actions/upload-artifact@v4 with: name: ssf-full-report path: scan_results.json retention-days: 14

Setup Instructions:

1. Go to Settings > Secrets and variables > Actions in your repository.
2. Add SUPABASE_URL and SUPABASE_ANON_KEY.
3. The workflow will now run on every commit and upload results to Security > Code Scanning Alerts.

Scan your local source code for Supabase-specific vulnerabilities (e.g., hardcoded keys, weak RLS definitions in migrations):

ssf <URL> <KEY> --agent-provider gemini --agent-key "KEY" --analyze ./supabase/migrations

Generate a SQL script to fix identified vulnerabilities:

ssf <URL> <KEY> --agent-provider gemini --agent-key "KEY" --gen-fixes

Test for vertical escalation by providing multiple role tokens:

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

Generate a comprehensive threat model (DFD, Attack Paths) using AI:

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

ssf includes a modern, dark-themed Web Dashboard for managing scans, viewing reports, and analyzing risks.

• Dashboard: Real-time scan progress, live logs, and finding summaries.
• Scan History: View, download, and compare past scan reports.
• Risk Management: Review findings and "Accept Risks" with justifications.
• Exploit Manager: View and run generated exploits directly from the browser.

ssf <URL> <KEY> --webui # Optional: Specify port ssf <URL> <KEY> --webui --port 9090 # Optional: For Collaboration ssf <URL> <KEY> --webui --ngrok --auth username:password

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

{ "accepted_risks": [ { "pattern": "public_stats", "type": "rls", "reason": "Intentionally public dashboard data" } ] }

Verify if accepted risks have been remediated and update the knowledge base:

ssf <URL> <KEY> --knowledge knowledge.json --verify-fix

[*] Testing RPC: get_user_data [!] DATA LEAK via RPC 'get_user_data' → 5 rows [!] Potential SQL Injection in get_user_data (param: id) - Verifying... [!!!] CONFIRMED Time-Based SQL Injection in get_user_data (5.02s) 

• Authorized Use Only: You must have explicit permission to scan the target.
• Data Privacy: Using --agent sends scan summaries to Google Gemini.

👉 Read our full Security Policy before use.

Run scans using local LLMs (e.g., Llama 3) for privacy and offline usage:

# Ensure Ollama is running (ollama serve) ssf <URL> <KEY> --agent-provider ollama --agent llama3

Use built-in tamper scripts or custom ones to bypass WAFs:

# Use built-in tamper ssf <URL> <KEY> --tamper randomcase # Available built-ins: # - randomcase: SeLECt * fRoM... # - charencode: URL encode # - doubleencode: Double URL encode # - unionall: UNION SELECT -> UNION ALL SELECT # - space2plus: space -> + # - version_comment: space -> /*!50000*/

plugins/dummy_plugin.py

To ensure the ssf framework automatically discovers and executes your plugin, you must adhere to three specific technical rules:

1. Inheritance Principle Your plugin class must inherit from BaseScanner (located in core.base).

   • Why: The system instantiates plugins by passing client, verbose, and context arguments. The BaseScanner class handles this initialization, giving you access to self.client (for HTTP requests) and self.context (for shared data).

2. Naming Convention Principle The name of your Class must end with the suffix Scanner.

   • Why: The PluginManager iterates through files in the plugins/ directory and specifically filters for classes where attr_name.endswith("Scanner"). If your class is named MyPlugin or SecurityCheck, it will be ignored.

3. Method Implementation Principle You must implement an asynchronous method named scan.

   • Why: The ScannerManager executes plugins concurrently using asyncio. It expects every loaded plugin instance to have an async def scan(self) method that returns a Dictionary (which is then added to the final report).

To create a new plugin, simply create a new .py file (e.g., custom_check.py) inside the plugins/ directory with the following structure:

from typing import Dict, Any # 1. Import the base class from core.base import BaseScanner # 2. Define your class ending with 'Scanner' class CustomVulnerabilityScanner(BaseScanner): """  Documentation for your custom scanner.  """ # 3. Implement the async scan method async def scan(self) -> Dict[str, Any]: self.log_info("[*] Starting Custom Vulnerability Scan...") results = { "found_issues": [], "risk": "SAFE" } try: # Use self.client to make HTTP requests # self.context contains data from previous scans (like 'users', 'tables') target_url = "/some/vulnerable/endpoint" response = await self.client.get(target_url) if response.status_code == 200: self.log_risk(f"Found issue at {target_url}", "HIGH") results["found_issues"].append(target_url) results["risk"] = "HIGH" except Exception as e: self.log_error(f"Custom scan failed: {e}") # Return a dictionary to be included in the final report return results

Once you save this file in the plugins/ folder, ssf will:

1. Detect the file during startup.
2. Import the module and find the CustomVulnerabilityScanner class.
3. Execute your scan() method automatically alongside the built-in scanners.

The developers assume no liability and are not responsible for any misuse or damage caused by this program. Use responsibly.

• See Project Github
• Python Package Index
• Quick Reference Gist - Shareable quick-start reference for SSF