Supabase Security Audit Orchestrator
🔵 RECOMMENDED: USE PLAN MODE FOR COMPLEX AUDITS
When your environment supports Plan Mode, it is strongly recommended to activate it before starting the audit:
- Use the
EnterPlanMode tool at the start of the orchestration
- Plan Mode enables better organization of multi-phase audits
- It allows the user to validate the approach before execution
- If Plan Mode is not available, proceed directly with execution
Plan Mode provides better traceability and user control over the audit process.
🔴 CRITICAL: PROGRESSIVE FILE UPDATES REQUIRED
You MUST write to context files AS YOU GO, not just at the end.
- Write to
.sb-pentest-context.json IMMEDIATELY after each discovery
- Log to
.sb-pentest-audit.log BEFORE and AFTER each action
- DO NOT wait until a phase or skill completes to update files
- If the audit crashes or is interrupted, all prior findings must already be saved
This is not optional. Failure to write progressively is a critical error.
This skill orchestrates a complete security audit of a Supabase-based application, guiding you through each phase with validation checkpoints.
⚠️ MANDATORY: Progressive Context File Management
BEFORE starting any audit, you MUST:
- Create
.sb-pentest-context.json if it doesn't exist
- Create
.sb-pentest-audit.log if it doesn't exist
- Create
.sb-pentest-evidence/ directory structure
- Initialize context with target URL and timestamp
DURING execution - WRITE AS YOU GO:
- BEFORE each action → Log to
.sb-pentest-audit.log
- AFTER each discovery → IMMEDIATELY update
.sb-pentest-context.json
- AFTER each test → Save evidence to
.sb-pentest-evidence/
- DO NOT batch writes → Each finding must be saved as it's discovered
- Verify after each skill → Check that ALL files were updated before proceeding
📋 SYSTEMATIC DOCUMENTATION REQUIREMENTS
All tracking files MUST be systematically maintained throughout the entire audit.
Required Files (MANDATORY)
| File |
Purpose |
Update Frequency |
.sb-pentest-context.json |
Centralized state and findings |
After EVERY discovery |
.sb-pentest-audit.log |
Chronological action log |
BEFORE and AFTER every action |
.sb-pentest-evidence/timeline.md |
Timestamped findings narrative |
After EVERY significant finding |
.sb-pentest-evidence/curl-commands.sh |
Reproducible test commands |
After EVERY curl/HTTP request |
Verification Checklist (Before Each Phase Transition)
Before moving to the next phase, the orchestrator MUST verify:
If any file is missing or incomplete, DO NOT proceed to the next phase.
Progressive Write Pattern
Each skill MUST follow this pattern:
1. [LOG] Write START entry to audit.log
2. [CONTEXT] Update context.json with "phase_in_progress"
3. [ACTION] Perform the test/scan
4. [EVIDENCE] Save evidence file IMMEDIATELY
5. [CURL] Append curl command to curl-commands.sh
6. [TIMELINE] Update timeline.md if significant finding
7. [CONTEXT] Update context.json with results
8. [LOG] Write COMPLETE entry to audit.log
Failure Recovery
If a skill or phase fails:
- All files updated up to the failure point are preserved
- The audit can be resumed from the last successful checkpoint
- Context file indicates exactly where the audit stopped
⚠️ WHY THIS MATTERS:
- If the audit is interrupted, crashes, or times out, findings up to that point are preserved
- Long-running skills must save progress incrementally, not just at the end
- Users can monitor progress in real-time by watching the log file
FAILURE TO UPDATE CONTEXT FILES PROGRESSIVELY IS NOT ACCEPTABLE.
Each individual skill is responsible for updating these files AS IT WORKS, not just at completion. If a skill does not update the context progressively, the orchestrator must do it immediately after each discovery.
When to Use This Skill
- Running a complete security assessment on a Supabase application
- Performing internal security self-assessment before production
- Auditing an application after security concerns are raised
- Conducting periodic security reviews
Prerequisites
- A public URL of the application to audit
- Authorization to test the target application (you must own it or have explicit permission)
- Internet access to reach the target URL
Important Security Notice
⚠️ AUTHORIZATION REQUIRED
Before proceeding, you must confirm:
1. I own this application, OR
2. I have explicit written authorization to perform security testing
Unauthorized security testing may violate laws and terms of service.
Type "I confirm I am authorized to test this application" to proceed.
Audit Phases
The orchestrator runs these phases sequentially with confirmation between each.
📁 REMINDER: After EVERY phase, verify that:
.sb-pentest-context.json is updated with phase results.sb-pentest-audit.log has START and COMPLETE entries- Evidence files are saved to
.sb-pentest-evidence/XX-phase/
timeline.md reflects any significant findingscurl-commands.sh contains all HTTP requests made
Phase 0: Initialization
Sets up the audit environment and evidence collection.
Pre-Phase Action (if supported):
- Use
EnterPlanMode if the environment supports it
- This allows the user to validate the audit approach before execution
- If Plan Mode is not available, proceed directly
Actions:
- Create
.sb-pentest-context.json
- Create
.sb-pentest-audit.log
- Create
.sb-pentest-evidence/ directory structure
- Initialize
curl-commands.sh with header
- Initialize
timeline.md with audit start
- Log initialization to
.sb-pentest-audit.log
Skills invoked:
supabase-evidence (initialization)
Verification before proceeding:
Output: Ready to collect evidence with full directory structure
Phase 1: Detection
Determines if the target uses Supabase and extracts basic information.
Skills invoked:
Output: Confirmation of Supabase usage, project URL identified
Evidence saved to: .sb-pentest-evidence/01-detection/
Phase 2: Key Extraction
Scans client-side code for exposed credentials.
Skills invoked:
supabase-extract-urlsupabase-extract-anon-keysupabase-extract-service-keysupabase-extract-jwtsupabase-extract-db-string
Output: List of all discovered credentials with severity assessment
Evidence saved to: .sb-pentest-evidence/02-extraction/
Phase 3: API Audit
Tests PostgREST API exposure and RLS policies.
Skills invoked:
supabase-audit-tables-listsupabase-audit-tables-readsupabase-audit-rlssupabase-audit-rpc
Output: Tables accessible, data exposure assessment, RLS gaps
Evidence saved to: .sb-pentest-evidence/03-api-audit/
Phase 4: Storage Audit
Checks storage bucket configurations and access.
Skills invoked:
supabase-audit-buckets-listsupabase-audit-buckets-readsupabase-audit-buckets-public
Output: Bucket inventory, public exposure, accessible files
Evidence saved to: .sb-pentest-evidence/04-storage-audit/
Phase 5: Auth Audit
Analyzes authentication configuration and potential weaknesses.
Skills invoked:
supabase-audit-auth-configsupabase-audit-auth-signupsupabase-audit-auth-userssupabase-audit-authenticated ← NEW: Creates test user (with consent) to detect IDOR
Output: Auth provider analysis, signup restrictions, enumeration risks, authenticated vs anonymous comparison
Evidence saved to: .sb-pentest-evidence/05-auth-audit/
⚠️ Note: supabase-audit-authenticated will ask for explicit consent before creating a test user. This is optional but highly recommended to detect IDOR and cross-user access vulnerabilities.
Phase 6: Realtime & Functions Audit
Tests WebSocket channels and Edge Functions.
Skills invoked:
supabase-audit-realtimesupabase-audit-functions
Output: Exposed channels, function endpoints, access control issues
Evidence saved to: .sb-pentest-evidence/06-realtime-audit/ and .sb-pentest-evidence/07-functions-audit/
Phase 7: Report Generation
Compiles all findings into a comprehensive report.
Skills invoked:
Output: Full Markdown report with executive summary, findings, and remediation
Workflow with Plan Mode
When Plan Mode is supported, the recommended workflow is:
1. User requests audit → Agent uses EnterPlanMode
2. Agent explores target superficially (detect Supabase, extract URL)
3. Agent writes plan to plan file with:
- Target URL
- Detected Supabase configuration
- Proposed phases to execute
- Estimated scope
4. Agent uses ExitPlanMode → User reviews and approves
5. Agent executes phases with systematic file updates
6. After each phase → Agent confirms files are updated
7. Final report generation
Benefits of Plan Mode:
- User can adjust scope before execution starts
- Better visibility into what will be tested
- Clearer audit trail from planning to execution
Usage
Basic Full Audit (with Plan Mode)
Run a Supabase security audit on https://myapp.example.com
The agent SHOULD:
- Use
EnterPlanMode if available
- Present the audit plan for approval
- Execute with systematic file updates
Basic Full Audit (without Plan Mode)
Run a Supabase security audit on https://myapp.example.com --no-plan
Resume from Phase
Continue Supabase audit from Phase 3 (API Audit)
Skip Specific Phases
Run Supabase audit on https://myapp.example.com, skip auth audit
Context Files and Evidence (MANDATORY)
⚠️ CRITICAL: Updating tracking files and collecting evidence is MANDATORY.
The orchestrator creates and manages:
| File/Directory |
Purpose |
.sb-pentest-context.json |
Stores extracted data between phases |
.sb-pentest-audit.log |
Logs all actions with timestamps |
.sb-pentest-evidence/ |
Evidence directory for professional audits |
Evidence Collection
The orchestrator initializes the evidence directory at the start of every audit:
.sb-pentest-evidence/
├── README.md # Evidence index
├── curl-commands.sh # All reproducible curl commands
├── timeline.md # Chronological findings
├── 01-detection/ # Detection evidence
├── 02-extraction/ # Key extraction evidence
├── 03-api-audit/ # API audit evidence
│ ├── tables/
│ ├── data-samples/
│ ├── rls-tests/
│ └── rpc-tests/
├── 04-storage-audit/ # Storage audit evidence
│ ├── buckets/
│ └── public-url-tests/
├── 05-auth-audit/ # Auth audit evidence
│ ├── signup-tests/
│ └── enumeration-tests/
├── 06-realtime-audit/ # Realtime audit evidence
├── 07-functions-audit/ # Functions audit evidence
└── screenshots/ # Optional screenshots
Each skill MUST save evidence to its respective directory as it works.
Mandatory Update Rules
- After each skill execution,
.sb-pentest-context.json MUST be updated with results
- Every action MUST be logged in
.sb-pentest-audit.log with timestamp
- If files don't exist, they MUST be created at audit start
- Never complete a skill without updating context files
Mandatory Log Format
Each entry in .sb-pentest-audit.log must follow this format:
[YYYY-MM-DD HH:MM:SS] [SKILL_NAME] [STATUS] Message
Example:
[2025-01-31 14:00:00] [supabase-detect] [START] Starting Supabase detection
[2025-01-31 14:00:05] [supabase-detect] [SUCCESS] Supabase detected
[2025-01-31 14:00:05] [supabase-detect] [CONTEXT_UPDATED] .sb-pentest-context.json updated
Context File Structure
{
"target_url": "https://myapp.example.com",
"started_at": "2025-01-31T10:00:00Z",
"authorization_confirmed": true,
"supabase": {
"detected": true,
"project_url": "https://abc123.supabase.co",
"anon_key": "eyJ...",
"service_key_exposed": false
},
"phases_completed": ["detection", "extraction"],
"findings": []
}
Rate Limiting
The orchestrator implements adaptive rate limiting:
- Starts with normal request speed
- If HTTP 429 (Too Many Requests) is detected, backs off exponentially
- Respects Supabase's rate limit headers
Output Format
After each phase:
═══════════════════════════════════════════════════════════
PHASE 2 COMPLETE: Key Extraction
═══════════════════════════════════════════════════════════
Findings:
├── ✅ Anon key found (expected)
├── ❌ P0: Service role key EXPOSED in main.js:1247
└── ⚠️ P1: JWT secret pattern detected
Proceed to Phase 3 (API Audit)? [Y/n]
═══════════════════════════════════════════════════════════
Best Practices
- Run audits in non-production hours to minimize impact
- Save the context file for audit trail purposes
- Review findings with your security team before remediation
- Re-run the audit after implementing fixes to verify
Common Issues
❌ Problem: Audit stops at Phase 1 with "Supabase not detected"
✅ Solution: The app may use a custom domain. Manually provide the Supabase URL:
Run audit with Supabase URL https://myproject.supabase.co
❌ Problem: Rate limited during audit
✅ Solution: The orchestrator auto-adjusts. If persistent, wait 5 minutes and resume.
❌ Problem: Context file corrupted
✅ Solution: Delete .sb-pentest-context.json and restart the audit.
Related Skills
supabase-help — Quick reference for all skillssupabase-evidence — Evidence collection managementsupabase-report — Generate report from existing contextsupabase-report-compare — Compare with previous audits
