supasec 1.0.3 → 1.0.5

package/IMPLEMENTATION_NOTES.md

@@ -1,305 +0,0 @@
-# SupaSec Implementation Notes
-
-## Recent Fixes & Updates
-
-### 1. Privacy Masking (Partial Masking Format)
-**Status:** ✅ COMPLETED
-
-Enhanced the masking system to show partial domain information:
-
-**Old Format:** `***.***. app`  
-**New Format:** `au******.app` (first 2 chars + masked middle + last 4 chars)
-
-**Examples:**
-```
-audityour.app → au******.app
-example.com → ex******.com
-myverylongdomainname.com → my**************name.com
-staging.example.org → st******.org
-```
-
-**Usage:**
-```bash
-supasec scan https://myapp.com --mask --format json
-# Target will appear as: my******.com
-```
-
-**Implementation Files:**
-- `src/commands/scan.ts` - `maskUrl()` and `maskDomain()` functions
-- Applied to all findings, descriptions, and evidence
-
----
-
-### 2. HTML Report Improvements
-**Status:** ✅ COMPLETED
-
-#### Removed Demo Text
-- Removed "Demo Security Report" banner from HTML reports
-- Reports now show clean, professional formatting
-- No "sample report" messaging
-
-#### Technical Details Display
-Technical details section now properly shows:
-- **Exposed Key (masked)** - Shows masked secret value
-- **Key Type** - Shows the pattern/category detected
-- **Location** - File path, line number, URL, or table name
-- **Code Snippet** - Shows the context where secret was found
-
-**Example output:**
-```
-Exposed Key (masked): pk_live_1234****8910
-Key Type: Stripe API Key
-Location: src/config.ts:42
-Code Snippet: const stripeKey = 'pk_live_1234...8910';
-```
-
----
-
-### 3. Report Format Options
-**Status:** ✅ COMPLETED
-
-Three report formats now available:
-
-#### Terminal (Default)
-```bash
-supasec scan https://myapp.com
-```
-Generates:
-- Colored terminal output
-- JSON report → `reports/supasec-report-{scan_id}.json`
-- HTML report → `reports/supasec-report-{scan_id}.html`
-
-#### JSON Format
-```bash
-supasec scan https://myapp.com --format json
-# or with custom path:
-supasec scan https://myapp.com --format json --output ./audit.json
-```
-
-#### HTML Format
-```bash
-supasec scan https://myapp.com --format html
-# or with custom path:
-supasec scan https://myapp.com --format html --output ./report.html
-```
-
-**All reports auto-save to `reports/` folder**
-
----
-
-## Planned Features (Not Yet Implemented)
-
-### 1. Fix Command (`supasec fix --interactive`)
-**Status:** ⏳ NOT YET IMPLEMENTED
-
-Currently, this command will show an error. To implement:
-
-```typescript
-// src/commands/fix.ts
-export function registerFixCommand(program: Command): void {
-  program
-    .command('fix')
-    .description('Fix security issues interactively or automatically')
-    .option('-i, --interactive', 'Interactive fix mode')
-    .option('-a, --auto', 'Automatic fix mode')
-    .option('-b, --backup', 'Create backup before fixing')
-    .action(async (options) => {
-      // Implementation needed
-    });
-}
-```
-
-**What the fix command should do:**
-1. Analyze recent scan results
-2. For each finding, offer fix options
-3. Apply fixes (generate SQL, update config, etc.)
-4. Create backups if requested
-5. Verify fixes worked
-
-**Priority:** Medium - Users can still scan and view reports
-
----
-
-### 2. Watch Mode (`supasec watch --interval 604800`)
-**Status:** ⏳ NOT YET IMPLEMENTED
-
-Periodically scan and track security changes over time.
-
-**Usage:**
-```bash
-supasec watch --interval 604800  # 7 days in seconds
-supasec watch --interval 86400   # 1 day
-supasec watch --interval 3600    # 1 hour
-```
-
-**What it should do:**
-1. Run scan at specified intervals
-2. Track findings over time
-3. Alert on new issues
-4. Generate trend reports
-5. Create historical comparison
-
----
-
-### 3. Database Connection Support
-**Status:** ⏳ NOT YET IMPLEMENTED
-
-Currently uses mock data. Should support:
-
-```bash
-# Via project URL and keys
-supasec scan --project-url https://abc.supabase.co \
-             --anon-key abc123... \
-             --service-key def456...
-
-# Via local Supabase
-supasec scan --local
-```
-
-**What to implement:**
-1. Connect to Supabase via SDK
-2. Fetch actual table definitions
-3. Check real RLS policies
-4. Scan actual database schema
-5. Get real function/RPC info
-
----
-
-### 4. Configuration File Support
-**Status:** ⏳ NOT YET IMPLEMENTED
-
-Support for `.supasecrc.json` or `supasec.config.json`:
-
-```json
-{
-  "target": "https://myapp.com",
-  "projectUrl": "https://abc.supabase.co",
-  "format": "html",
-  "mask": true,
-  "failOn": ["critical", "high"],
-  "ignorePaths": ["node_modules", ".next"],
-  "customRules": [
-    {
-      "id": "CUSTOM-001",
-      "pattern": "SECRET_API_KEY",
-      "severity": "CRITICAL"
-    }
-  ]
-}
-```
-
-Usage:
-```bash
-supasec scan  # Uses config file if present
-```
-
----
-
-### 5. CI/CD Integration
-**Status:** ⏳ PARTIAL (GitHub Actions example provided)
-
-Templates provided in docs, but could add:
-- Pre-built GitHub Actions
-- GitLab CI templates
-- Jenkins pipeline examples
-- Azure DevOps pipelines
-
----
-
-## Known Limitations
-
-### Current (Mock) Implementation
-1. **No real database connection** - Uses sample data
-2. **No browser-based scanning** - Puppeteer removed for now
-3. **No real API scanning** - Mock endpoints only
-4. **No RLS policy validation** - Uses mock policies
-5. **No fix command** - Analysis only, no remediation
-
-### Masking Limitations
-- Masking is primarily for privacy when sharing reports
-- Does not encrypt sensitive data in storage
-- Should not be used as security mechanism
-
-### Report Limitations
-- HTML reports are standalone files
-- No server-side dashboard
-- No report comparison/trending
-- No historical data retention by default
-
----
-
-## Architecture Notes
-
-### Finding Model
-```typescript
-interface Finding {
-  finding_id: string;           // e.g., "SEC-001"
-  severity: Severity;           // CRITICAL | HIGH | MEDIUM | LOW | INFO
-  title: string;
-  description: string;
-  location?: FindingLocation;   // Where the issue was found
-  evidence?: FindingEvidence;   // Proof/context
-  impact: FindingImpact;        // What could go wrong
-  remediation: FindingRemediation; // How to fix it
-}
-```
-
-### Masking Strategy
-- Applied at report generation time, not storage
-- Original data stored in JSON reports
-- User can choose --mask flag to hide sensitive info
-- Partial masking maintains some identifier visibility
-
-### Report Generation Flow
-```
-Scan → Findings Collection → Mask (if --mask) → Format → Save
-                                    ↓
-                           JSON | HTML | Terminal
-```
-
----
-
-## Testing Checklist
-
-- [x] Basic scan works: `npm start -- scan https://example.com`
-- [x] Masking works: `npm start -- scan https://audityour.app --mask`
-- [x] JSON format: `npm start -- scan https://example.com --format json`
-- [x] HTML format: `npm start -- scan https://example.com --format html`
-- [x] Reports save to `reports/` folder
-- [x] Technical details display in HTML
-- [x] No "Demo" text in HTML reports
-- [ ] Fix command (not yet implemented)
-- [ ] Watch mode (not yet implemented)
-- [ ] Real database connection (not yet implemented)
-
----
-
-## Next Steps for Development
-
-### High Priority
-1. Implement `supasec fix` command with SQL generation
-2. Add real Supabase database connection
-3. Implement configuration file support
-4. Add historical scan data/trending
-
-### Medium Priority
-1. Implement watch mode
-2. Add browser-based scanning (Puppeteer)
-3. Create CI/CD templates
-4. Add webhook integration
-
-### Low Priority
-1. Create web dashboard
-2. Add multi-project support
-3. Implement team features
-4. Add custom rule builder
-
----
-
-## Resources
-
-- [SupaSec GitHub](https://github.com/Interpoolx/supasec)
-- [Supabase Documentation](https://supabase.com/docs)
-- [AGENTS.md](./AGENTS.md) - Development guide
-- [REPORTING.md](./REPORTING.md) - Report formats guide
-- [PUBLISHING.md](./PUBLISHING.md) - Publishing to npm

package/QUICK_REFERENCE.md

@@ -1,185 +0,0 @@
-# SupaSec Quick Reference
-
-## Common Commands
-
-### Scan Websites
-```bash
-# Basic scan (terminal output + JSON + HTML)
-npm start -- scan https://myapp.com
-
-# Scan with domain masking
-npm start -- scan https://myapp.com --mask
-
-# Scan for sharing (masked HTML report)
-npm start -- scan https://myapp.com --mask --format html --output report.html
-```
-
-### Report Formats
-```bash
-# Terminal (default)
-npm start -- scan https://myapp.com
-
-# JSON only
-npm start -- scan https://myapp.com --format json
-
-# HTML only
-npm start -- scan https://myapp.com --format html
-
-# Custom output paths
-npm start -- scan https://myapp.com --format html --output ./report.html
-npm start -- scan https://myapp.com --format json --output ./audit.json
-```
-
-### Privacy & Sharing
-```bash
-# Mask domains (au******.app format)
-npm start -- scan https://myapp.com --mask
-
-# Generate masked report for sharing
-npm start -- scan https://myapp.com --mask --format html --quiet --output /tmp/report.html
-```
-
-## Masking Examples
-
-| Original | Masked |
-|----------|--------|
-| `audityour.app` | `au******.app` |
-| `example.com` | `ex*mple.com` |
-| `myverylongdomainname.com` | `my**************name.com` |
-| `staging.example.com` | `st*ging.com` |
-
-## Report Locations
-
-All reports auto-save to `reports/` folder:
-```
-reports/
-├── supasec-example-com-2026-01-28-17-15-06.html
-├── supasec-example-com-2026-01-28-17-15-06.json
-├── supasec-au******.app-2026-01-28-17-14-57.html
-└── ...
-```
-
-## Development Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Build TypeScript
-npm run build
-
-# Build in watch mode
-npm run dev
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Fix lint errors
-npm run lint -- --fix
-
-# Clean builds
-rm -r dist/
-npm run build
-```
-
-## Publishing
-
-```bash
-# Setup token (one time)
-npm config set //registry.npmjs.org/:_authToken npm_YOUR_TOKEN_HERE
-
-# Publish current version
-node scripts/publish.js
-
-# Publish as specific version
-node scripts/publish.js 1.0.5
-```
-
-## Troubleshooting
-
-### Build Fails
-```bash
-npm install
-npm run build
-```
-
-### Reports Not Generating
-```bash
-# Check reports folder exists
-ls reports/
-
-# Run with non-quiet mode
-npm start -- scan https://example.com  # See progress
-```
-
-### Masking Not Applied
-```bash
-# Make sure to use --mask flag
-npm start -- scan https://myapp.com --mask  # ✅
-npm start -- scan https://myapp.com         # No masking
-```
-
-## File Locations
-
-| Purpose | Location |
-|---------|----------|
-| Source Code | `src/` |
-| Compiled Output | `dist/` |
-| Reports | `reports/` |
-| Config | `tsconfig.json`, `.eslintrc.json` |
-| Dependencies | `package.json` |
-| Docs | `AGENTS.md`, `REPORTING.md`, `PUBLISHING.md` |
-
-## Useful Resources
-
-- [AGENTS.md](./AGENTS.md) - Development guide
-- [REPORTING.md](./REPORTING.md) - Report format details
-- [PUBLISHING.md](./PUBLISHING.md) - How to publish to npm
-- [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md) - Technical details
-- [COMPLETION_REPORT.md](./COMPLETION_REPORT.md) - What was fixed
-
-## Options Reference
-
-```bash
-supasec scan <target> [options]
-
-Options:
-  -f, --format <format>      Output format: terminal|json|html (default: terminal)
-  -o, --output <file>        Output file path
-  --mask                      Mask domains in reports (au******.app format)
-  -q, --quiet                Suppress console output
-  --no-color                 Disable colored output
-  -t, --timeout <seconds>    Scan timeout (default: 60)
-  --fail-on <levels>         Fail on severity: critical,high,medium,low
-  -d, --deep                 Deep scan (slower, more thorough)
-  -l, --local                Scan local Supabase
-  --project-url <url>        Supabase project URL
-  --anon-key <key>           Supabase anon key
-  --service-key <key>        Supabase service role key
-```
-
-## HTML Report Features
-
-✅ Color-coded severity levels  
-✅ Responsive mobile-friendly design  
-✅ Exposed secrets (masked)  
-✅ Security grade (A-F)  
-✅ Risk scores  
-✅ Remediation steps  
-✅ Print-friendly layout  
-✅ Fast page load  
-
-## Next Steps
-
-1. **Scan your app:** `npm start -- scan https://myapp.com`
-2. **Review report:** Open `reports/supasec-*.html`
-3. **Share report:** Use `--mask` flag for privacy
-4. **Implement fixes:** Follow remediation steps
-5. **Re-scan:** Verify issues are fixed
-
----
-
-**More Help:** Check documentation files for detailed guides.

package/REPORTING.md

@@ -1,217 +0,0 @@
-# SupaSec Reporting Guide
-
-## Report Formats
-
-SupaSec supports multiple report formats for different workflows.
-
-### Terminal Output (Default)
-
-Display results directly in the terminal with colored formatting:
-
-```bash
-supasec scan https://myapp.com
-```
-
-Automatically generates:
-- Terminal output (colored)
-- JSON report (saved to `reports/`)
-- HTML report (saved to `reports/`)
-
-### JSON Format
-
-Machine-readable JSON reports for CI/CD integration:
-
-```bash
-supasec scan https://myapp.com --format json
-supasec scan https://myapp.com --format json --output custom/path/report.json
-```
-
-## HTML Format
-
-Beautiful interactive HTML reports for sharing and presentations:
-
-```bash
-supasec scan https://myapp.com --format html
-supasec scan https://myapp.com --format html --output reports/audit-report.html
-```
-
-Features:
-- ✓ Color-coded severity levels
-- ✓ Responsive design (works on all devices)
-- ✓ Detailed vulnerability information
-- ✓ Passed checks summary
-- ✓ Print-friendly layout
-- ✓ Risk scoring and grading
-
-## Report Location
-
-By default, all reports are saved to the `reports/` folder:
-
-```
-reports/
-├── supasec-report-scan_2026-01-28T16-21-35.json
-└── supasec-report-scan_2026-01-28T16-21-35.html
-```
-
-### Custom Output Path
-
-```bash
-# Specify custom output file
-supasec scan https://myapp.com --format json --output /path/to/report.json
-
-# Terminal mode generates both formats
-supasec scan https://myapp.com
-# → reports/supasec-report-{scan_id}.json
-# → reports/supasec-report-{scan_id}.html
-```
-
-## Report Contents
-
-### JSON Report
-
-Machine-readable structure:
-
-```json
-{
-  "scan_metadata": {
-    "tool": "supasec",
-    "version": "1.0.0",
-    "scan_id": "scan_2026-01-28T16-21-35",
-    "target_url": "https://myapp.com",
-    "scan_date": "2026-01-28T16:21:35.613Z",
-    "scan_duration_seconds": 2.5,
-    "scanner_mode": "url"
-  },
-  "summary": {
-    "total_issues": 2,
-    "critical": 0,
-    "high": 1,
-    "medium": 1,
-    "low": 0,
-    "overall_grade": "B",
-    "overall_score": 85
-  },
-  "findings": [
-    {
-      "finding_id": "SEC-001",
-      "severity": "HIGH",
-      "title": "Exposed Secret",
-      "description": "API key found in JavaScript bundle",
-      "location": { "url": "https://myapp.com", "line": 42 },
-      "impact": { "description": "Unauthorized API access" },
-      "remediation": { "summary": "Remove secrets from client code" }
-    }
-  ],
-  "passed_checks": [...],
-  "grading": {...}
-}
-```
-
-### HTML Report
-
-Visual format with:
-- Executive summary cards
-- Severity breakdown
-- Detailed findings with descriptions
-- Remediation guidance
-- Security grading (A-F)
-- Scan metadata
-
-## CI/CD Integration
-
-### GitHub Actions Example
-
-```yaml
-- name: Security Audit
-  run: |
-    npx supasec scan ${{ secrets.STAGING_URL }} \
-      --format json \
-      --output audit.json \
-      --quiet
-      
-- name: Upload Report
-  if: always()
-  uses: actions/upload-artifact@v3
-  with:
-    name: security-audit
-    path: audit.json
-```
-
-### Parse JSON in CI/CD
-
-```bash
-# Count critical issues
-critical=$(jq '.summary.critical' audit.json)
-
-# Fail if critical issues found
-if [ "$critical" -gt 0 ]; then
-  echo "❌ Critical security issues found!"
-  exit 1
-fi
-```
-
-## Options
-
-| Option | Format | Default | Description |
-|--------|--------|---------|-------------|
-| `--format` | `terminal\|json\|html` | `terminal` | Output format |
-| `--output` | path | `reports/{scan_id}.{ext}` | Custom output file |
-| `--quiet` | flag | false | Suppress console output |
-
-## Examples
-
-```bash
-# Default: Terminal + JSON + HTML
-npm start -- scan https://example.com
-
-# JSON only
-npm start -- scan https://example.com --format json
-
-# HTML only  
-npm start -- scan https://example.com --format html
-
-# Custom output paths
-npm start -- scan https://example.com --format json --output ./security/report.json
-npm start -- scan https://example.com --format html --output ./public/audit.html
-
-# Quiet mode (no console output)
-npm start -- scan https://example.com --quiet
-
-# Combine options
-npm start -- scan https://example.com --format json --output results.json --quiet
-```
-
-## Opening HTML Reports
-
-Generated HTML reports are standalone files. Open them in any browser:
-
-```bash
-# Windows
-start reports/supasec-report-scan_2026-01-28T16-21-35.html
-
-# macOS
-open reports/supasec-report-scan_2026-01-28T16-21-35.html
-
-# Linux
-xdg-open reports/supasec-report-scan_2026-01-28T16-21-35.html
-```
-
-## Report Retention
-
-Reports are stored in the `reports/` folder and are **not** committed to git:
-
-```
-# .gitignore
-reports/
-supasec-report-*.json
-supasec-report-*.html
-```
-
-Archive old reports:
-```bash
-# Backup reports folder
-tar -czf reports-backup-$(date +%Y%m%d).tar.gz reports/
-
-# Clear old reports
-rm reports/supasec-report-*.{json,html}
-```