Supabase Pentest Skills

<p align="center">
  <img src="https://img.shields.io/badge/Skills-24-brightgreen" alt="24 Skills">
  <img src="https://img.shields.io/badge/License-MIT-blue" alt="MIT License">
  <img src="https://img.shields.io/badge/PRs-Welcome-orange" alt="PRs Welcome">
</p>

<h1 align="center">Supabase Pentest Skills</h1>

<p align="center">
  <strong>24 AI Agent Skills for professional security auditing of Supabase applications.</strong><br>
  Detection, key extraction, RLS testing, IDOR detection, storage audit, evidence collection, comprehensive reporting.
</p>

<p align="center">
  <a href="#quick-install">Install</a> •
  <a href="#all-24-skills">Skills</a> •
  <a href="#example-usage">Usage</a> •
  <a href="#contributing">Contribute</a>
</p>

---

## Quick Install

```bash
npx skills add yoanbernabeu/supabase-pentest-skills
```

**That's it.** Works with Claude Code, Cursor, Codex, OpenCode, Windsurf, and 30+ AI agents.

### One-Liners

```bash
# Install everything (24 skills)
npx skills add yoanbernabeu/supabase-pentest-skills

# Install only detection skills
npx skills add yoanbernabeu/supabase-pentest-skills --skill supabase-detect

# Install globally (available in all projects)
npx skills add yoanbernabeu/supabase-pentest-skills -g

# List all available skills
npx skills add yoanbernabeu/supabase-pentest-skills --list

# Non-interactive (CI/CD friendly)
npx skills add yoanbernabeu/supabase-pentest-skills --all -y
```

---

## Recommended Setup (New Audit)

> **Note**: This setup is optimized for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) users. The CLAUDE.md template provides specific instructions for Claude Code's agent capabilities.

For professional audits with complete logging and evidence collection, follow this setup:

### Step 1: Install the Skills

```bash
npx skills add yoanbernabeu/supabase-pentest-skills
```

### Step 2: Create a Fresh Audit Directory

```bash
mkdir my-security-audit
cd my-security-audit
```

### Step 3: Download the CLAUDE.md Template

This template configures your AI agent for strict logging and systematic execution:

```bash
curl -o CLAUDE.md https://raw.githubusercontent.com/yoanbernabeu/supabase-pentest-skills/main/templates/CLAUDE.md
```

### Step 4: Launch the Audit

Open your AI agent (Claude Code, Cursor, etc.) in the directory and run:

```
/supabase-pentest
```

Or use the detailed prompt for maximum compliance:

```
I need you to run a complete Supabase security audit on https://myapp.example.com

IMPORTANT INSTRUCTIONS:
1. Use Plan Mode (EnterPlanMode) before starting
2. Initialize supabase-evidence skill FIRST
3. Execute ALL 24 audit skills systematically - NO EXCEPTIONS:
   - 1 detection skill
   - 5 extraction skills (url, anon-key, service-key, jwt, db-string)
   - 4 API audit skills (tables-list, tables-read, rls, rpc)
   - 3 storage audit skills (buckets-list, buckets-read, buckets-public)
   - 4 auth audit skills (auth-config, auth-signup, auth-users, authenticated)
   - 1 realtime audit skill
   - 1 functions audit skill
   - 2 reporting skills (report, report-compare if applicable)
4. After EACH skill: update context, log actions, save evidence
5. NEVER skip a phase without explicit user confirmation
6. Generate final report with supabase-report

I confirm I am authorized to test this application.
```

> **Note**: The CLAUDE.md template includes a checklist of all 24 skills that must be executed. The AI agent will follow this checklist systematically.

### Why Use the CLAUDE.md Template?

The template enforces:

| Requirement | Benefit |
|-------------|---------|
| **Mandatory logging** | Complete audit trail for compliance |
| **Systematic execution** | No steps skipped, consistent results |
| **Evidence collection** | Professional-grade proof of findings |
| **Reproducible commands** | All curl commands saved for verification |
| **Timestamped timeline** | Chronological record of all discoveries |

### Directory Structure After Audit

```
my-security-audit/
├── CLAUDE.md                    # Agent configuration (from template)
├── .sb-pentest-context.json     # Shared context between skills
├── .sb-pentest-audit.log        # Complete action log
├── .sb-pentest-evidence/        # Professional evidence collection
│   ├── README.md
│   ├── curl-commands.sh
│   ├── timeline.md
│   ├── 01-detection/
│   ├── 02-extraction/
│   ├── 03-api-audit/
│   ├── 04-storage-audit/
│   ├── 05-auth-audit/
│   ├── 06-realtime-audit/
│   └── 07-functions-audit/
└── supabase-audit-report.md     # Final report
```

