home / skills / yoanbernabeu / supabase-pentest-skills / supabase-evidence

supabase-evidence skill

This skill initializes and manages progressive evidence collection for professional security audits, ensuring immediate evidence saving and organized reporting.

npx playbooks add skill yoanbernabeu/supabase-pentest-skills --skill supabase-evidence

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

11.5 KB

---
name: supabase-evidence
description: Initialize and manage the evidence collection directory for professional security audits with documented proof of findings.
---

# Evidence Collection Management

> 🔴 **CRITICAL: PROGRESSIVE FILE UPDATES REQUIRED**
>
> You MUST write evidence files **AS YOU GO**, not just at the end.
> - Save each piece of evidence **IMMEDIATELY after collection**
> - **DO NOT** wait until the skill completes to save evidence
> - If the audit crashes or is interrupted, all prior evidence must already be saved
>
> **This is not optional. Failure to save evidence progressively is a critical error.**

This skill initializes and manages the evidence collection system for professional security audits.

## When to Use This Skill

- Automatically invoked at the start of `supabase-pentest`
- When you need to organize evidence for a professional report
- When conducting audits that require documented proof
- For compliance and legal purposes

## Why Evidence Collection Matters

Professional security audits require:

| Requirement | Purpose |
|-------------|---------|
| **Reproducibility** | Others can verify findings |
| **Legal proof** | Documentation for legal/compliance |
| **Remediation verification** | Prove issues existed before fix |
| **Audit trail** | Complete record of what was tested |

## Evidence Directory Structure

The skill creates `.sb-pentest-evidence/` with this structure:

```
.sb-pentest-evidence/
├── README.md                    # Evidence index and summary
├── curl-commands.sh             # All curl commands used (reproducible)
├── timeline.md                  # Chronological evidence timeline
│
├── 01-detection/
│   ├── initial-scan.json        # Raw detection results
│   ├── supabase-endpoints.txt   # Discovered endpoints
│   └── client-code-snippets/    # Relevant code excerpts
│       └── supabase-init.js
│
├── 02-extraction/
│   ├── extracted-url.json       # URL extraction proof
│   ├── extracted-anon-key.json  # Anon key with decoded JWT
│   ├── extracted-jwts.json      # All JWTs found
│   ├── service-key-exposure/    # If service key found (P0)
│   │   ├── location.txt
│   │   └── decoded-payload.json
│   └── db-string-exposure/      # If DB string found (P0)
│       └── connection-details.json
│
├── 03-api-audit/
│   ├── openapi-schema.json      # Raw OpenAPI/PostgREST schema
│   ├── tables/
│   │   ├── tables-list.json     # All exposed tables
│   │   └── tables-metadata.json # Column details per table
│   ├── data-samples/            # Sample data retrieved (redacted)
│   │   ├── users-sample.json
│   │   ├── orders-sample.json
│   │   └── ...
│   ├── rls-tests/               # RLS policy test results
│   │   ├── users-anon.json      # Anon access attempt
│   │   ├── users-auth.json      # Authenticated access
│   │   └── cross-user-test.json # Cross-user access attempt
│   └── rpc-tests/               # RPC function test results
│       ├── function-list.json
│       └── vulnerable-functions/
│           └── get-all-users.json
│
├── 04-storage-audit/
│   ├── buckets-config.json      # Bucket configurations
│   ├── buckets/
│   │   ├── avatars/
│   │   │   └── file-list.json
│   │   ├── backups/             # If sensitive (P0)
│   │   │   ├── file-list.json
│   │   │   └── sample-contents/ # Redacted samples
│   │   └── ...
│   └── public-url-tests/        # Direct URL access tests
│       └── backup-access.json
│
├── 05-auth-audit/
│   ├── auth-settings.json       # Auth configuration
│   ├── signup-tests/
│   │   ├── open-signup.json     # Signup availability
│   │   ├── weak-password.json   # Weak password test
│   │   └── rate-limit.json      # Rate limiting test
│   └── enumeration-tests/
│       ├── login-timing.json    # Timing attack data
│       ├── recovery-timing.json
│       └── otp-enumeration.json
│
├── 06-realtime-audit/
│   ├── websocket-connection.json
│   ├── postgres-changes/        # Table subscription tests
│   │   └── users-streaming.json
│   ├── broadcast-channels/      # Channel access tests
│   │   └── admin-channel.json
│   └── presence-data/
│       └── exposed-users.json
│
├── 07-functions-audit/
│   ├── discovered-functions.json
│   └── function-tests/
│       ├── hello-world.json
│       ├── get-user-data-idor.json
│       └── admin-panel-escalation.json
│
└── screenshots/                 # Optional: browser screenshots
    └── ...
```

