supascan 0.0.1

package/README.md

@@ -0,0 +1,165 @@
+# supascan
+
+A security analysis CLI tool for Supabase databases that helps identify exposed data, analyze schemas, and test RPC functions.
+
+## Installation
+
+```bash
+npm install -g supascan
+```
+
+## Usage
+
+### Basic Analysis
+
+Analyze your Supabase database for security issues:
+
+```bash
+supascan --url https://your-project.supabase.co --key your-anon-key
+```
+
+### Available Commands
+
+#### Database Analysis
+
+```bash
+# Analyze all schemas
+supascan --url <url> --key <key>
+
+# Analyze specific schema
+supascan --url <url> --key <key> --schema public
+
+# Generate HTML report
+supascan --url <url> --key <key> --html
+
+# JSON output
+supascan --url <url> --key <key> --json
+```
+
+#### Data Dumping
+
+```bash
+# Dump table data
+supascan --url <url> --key <key> --dump public.users --limit 100
+
+# Dump Swagger JSON for schema
+supascan --url <url> --key <key> --dump public
+```
+
+#### RPC Testing
+
+```bash
+# Get RPC help
+supascan --url <url> --key <key> --rpc public.get_user_stats
+
+# Call RPC with parameters
+supascan --url <url> --key <key> --rpc public.get_user_stats --args '{"user_id": "123"}'
+
+# Show query execution plan
+supascan --url <url> --key <key> --rpc public.get_user_stats --args '{"user_id": "123"}' --explain
+```
+
+#### Credential Extraction (Experimental)
+
+```bash
+# Extract credentials from JS file
+supascan --extract https://example.com/app.js --url <url> --key <key>
+```
+
+## Options
+
+| Option                             | Description                                                      |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `-u, --url <url>`                  | Supabase URL                                                     |
+| `-k, --key <key>`                  | Supabase anon key                                                |
+| `-s, --schema <schema>`            | Schema to analyze (default: all schemas)                         |
+| `-x, --extract <url>`              | Extract credentials from JS file URL (experimental)              |
+| `--dump <schema.table\|schema>`    | Dump data from specific table or swagger JSON from schema        |
+| `--limit <number>`                 | Limit rows for dump or RPC results (default: 10)                 |
+| `--rpc <schema.rpc_name>`          | Call an RPC function (read-only operations only)                 |
+| `--args <json>`                    | JSON arguments for RPC call (use $VAR for environment variables) |
+| `--json`                           | Output as JSON                                                   |
+| `--html`                           | Generate HTML report                                             |
+| `-d, --debug`                      | Enable debug mode                                                |
+| `--explain`                        | Show query execution plan                                        |
+| `--suppress-experimental-warnings` | Suppress experimental warnings                                   |
+
+## What supascan Analyzes
+
+### Database Security Assessment
+
+- **Schema Discovery**: Automatically discovers all available schemas
+- **Table Access Analysis**: Identifies which tables are:
+  - ✅ **Readable** - Data is exposed and accessible
+  - ⚠️ **Empty/Protected** - No data or protected by RLS
+  - ❌ **Denied** - Access is explicitly denied
+
+### JWT Token Analysis
+
+- Parses and displays JWT token information
+- Shows issuer, audience, expiration, and role information
+
+### RPC Function Analysis
+
+- Lists all available RPC functions
+- Shows parameter requirements and types
+- Validates parameters before execution
+
+### Output Formats
+
+- **Console**: Colorized terminal output with detailed analysis
+- **JSON**: Machine-readable output for scripting
+- **HTML**: Visual report that opens in your browser
+
+## Examples
+
+### Security Analysis Report
+
+```bash
+supascan --url https://abc123.supabase.co --key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... --html
+```
+
+### Check Specific Table Access
+
+```bash
+supascan --url https://abc123.supabase.co --key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... --dump public.users --limit 5
+```
+
+### Test RPC Function
+
+```bash
+supascan --url https://abc123.supabase.co --key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... --rpc public.get_user_count --args '{"active": true}'
+```
+
+## Security Considerations
+
+⚠️ **Important**: This tool is designed for security analysis and testing. Only use it on:
+
+- Your own databases
+- Databases you have explicit permission to test
+- Staging/development environments
+
+Never use this tool on production databases without proper authorization.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run locally
+bun run start
+
+# Build
+bun run build
+
+# Test
+bun test
+
+# Lint
+bun run lint
+```
+
+## License
+
+Private - All rights reserved.

package/commands/analyze.command.ts

@@ -0,0 +1,187 @@
+import pc from "picocolors";
+import type { CLIContext } from "../context";
+import {
+  AnalyzerService,
+  type AnalysisResult,
+} from "../services/analyzer.service";
+import { HtmlRendererService } from "../services/html-renderer.service";
+import {
+  generateTempFilePath,
+  log,
+  openInBrowser,
+  writeHtmlFile,
+} from "../utils";
+
+export async function executeAnalyzeCommand(
+  ctx: CLIContext,
+  options: { schema?: string },
+): Promise<void> {
+  const analysisResult = await AnalyzerService.analyze(ctx, options.schema);
+
+  if (!analysisResult.success) {
+    log.error("Analysis failed", analysisResult.error.message);
+    process.exit(1);
+  }
+
+  if (ctx.json) {
+    console.log(JSON.stringify(analysisResult.value, null, 2));
+  } else if (ctx.html) {
+    const htmlContent = HtmlRendererService.generateHtmlReport(
+      analysisResult.value,
+      ctx.url,
+      ctx.key,
+    );
+    const filePath = generateTempFilePath();
+    writeHtmlFile(filePath, htmlContent);
+    openInBrowser(filePath);
+    log.success(`HTML report generated: ${filePath}`);
+  } else {
+    displayAnalysisResult(analysisResult.value);
+  }
+}
+
+function displayAnalysisResult(result: AnalysisResult): void {
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log(pc.bold(pc.cyan("  SUPABASE DATABASE ANALYSIS")));
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+
+  console.log(pc.bold(pc.yellow("TARGET SUMMARY")));
+  console.log(pc.dim("─".repeat(20)));
+  console.log(pc.bold("Domain:"), pc.white(result.summary.domain));
+
+  if (result.summary.metadata?.service) {
+    console.log(pc.bold("Service:"), pc.white(result.summary.metadata.service));
+  }
+
+  if (result.summary.metadata?.region) {
+    console.log(
+      pc.bold("Project ID:"),
+      pc.white(result.summary.metadata.region),
+    );
+  }
+
+  if (result.summary.metadata?.title) {
+    console.log(pc.bold("Title:"), pc.white(result.summary.metadata.title));
+  }
+
+  if (result.summary.metadata?.version) {
+    console.log(pc.bold("Version:"), pc.white(result.summary.metadata.version));
+  }
+
+  if (result.summary.jwtInfo) {
+    console.log();
+    console.log(pc.bold(pc.yellow("JWT TOKEN INFO")));
+    console.log(pc.dim("─".repeat(20)));
+
+    if (result.summary.jwtInfo.iss) {
+      console.log(pc.bold("Issuer:"), pc.white(result.summary.jwtInfo.iss));
+    }
+    if (result.summary.jwtInfo.aud) {
+      console.log(pc.bold("Audience:"), pc.white(result.summary.jwtInfo.aud));
+    }
+    if (result.summary.jwtInfo.role) {
+      console.log(pc.bold("Role:"), pc.white(result.summary.jwtInfo.role));
+    }
+    if (result.summary.jwtInfo.exp) {
+      const expDate = new Date(result.summary.jwtInfo.exp * 1000);
+      console.log(pc.bold("Expires:"), pc.white(expDate.toISOString()));
+    }
+    if (result.summary.jwtInfo.iat) {
+      const iatDate = new Date(result.summary.jwtInfo.iat * 1000);
+      console.log(pc.bold("Issued:"), pc.white(iatDate.toISOString()));
+    }
+  }
+
+  console.log();
+  console.log(pc.bold(pc.cyan("DATABASE ANALYSIS")));
+  console.log(pc.dim("─".repeat(20)));
+  console.log(
+    pc.bold("Schemas discovered:"),
+    pc.green(result.schemas.length.toString()),
+  );
+  console.log();
+
+  Object.entries(result.schemaDetails).forEach(([schema, analysis]) => {
+    console.log(pc.bold(pc.cyan(`Schema: ${schema}`)));
+    console.log();
+
+    const exposedCount = Object.values(analysis.tableAccess).filter(
+      (a) => a.status === "readable",
+    ).length;
+    const deniedCount = Object.values(analysis.tableAccess).filter(
+      (a) => a.status === "denied",
+    ).length;
+    const emptyCount = Object.values(analysis.tableAccess).filter(
+      (a) => a.status === "empty",
+    ).length;
+
+    console.log(
+      pc.bold("Tables:"),
+      pc.green(analysis.tables.length.toString()),
+    );
+    console.log(
+      pc.dim(
+        `  ${exposedCount} exposed • ${emptyCount} empty/protected • ${deniedCount} denied`,
+      ),
+    );
+    console.log();
+
+    if (analysis.tables.length > 0) {
+      analysis.tables.forEach((table) => {
+        const access = analysis.tableAccess[table];
+        let indicator = "";
+        let description = "";
+
+        switch (access?.status) {
+          case "readable":
+            indicator = pc.green("✓");
+            description = pc.dim("(data exposed)");
+            break;
+          case "empty":
+            indicator = pc.yellow("○");
+            description = pc.dim("(0 rows - empty or RLS)");
+            break;
+          case "denied":
+            indicator = pc.red("✗");
+            description = pc.dim("(access denied)");
+            break;
+        }
+
+        console.log(`  ${indicator} ${pc.white(table)} ${description}`);
+      });
+    } else {
+      console.log(pc.dim("  No tables found"));
+    }
+    console.log();
+
+    console.log(pc.bold("RPCs:"), pc.green(analysis.rpcs.length.toString()));
+    if (analysis.rpcFunctions.length > 0) {
+      analysis.rpcFunctions.forEach((rpc) => {
+        console.log(`  • ${pc.white(rpc.name)}`);
+        if (rpc.parameters.length > 0) {
+          rpc.parameters.forEach((param) => {
+            const required = param.required
+              ? pc.red("(required)")
+              : pc.dim("(optional)");
+            const type = param.format
+              ? `${param.type} (${param.format})`
+              : param.type;
+            console.log(
+              `    - ${pc.cyan(param.name)}: ${pc.yellow(type)} ${required}`,
+            );
+          });
+        } else {
+          console.log(pc.dim("    No parameters"));
+        }
+      });
+    } else {
+      console.log(pc.dim("  No RPCs found"));
+    }
+    console.log();
+  });
+
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+}

package/commands/dump.command.ts

@@ -0,0 +1,98 @@
+import pc from "picocolors";
+import type { CLIContext } from "../context";
+import { SupabaseService } from "../services/supabase.service";
+import { log } from "../utils";
+
+export async function executeDumpCommand(
+  ctx: CLIContext,
+  options: {
+    dump: string;
+    limit: string;
+  },
+): Promise<void> {
+  const parts = options.dump.split(".");
+
+  if (parts.length === 1 && parts[0]) {
+    const schema = parts[0];
+
+    const swaggerResult = await SupabaseService.getSwagger(ctx, schema);
+
+    if (!swaggerResult.success) {
+      log.error("Failed to get swagger", swaggerResult.error.message);
+      process.exit(1);
+    }
+
+    if (ctx.json) {
+      console.log(JSON.stringify(swaggerResult.value, null, 2));
+    } else {
+      displaySwaggerResult(schema, swaggerResult.value);
+    }
+    return;
+  }
+
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    log.error("Invalid format. Use: schema.table or schema");
+    process.exit(1);
+  }
+
+  const schema = parts[0];
+  const table = parts[1];
+  const limit = parseInt(options.limit);
+
+  const dumpResult = await SupabaseService.dumpTable(ctx, schema, table, limit);
+
+  if (!dumpResult.success) {
+    log.error("Failed to dump table", dumpResult.error.message);
+    process.exit(1);
+  }
+
+  if (ctx.json) {
+    console.log(JSON.stringify(dumpResult.value, null, 2));
+  } else {
+    displayTableDumpResult(schema, table, dumpResult.value);
+  }
+}
+
+function displaySwaggerResult(schema: string, swagger: any): void {
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log(pc.bold(pc.cyan(`  SWAGGER DUMP: ${schema}`)));
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+  console.log(JSON.stringify(swagger, null, 2));
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+}
+
+function displayTableDumpResult(
+  schema: string,
+  table: string,
+  result: {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    count: number;
+  },
+): void {
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log(pc.bold(pc.cyan(`  TABLE DUMP: ${schema}.${table}`)));
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+  console.log(pc.bold("Total rows:"), pc.green(result.count.toString()));
+  console.log(pc.bold("Showing:"), pc.green(result.rows.length.toString()));
+  console.log(pc.bold("Columns:"), pc.green(result.columns.length.toString()));
+  console.log();
+  console.log(pc.dim(result.columns.join(", ")));
+  console.log();
+
+  if (result.rows.length > 0) {
+    console.table(result.rows);
+  } else {
+    console.log(pc.dim("No rows found"));
+  }
+
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+}

package/commands/rpc.command.ts

@@ -0,0 +1,205 @@
+import pc from "picocolors";
+import type { CLIContext } from "../context";
+import {
+  SupabaseService,
+  type RPCFunction,
+  type RPCParameter,
+} from "../services/supabase.service";
+import { log, parseRPCArgs } from "../utils";
+
+export async function executeRPCCommand(
+  ctx: CLIContext,
+  options: {
+    rpc: string;
+    args?: string;
+    limit: string;
+    explain?: boolean;
+  },
+): Promise<void> {
+  const parts = options.rpc.split(".");
+
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    log.error("Invalid RPC format. Use: schema.rpc_name");
+    process.exit(1);
+  }
+
+  const schema = parts[0];
+  const rpcName = parts[1];
+
+  const rpcFunctionsResult = await SupabaseService.getRPCsWithParameters(
+    ctx,
+    schema,
+  );
+
+  let rpcFunction: RPCFunction | null = null;
+
+  if (rpcFunctionsResult.success) {
+    rpcFunction =
+      rpcFunctionsResult.value.find((rpc) => rpc.name === `rpc/${rpcName}`) ||
+      null;
+  } else {
+    log.warn(
+      "Failed to get RPC functions from schema, proceeding without validation",
+      rpcFunctionsResult.error.message,
+    );
+  }
+
+  if (!options.args) {
+    displayRPCHelp(schema, rpcName, rpcFunction);
+    return;
+  }
+
+  let args: Record<string, any> = {};
+  try {
+    args = parseRPCArgs(options.args);
+  } catch (error) {
+    log.error(
+      "Failed to parse RPC arguments",
+      error instanceof Error ? error.message : String(error),
+    );
+    process.exit(1);
+  }
+
+  if (rpcFunction) {
+    const requiredParams = rpcFunction.parameters.filter(
+      (p: RPCParameter) => p.required,
+    );
+    const missingParams = requiredParams.filter(
+      (p: RPCParameter) => !(p.name in args),
+    );
+
+    if (missingParams.length > 0) {
+      log.error(
+        `Missing required parameters: ${missingParams.map((p: RPCParameter) => p.name).join(", ")}`,
+      );
+      process.exit(1);
+    }
+  } else {
+    log.warn(
+      "Skipping parameter validation due to schema introspection failure",
+    );
+  }
+
+  const rpcResult = await SupabaseService.callRPC(ctx, schema, rpcName, args, {
+    get: true,
+    explain: options.explain,
+    limit: parseInt(options.limit),
+  });
+
+  if (!rpcResult.success) {
+    log.error("RPC call failed", rpcResult.error.message);
+    process.exit(1);
+  }
+
+  if (ctx.json) {
+    console.log(JSON.stringify(rpcResult.value, null, 2));
+  } else {
+    displayRPCResult(schema, rpcName, rpcResult.value, options.explain);
+  }
+}
+
+function displayRPCHelp(
+  schema: string,
+  rpcName: string,
+  rpcFunction: RPCFunction | null,
+): void {
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log(pc.bold(pc.cyan(`  RPC HELP: ${schema}.${rpcName}`)));
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+
+  if (rpcFunction && rpcFunction.parameters.length > 0) {
+    console.log(pc.bold("Parameters:"));
+    rpcFunction.parameters.forEach((param: RPCParameter) => {
+      const required = param.required
+        ? pc.red("(required)")
+        : pc.dim("(optional)");
+      const type = param.format
+        ? `${param.type} (${param.format})`
+        : param.type;
+      console.log(`  • ${pc.cyan(param.name)}: ${pc.yellow(type)} ${required}`);
+      if (param.description) {
+        console.log(pc.dim(`    ${param.description}`));
+      }
+    });
+    console.log();
+    console.log(pc.bold("Usage:"));
+    console.log(
+      pc.dim(
+        `supascan --rpc "${schema}.${rpcName}" --args '{"param1": "value1", "param2": "value2"}'`,
+      ),
+    );
+  } else if (rpcFunction) {
+    console.log(pc.dim("No parameters required"));
+    console.log();
+    console.log(pc.bold("Usage:"));
+    console.log(pc.dim(`supascan --rpc "${schema}.${rpcName}"`));
+  } else {
+    console.log(
+      pc.yellow(
+        "⚠️  Schema introspection failed - parameter information unavailable",
+      ),
+    );
+    console.log();
+    console.log(pc.bold("Usage:"));
+    console.log(
+      pc.dim(
+        `supascan --rpc "${schema}.${rpcName}" --args '{"param1": "value1"}'`,
+      ),
+    );
+    console.log();
+    console.log(
+      pc.dim(
+        "Note: You can still call the RPC, but parameter validation is disabled",
+      ),
+    );
+  }
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+}
+
+function displayRPCResult(
+  schema: string,
+  rpcName: string,
+  result: any,
+  explain?: boolean,
+): void {
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  if (explain) {
+    console.log(pc.bold(pc.cyan(`  QUERY PLAN: ${schema}.${rpcName}`)));
+  } else {
+    console.log(pc.bold(pc.cyan(`  RPC RESULT: ${schema}.${rpcName}`)));
+  }
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+
+  if (explain) {
+    console.log(pc.bold("Execution Plan:"));
+    console.log();
+    if (typeof result === "string") {
+      console.log(pc.yellow(result));
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else if (Array.isArray(result)) {
+    console.log(pc.bold("Results:"), pc.green(result.length.toString()));
+    console.log();
+    if (result.length > 0) {
+      console.table(result);
+    } else {
+      console.log(pc.dim("No results returned"));
+    }
+  } else if (typeof result === "object" && result !== null) {
+    console.log(pc.bold("Result:"));
+    console.table([result]);
+  } else {
+    console.log(pc.bold("Result:"), pc.green(String(result)));
+  }
+
+  console.log();
+  console.log(pc.bold(pc.cyan("━".repeat(60))));
+  console.log();
+}