---

## What is Supabase Pentest Skills?

A comprehensive toolkit for **internal security auditing** of Supabase-based applications. These skills help development teams:

- **Detect** Supabase usage from public URLs
- **Extract** exposed keys, JWTs, and connection strings
- **Audit** API access, RLS policies, storage buckets, and auth config
- **Report** findings with severity levels and remediation guidance

### Important Notice

These skills are designed for **internal self-assessment by authorized development teams only**. Before running any audit:

1. You must own or have explicit authorization to test the target application
2. Tests are read-only (no write/delete operations)
3. All actions are logged for audit trail

---

## Security Model

| Aspect | Implementation |
|--------|----------------|
| **Access** | Public URL analysis only (HTML, JS, network) |
| **Operations** | Read-only (no write/delete) |
| **Rate Limiting** | Adaptive (slows down if throttled) |
| **Logging** | Full audit trail in `.sb-pentest-audit.log` |
| **Context** | Shared via `.sb-pentest-context.json` |
| **Evidence** | Professional-grade evidence in `.sb-pentest-evidence/` |
| **Authorization** | Explicit ownership confirmation required |

---

## All 24 Skills

### Orchestration & Help
| Skill | What It Does |
|-------|--------------|
| `supabase-pentest` | Orchestrator: guided step-by-step security audit |
| `supabase-evidence` | Professional evidence collection management |
| `supabase-help` | Quick reference and usage examples |

### Detection
| Skill | What It Does |
|-------|--------------|
| `supabase-detect` | Detect if a web application uses Supabase |

### Key Extraction
| Skill | What It Does |
|-------|--------------|
| `supabase-extract-url` | Extract Supabase project URL from client code |
| `supabase-extract-anon-key` | Extract anon/public API key |
| `supabase-extract-service-key` | Detect leaked service_role key (critical!) |
| `supabase-extract-jwt` | Extract and decode Supabase JWTs |
| `supabase-extract-db-string` | Detect exposed database connection strings |

### API Audit
| Skill | What It Does |
|-------|--------------|
| `supabase-audit-tables-list` | List tables exposed via PostgREST |
| `supabase-audit-tables-read` | Attempt to read data from exposed tables |
| `supabase-audit-rls` | Test Row Level Security policies |
| `supabase-audit-rpc` | List and test exposed RPC functions |

### Storage Audit
| Skill | What It Does |
|-------|--------------|
| `supabase-audit-buckets-list` | List storage buckets |
| `supabase-audit-buckets-read` | Attempt to read files from buckets |
| `supabase-audit-buckets-public` | Detect misconfigured public buckets |

### Auth Audit
| Skill | What It Does |
|-------|--------------|
| `supabase-audit-auth-config` | Analyze authentication configuration |
| `supabase-audit-auth-signup` | Test if signup is open/unrestricted |
| `supabase-audit-auth-users` | Attempt user enumeration |
| `supabase-audit-authenticated` | **Create test user to detect IDOR & cross-user access** |

### Realtime & Functions Audit
| Skill | What It Does |
|-------|--------------|
| `supabase-audit-realtime` | Test exposed Realtime channels |
| `supabase-audit-functions` | List and test Edge Functions |

### Reporting
| Skill | What It Does |
|-------|--------------|
| `supabase-report` | Generate comprehensive Markdown report |
| `supabase-report-compare` | Compare two reports to track progress |

---

## Skill Packs

Install skills by category:

| Pack | Skills | Description |
|------|--------|-------------|
| `supabase-orchestration` | 3 | Main orchestrator, evidence, and help |
| `supabase-detection` | 1 | Supabase detection |
| `supabase-extraction` | 5 | Key and credential extraction |
| `supabase-audit-api` | 4 | API and RLS testing |
| `supabase-audit-storage` | 3 | Storage bucket auditing |
| `supabase-audit-auth` | 4 | Authentication testing + IDOR detection |
| `supabase-audit-realtime` | 1 | Realtime channel testing |
| `supabase-audit-functions` | 1 | Edge Functions testing |
| `supabase-report` | 2 | Report generation |
| **`supabase-complete`** | **24** | **All skills — complete toolkit** |

---

## Severity Levels