## Usage

### Initialize Evidence Directory

```
Initialize evidence collection for audit
```

### Manual Evidence Save

```
Save evidence: [description] to [category]
```

## Evidence File Format

Each evidence file follows this structure:

```json
{
  "evidence_id": "API-001",
  "timestamp": "2025-01-31T10:30:00Z",
  "category": "api-audit",
  "type": "data-sample",
  "finding_id": "P0-001",
  "description": "Users table data accessible without authentication",

  "request": {
    "method": "GET",
    "url": "https://abc123.supabase.co/rest/v1/users?select=*&limit=5",
    "headers": {
      "apikey": "[REDACTED - anon key]",
      "Authorization": "Bearer [REDACTED - anon key]"
    },
    "curl_command": "curl -X GET 'https://abc123.supabase.co/rest/v1/users?select=*&limit=5' -H 'apikey: eyJ...' -H 'Authorization: Bearer eyJ...'"
  },

  "response": {
    "status": 200,
    "headers": {
      "content-type": "application/json",
      "x-total-count": "1247"
    },
    "body": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "email": "[REDACTED]@example.com",
        "name": "[REDACTED]",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "body_redacted": true,
    "total_rows_indicated": 1247
  },

  "analysis": {
    "severity": "P0",
    "impact": "All user PII accessible without authentication",
    "affected_data": ["email", "name", "id"],
    "row_count": 1247
  }
}
```

## Curl Commands File

All curl commands are collected in `curl-commands.sh`:

```bash
#!/bin/bash
# Supabase Security Audit - Reproducible Commands
# Target: https://myapp.example.com
# Project: abc123def.supabase.co
# Date: 2025-01-31
#
# IMPORTANT: Replace [ANON_KEY] with actual key before running
# WARNING: These commands may modify data - use with caution

SUPABASE_URL="https://abc123def.supabase.co"
ANON_KEY="eyJ..."

# === DETECTION ===
# Check if Supabase is used
curl -s "$SUPABASE_URL/rest/v1/" -H "apikey: $ANON_KEY" | head -100

# === TABLE LISTING ===
# Get OpenAPI schema (list all tables)
curl -s "$SUPABASE_URL/rest/v1/" -H "apikey: $ANON_KEY"

# === DATA ACCESS TESTS ===
# Test: Users table (P0 - should be blocked)
curl -s "$SUPABASE_URL/rest/v1/users?select=*&limit=5" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ANON_KEY"

# Test: Orders table (should be blocked by RLS)
curl -s "$SUPABASE_URL/rest/v1/orders?select=*&limit=5" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ANON_KEY"

# === RLS BYPASS TESTS ===
# ... additional commands ...
```

## Timeline File

The `timeline.md` provides chronological evidence:

```markdown
# Audit Timeline

## 2025-01-31 10:00:00 - Audit Started
- Target: https://myapp.example.com
- Authorization confirmed

## 2025-01-31 10:05:00 - Detection Phase
- Supabase detected with high confidence
- Project URL: https://abc123def.supabase.co
- Evidence: `01-detection/initial-scan.json`

## 2025-01-31 10:10:00 - P0 CRITICAL: Service Key Exposed
- Service role key found in client code
- Location: /static/js/admin.chunk.js:89
- Evidence: `02-extraction/service-key-exposure/`

## 2025-01-31 10:15:00 - API Audit Started
- 8 tables discovered
- Evidence: `03-api-audit/tables/tables-list.json`

## 2025-01-31 10:20:00 - P0 CRITICAL: Users Table Exposed
- All 1,247 user records accessible
- PII exposed: email, name
- Evidence: `03-api-audit/data-samples/users-sample.json`

...
```

## Context Output

Updates `.sb-pentest-context.json`:

```json
{
  "evidence": {
    "directory": ".sb-pentest-evidence",
    "initialized_at": "2025-01-31T10:00:00Z",
    "files_count": 45,
    "categories": {
      "detection": 3,
      "extraction": 5,
      "api-audit": 15,
      "storage-audit": 8,
      "auth-audit": 7,
      "realtime-audit": 4,
      "functions-audit": 3
    },
    "critical_evidence": [
      "02-extraction/service-key-exposure/",
      "03-api-audit/data-samples/users-sample.json",
      "04-storage-audit/buckets/backups/"
    ]
  }
}
```

## Evidence Collection Rules

### What to Collect

| Category | Evidence Type | Example |
|----------|---------------|---------|
| **Always** | Raw API responses | JSON responses |
| **Always** | Curl commands | Reproducible commands |
| **Always** | Timestamps | When each test occurred |
| **P0/P1** | Data samples (redacted) | Sample rows with PII masked |
| **P0** | Full request/response | Complete HTTP exchange |
| **Optional** | Screenshots | Browser evidence |

