---
name: supabase-pentest
description: Orchestrate a complete Supabase security audit with guided step-by-step execution and ownership confirmation.
---

# 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:**

1. Create `.sb-pentest-context.json` if it doesn't exist
2. Create `.sb-pentest-audit.log` if it doesn't exist
3. Create `.sb-pentest-evidence/` directory structure
4. Initialize context with target URL and timestamp

**DURING execution - WRITE AS YOU GO:**

1. **BEFORE each action** → Log to `.sb-pentest-audit.log`
2. **AFTER each discovery** → IMMEDIATELY update `.sb-pentest-context.json`
3. **AFTER each test** → Save evidence to `.sb-pentest-evidence/`
4. **DO NOT batch writes** → Each finding must be saved as it's discovered
5. **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:

- [ ] `.sb-pentest-context.json` contains all discoveries from current phase
- [ ] `.sb-pentest-audit.log` has entries for all actions performed
- [ ] Evidence files exist in `.sb-pentest-evidence/XX-phase-name/`
- [ ] `timeline.md` is updated with any P0/P1/P2 findings
- [ ] `curl-commands.sh` contains all HTTP requests made

**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 findings
> - `curl-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:**
- [ ] All 4 tracking files exist
- [ ] Evidence directory structure is complete
- [ ] User authorization confirmed

**Output:** Ready to collect evidence with full directory structure

### Phase 1: Detection
Determines if the target uses Supabase and extracts basic information.

**Skills invoked:**
- `supabase-detect`

**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-url`
- `supabase-extract-anon-key`
- `supabase-extract-service-key`
- `supabase-extract-jwt`
- `supabase-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-list`
- `supabase-audit-tables-read`
- `supabase-audit-rls`
- `supabase-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-list`
- `supabase-audit-buckets-read`
- `supabase-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-config`
- `supabase-audit-auth-signup`
- `supabase-audit-auth-users`
- `supabase-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-realtime`
- `supabase-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:**
- `supabase-report`

**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:
1. Use `EnterPlanMode` if available
2. Present the audit plan for approval
3. 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

1. **After each skill execution**, `.sb-pentest-context.json` MUST be updated with results
2. **Every action** MUST be logged in `.sb-pentest-audit.log` with timestamp
3. **If files don't exist**, they MUST be created at audit start
4. **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

```json
{
  "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:

1. Starts with normal request speed
2. If HTTP 429 (Too Many Requests) is detected, backs off exponentially
3. 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 skills
- `supabase-evidence` — Evidence collection management
- `supabase-report` — Generate report from existing context
- `supabase-report-compare` — Compare with previous audits