| Level | Description | Examples |
|-------|-------------|----------|
| **P0** | Critical data exposure, user data, privilege escalation | Service key leaked, full DB access, user enumeration |
| **P1** | Sensitive data exposure, security misconfiguration | Weak RLS, unprotected buckets, open signup |
| **P2** | Minor exposure, best practice violations | Verbose errors, unused endpoints exposed |

---

## Example Usage

### Full Security Audit

```
"Run a complete Supabase security audit on https://myapp.com"
```

### Targeted Checks

```
"Check if https://myapp.com uses Supabase"

"Extract all Supabase keys from https://myapp.com"

"Test RLS policies on my Supabase app"

"Check if any storage buckets are misconfigured"

"Generate a security report for my last audit"
```

### Compare Progress

```
"Compare my current audit with last month's report"
```

### Recommended Prompt for Maximum Compliance

For the most thorough audit with strict adherence to all procedures, use this detailed prompt:

```
I need you to run a complete Supabase security audit on https://myapp.example.com

IMPORTANT INSTRUCTIONS:
1. Use Plan Mode (EnterPlanMode) before starting if available
2. Initialize the supabase-evidence skill FIRST to set up evidence collection
3. Execute ALL audit skills systematically in order (detection → extraction → API → storage → auth → realtime → functions)
4. After EACH skill execution, you MUST:
   - Update .sb-pentest-context.json with findings
   - Log the action to .sb-pentest-audit.log
   - Save evidence to .sb-pentest-evidence/
   - Update timeline.md for any P0/P1/P2 finding
   - Append curl commands to curl-commands.sh
5. NEVER skip a phase without explicit confirmation
6. Generate the final report with supabase-report

I confirm I am authorized to test this application.
```

This prompt ensures:
- ✅ Plan Mode activation for better traceability
- ✅ Proper evidence collection initialization
- ✅ Systematic execution of all 24 skills
- ✅ Progressive file updates (crash-resistant)
- ✅ Complete audit trail for compliance

---

## Report Format

Reports include:

1. **Executive Summary** — 5-10 lines, risk overview, score
2. **Security Score** — 0-100 with letter grade
3. **Findings by Severity** — P0, P1, P2 issues
4. **Detailed Analysis** — Per-component breakdown
5. **Remediation Guidance** — Fix suggestions + code examples + docs links

Example output:

```markdown
# Supabase Security Audit Report

## Executive Summary
Security Score: 45/100 (Grade: D)
- 2 P0 (Critical) issues found
- 3 P1 (High) issues found
- 5 P2 (Medium) issues found

## Critical Findings (P0)
### 1. Service Role Key Exposed
**Severity:** P0 - Critical
**Location:** /static/js/main.js:1247
**Impact:** Full database access without RLS
**Remediation:**
- Rotate key immediately in Supabase Dashboard
- Remove from client code
- Use Edge Functions for privileged operations
...
```

---

## Files Generated

| File/Directory | Purpose |
|----------------|---------|
| `.sb-pentest-context.json` | Shared context between skills |
| `.sb-pentest-audit.log` | Detailed action log |
| `.sb-pentest-evidence/` | **Professional evidence collection** |
| `supabase-audit-report.md` | Final report |

---

## Professional Evidence Collection

Every audit generates a complete evidence directory for professional reports:

```
.sb-pentest-evidence/
├── README.md                    # Evidence index and summary
├── curl-commands.sh             # All reproducible curl commands
├── timeline.md                  # Chronological findings timeline
│
├── 01-detection/                # Detection evidence
│   └── initial-scan.json
├── 02-extraction/               # Key extraction evidence
│   ├── extracted-anon-key.json
│   └── service-key-exposure/    # P0 findings with proof
├── 03-api-audit/                # API audit evidence
│   ├── tables/
│   ├── data-samples/            # Redacted 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
```

### Evidence Features

- **Reproducible**: All curl commands saved for verification
- **Timestamped**: Complete timeline of findings
- **Redacted**: Sensitive data automatically masked
- **Professional**: Ready for compliance and legal purposes

---

## Contributing

Contributions welcome! Please ensure all new skills:

1. Follow the existing SKILL.md format
2. Include practical examples
3. Document remediation steps with code
4. Reference official Supabase documentation

---

## License

[MIT](LICENSE) — For internal security assessment only.

---

<p align="center">
  <strong>Built for developers who take security seriously.</strong><br><br>
  <a href="https://github.com/yoanbernabeu/supabase-pentest-skills">Star this repo</a> if it helps secure your apps!
</p>