### Redaction Rules

Sensitive data MUST be redacted in evidence files:

```json
{
  "original": "[email protected]",
  "redacted": "[REDACTED]@example.com"
}

{
  "original": "John Doe",
  "redacted": "[REDACTED]"
}

{
  "original": "sk_live_xxxxxxxxxxxxxxxxxxxx",
  "redacted": "sk_live_[REDACTED]"
}
```

**NEVER store in evidence:**
- Actual passwords
- Full credit card numbers
- Full API keys (show first/last 4 chars only)
- Full personal data (partial redaction required)

### Naming Conventions

```
[category]-[test-name]-[timestamp].json
```

Examples:
- `users-anon-access-20250131-103000.json`
- `admin-function-no-auth-20250131-143000.json`

## MANDATORY: Evidence File Updates

⚠️ **Evidence MUST be saved PROGRESSIVELY during execution.**

### Critical Rule: Save As You Go

**DO NOT** batch all evidence at the end. Instead:

1. **Before each test** → Create evidence file placeholder
2. **After each request** → Save request details immediately
3. **After each response** → Save response immediately
4. **After analysis** → Add analysis to evidence file

### Directory Initialization

At audit start, create:

```bash
mkdir -p .sb-pentest-evidence/{01-detection,02-extraction,03-api-audit/tables,03-api-audit/data-samples,03-api-audit/rls-tests,03-api-audit/rpc-tests,04-storage-audit/buckets,04-storage-audit/public-url-tests,05-auth-audit/signup-tests,05-auth-audit/enumeration-tests,06-realtime-audit/postgres-changes,06-realtime-audit/broadcast-channels,07-functions-audit/function-tests,screenshots}
```

### Log to Audit Log

```
[TIMESTAMP] [supabase-evidence] [START] Initializing evidence directory
[TIMESTAMP] [supabase-evidence] [CREATED] .sb-pentest-evidence/
[TIMESTAMP] [supabase-evidence] [CONTEXT_UPDATED] Evidence tracking initialized
```

## Integration with Other Skills

This skill is automatically invoked by `supabase-pentest`. Each audit skill should:

1. Save evidence to the appropriate subdirectory
2. Use consistent naming conventions
3. Add entries to `curl-commands.sh`
4. Update `timeline.md` for significant findings

## Related Skills

- `supabase-pentest` — Orchestrator that initializes evidence collection
- `supabase-report` — Uses evidence for comprehensive reporting
- All audit skills — Contribute evidence to their respective directories

Overview

This skill initializes and manages a progressive evidence collection directory for professional Supabase security audits. It ensures every request, response, command, and analysis is saved immediately during the audit to preserve reproducibility and legal proof. The structure, naming, and redaction rules are enforced so evidence is consistent and safe for reporting.

How this skill works

On start it creates a standardized .sb-pentest-evidence/ tree and placeholders for each test category. During the audit it writes evidence files incrementally: request placeholders before tests, request/response pairs immediately after each interaction, and analysis entries once a finding is evaluated. It also appends reproducible curl commands, updates a chronological timeline, and maintains a context file summarizing evidence counts and critical items.

When to use it

Automatically at the start of a supabase-pentest run
When you need auditable, reproducible proof of findings
For compliance, legal, or remediation verification purposes
While running any Supabase audit sub-skill that produces API/storage/auth evidence
When building a report that must reference primary evidence files

Best practices

Always save evidence progressively — create placeholders before tests and write results immediately after
Use the provided directory structure and naming conventions for consistent indexing
Redact sensitive values per rules: mask PII and only show key prefixes/suffixes
Collect raw API responses, curl commands, timestamps, and analysis for each test
Append a short timeline entry for every significant finding to maintain chronological context

Example use cases

Start-of-audit initialization for a full Supabase pentest to collect reproducible artifacts
Capturing a P0 service-key exposure with full request/response and decoded payload saved immediately
Recording RLS test attempts: save anon vs. authenticated responses and analysis per test
Collecting storage bucket listings and direct URL access tests with sample redacted file contents
Generating curl-commands.sh entries while performing API enumeration so investigators can reproduce steps

FAQ

What must I do if the audit process is interrupted?

Because evidence is saved progressively, previous files remain intact; resume by continuing to append new evidence and update timeline and context files.

How should sensitive data be stored in evidence files?

Redact personal data and secrets: mask PII, never store full passwords or API keys (show only first/last 4 chars), and mark redacted fields clearly in evidence JSON.