codeprobe-scanner 1.0.4 → 1.0.6

package/STAGE_2_CLI_VERIFICATION.md

@@ -1,269 +0,0 @@
-# CodeProbe MVP — Stage 2: CLI + Verification + Fallbacks
-**Duration:** 2–4 hours  
-**Team:** 1–2 engineers (can work in parallel with Stage 1 or sequentially)  
-**Dependency:** Stage 1 must be working  
-
----
-
-## Overview
-
-Build the **CLI interface** and **production-grade fallback logic**. This is where the "demo moment" happens: user runs `codeprobe scan` and sees real-time exploit verification. Includes error handling, retry logic, and graceful degradation if external APIs fail.
-
-**Success Metric:** `codeprobe scan ./demo-vulnerable-app` completes in <3 minutes, shows risk score + confirmed exploitable CVEs, patches are ready to apply.
-
----
-
-## Critical Decisions (Locked)
-
-| What | Decision | Why |
-|------|----------|-----|
-| CLI Framework | No heavy framework; use chalk + table.js | Keep it simple, fast startup. No `commander.js` overhead. |
-| Real-Time Output | Event emitter (progress updates) → CLI polls/logs | Engine emits: "parsing...", "scraping...", "sandboxing...", CLI logs with timestamps. |
-| Fallback Strategy | Bright Data fails → cached CVE JSON. Daytona crash → mark "verification failed". LLM fails → use pre-baked patch. | Demo must work even if 1–2 APIs are flaky. Pre-record fallback video anyway. |
-| Config Storage | `~/.codeprobe/config.json` (GitHub token encrypted with SHA256 + salt) | Simple, portable. No database. |
-| Exit Codes | 0 = success, 1 = vulnerabilities found, 2 = scan failed | Matches CI/CD standards. |
-
----
-
-## Deliverables
-
-### 1. CLI Entry Point
-- [ ] `src/cli/index.ts`:
-  - Commands: `scan`, `scan --fix`, `report`
-  - No args = show help
-  - `--json` flag for machine-readable output
-  - `--verbose` flag for detailed logs
-  - Error handling: catch all errors, show friendly messages + suggestion
-  - **Test**: `bun ./src/cli/index.ts --help` shows usage
-
-### 2. `codeprobe scan` Command
-- [ ] `src/cli/commands/scan.ts`:
-  - Input: repo URL or local path (default: current dir)
-  - Output: Real-time progress to stdout
-  - Flow:
-    ```
-    ⚡ CodeProbe v1.0.0
-    [12:34:56] Parsing dependencies...
-    [12:34:58] Found 8 dependencies
-    [12:34:59] Fetching CVE data (Bright Data)...
-    [12:35:14] Found 3 CVEs matching your dependencies
-    [12:35:15] Spinning up sandboxes for CRITICAL CVEs...
-    [12:35:16]   ├─ Sandbox 1: CVE-2022-29078 (ejs Template Injection RCE)
-    [12:35:17] Running exploit...
-    [12:36:17] ✓ CONFIRMED EXPLOITABLE (RCE achieved in 1.2s)
-    
-    ────────────────────────────────────────────────
-    SCAN COMPLETE
-    Risk Score: 9.0/10 (CRITICAL)
-    Confirmed Exploitable: 1
-    Theoretical Risk: 1
-    
-    Patches Available: 1
-    View full report: ~/.codeprobe/scans/{scan_id}.json
-    ────────────────────────────────────────────────
-    ```
-  - Colors: Green = confirmed, Yellow = theoretical, Red = supply chain warnings
-  - Exit code: 0 (no vulns), 1 (vulns found), 2 (scan failed)
-
-### 3. `codeprobe scan --fix` Command
-- [ ] `src/cli/commands/scan-with-fix.ts`:
-  - After scan completes, generate patches for confirmed CVEs
-  - Create new git branch: `codeprobe-fix-{timestamp}`
-  - Apply patches (update package.json + package-lock.json)
-  - Commit with message:
-    ```
-    [CodeProbe] Fix CVE-2023-44487 (HTTP/2 Rapid Reset)
-    
-    Exploit verification: CONFIRMED EXPLOITABLE
-    Risk Score: 8.5/10
-    Patch: http2-server 1.0.0 → 1.0.1
-    ```
-  - Output:
-    ```
-    [12:36:20] Applying patches...
-    [12:36:25] ✓ Updated ejs: 3.1.6 → 3.1.7
-    [12:36:26] Committed to branch: codeprobe-fix-2026-06-13-001
-    [12:36:27] Push to GitHub: git push -u origin codeprobe-fix-2026-06-13-001
-    ```
-  - Exit code: 0 (patches applied), 1 (patches failed), 2 (scan failed)
-
-### 4. `codeprobe report` Command
-- [ ] `src/cli/commands/report.ts`:
-  - Display last scan results (from `~/.codeprobe/scans/latest.json`)
-  - Formatted table: CVE | Package | Severity | Exploitable | Patch Version
-  - Option: `--export json` or `--export html`
-  - Exit code: 0
-
-### 5. Config Management
-- [ ] `src/cli/config.ts`:
-  - Load/save `~/.codeprobe/config.json`
-  - Store: GitHub token (encrypted), Bright Data API key, Daytona API key, Nosana API key
-  - Encryption: SHA256 + salt (simple, not production-grade, but OK for MVP)
-  - Methods: `getConfig()`, `setConfig(key, value)`, `clearConfig(key)`
-  - On first run: prompt for GitHub token (if needed for later features)
-
-### 6. Progress + Logging
-- [ ] `src/cli/progress.ts`:
-  - Event emitter from Stage 1 engine
-  - Translate engine events → human-readable CLI output
-  - Progress bar library: use simple ASCII (no fancy libraries)
-  - Colors: chalk.js
-  - Timestamps: dayjs.js
-  - Levels: `info`, `warn`, `error`, `success`
-  - **Test**: `bun run index.ts scan . --verbose` should show all events
-
-### 7. Error Handling + Fallbacks
-- [ ] `src/cli/errors.ts`:
-  - Catch all exceptions at top level
-  - Map to user-friendly messages:
-    ```
-    ❌ Bright Data API failed (network timeout)
-    → Using cached CVE data (last updated 2h ago)
-    → Scan continues but results may be incomplete
-    ⚠️ Run `codeprobe config set BRIGHT_DATA_API_KEY <key>` to use live data
-    ```
-  - Fallback triggers:
-    - Bright Data timeout (5s) → use cache
-    - Daytona spawn fail (2 retries) → mark "verification failed", continue
-    - LLM generation fail (2 retries) → use pre-baked patch
-  - Never silently fail; always log what went wrong + what we're doing instead
-
-### 8. Integration Tests
-- [ ] `src/test/cli.test.ts`:
-  ```ts
-  test("CLI: scan demo repo end-to-end", async () => {
-    const { exitCode, output } = await runCLI(["scan", "./demo-vulnerable-app"]);
-    expect(exitCode).toBe(1); // 1 = vulnerabilities found
-    expect(output).toContain("CVE-2022-29078");
-    expect(output).toContain("CONFIRMED EXPLOITABLE");
-    expect(output).toContain("Risk Score");
-  });
-
-  test("CLI: --fix creates branch and commits", async () => {
-    const { exitCode, output } = await runCLI(["scan", "./demo-vulnerable-app", "--fix"]);
-    expect(exitCode).toBe(1);
-    expect(output).toContain("codeprobe-fix");
-    // Check git branch was created
-    const branches = await $`git branch`.text();
-    expect(branches).toContain("codeprobe-fix");
-  });
-  ```
-- [ ] Run: `bun test` → should pass
-
-### 9. Performance Optimization
-- [ ] Measure + log scan time:
-  ```
-  ⏱️  Scan completed in 2m 34s
-  - Parsing: 2s
-  - Scraping: 18s
-  - Sandbox setup: 45s
-  - Exploit execution: 28s
-  - Patch generation: 1s
-  ```
-- [ ] If any step > 30s, log warning: "⚠️ Step XYZ slow (YYs). Consider checking your network."
-- [ ] Target: <3 minutes end-to-end
-
-### 10. Demo Rehearsal Script
-- [ ] `demo.sh`:
-  ```bash
-  #!/bin/bash
-  set -e
-  echo "=== CodeProbe Demo Script ==="
-  echo "1. Clear previous scans..."
-  rm -rf ~/.codeprobe/scans/*
-  
-  echo "2. Run full scan with --fix..."
-  bun run src/cli/index.ts scan ./demo-vulnerable-app --fix
-  
-  echo "3. Show results..."
-  bun run src/cli/index.ts report --export json | jq .
-  
-  echo "4. Verify git branch created..."
-  git branch
-  
-  echo "✅ Demo successful"
-  ```
-- [ ] Run manually: `bash demo.sh` should complete without errors
-- [ ] Time it: `time bash demo.sh` (target <3 minutes)
-
----
-
-## Acceptance Criteria
-
-✅ **Must Have:**
-1. `bun run src/cli/index.ts scan ./demo-vulnerable-app` completes in <3 minutes
-2. Shows "CONFIRMED EXPLOITABLE" for HTTP/2 CVE
-3. Shows risk_score (0–10)
-4. JSON report saved to `~/.codeprobe/scans/{id}.json`
-5. `--fix` flag creates git branch + commits patches
-6. `--json` flag outputs valid JSON
-7. Exit code: 1 when vulnerabilities found
-8. If Bright Data fails, uses cache + shows warning
-9. `bun test` passes (all CLI tests)
-10. `demo.sh` runs without errors
-
-✅ **Nice to Have:**
-- Colorized output (green/yellow/red)
-- Progress bar ASCII animation
-- Scan time breakdown per stage
-- `--verbose` flag shows detailed logs
-
----
-
-## Known Risks + Mitigations
-
-| Risk | Mitigation |
-|------|-----------|
-| CLI startup is slow (Bun cold start) | Pre-warm Bun by running once before demo. Measure startup time. |
-| Bright Data scraping times out | Pre-cache CVE data. In demo, show fallback working. |
-| Daytona sandbox slow to provision | Pre-test sandbox startup latency. If >30s, adjust timeout expectations. |
-| User's git repo is dirty | Check `git status` before `--fix`. If dirty, warn + ask to commit first. |
-| Network connectivity lost mid-scan | Graceful error: "Scan interrupted. Results saved to {cache}. Try again when online." |
-
----
-
-## Setup Checklist
-
-Before starting Stage 2:
-- [ ] Stage 1 passing (`bun test` in `src/test/engine.test.ts`)
-- [ ] Demo repo has HTTP/2 vulnerable server running locally (test: `curl http://localhost:8080`)
-- [ ] Bright Data cache file exists: `cve-cache.json` (even if API fails)
-- [ ] Pre-baked patches exist: `patches.json`
-- [ ] Git repo initialized locally: `git init` (for --fix flag testing)
-- [ ] API keys set as env vars (or in `~/.codeprobe/config.json`)
-
----
-
-## Deliverable Checklist
-
-When Stage 2 is done:
-- [ ] Push to branch: `stage-2-cli` (or merge into `stage-1-engine` if both complete)
-- [ ] Run demo manually: `bash demo.sh` (timing should be <3 minutes)
-- [ ] Create summary: "Stage 2 Complete: CLI fully functional, real-time progress logging, fallbacks tested"
-- [ ] Note any deviations: If Bright Data timeout happens, document actual fallback behavior
-- [ ] List blockers for Stage 3: "Dashboard needs {scan_id} lookup, requires database or S3 key"
-
----
-
-## Files to Create/Modify
-
-```
-NEW:
-  src/cli/index.ts
-  src/cli/commands/scan.ts
-  src/cli/commands/scan-with-fix.ts
-  src/cli/commands/report.ts
-  src/cli/config.ts
-  src/cli/progress.ts
-  src/cli/errors.ts
-  src/test/cli.test.ts
-  demo.sh
-
-MODIFY:
-  package.json (add CLI entry point: bin.codeprobe)
-  src/engine/report.ts (add latest.json symlink)
-```
-
----
-
-**Next Stage:** Once this is complete, Stage 3 begins (Dashboard + Auth + Polish).

package/STAGE_2_COMPLETE.md

@@ -1,332 +0,0 @@
-# CodeProbe Stage 2: Implementation Complete
-
-**Date**: 2026-06-13  
-**Status**: ✅ Stage 2 CLI fully functional (mocked engine, ready for Stage 1 integration)  
-**Test Results**: 16/16 tests passing
-
----
-
-## What Was Built
-
-### Core CLI Files (11 files)
-
-1. **src/cli/index.ts** — Main entry point
-   - Command dispatch (scan, report, config, help)
-   - Argument parsing
-   - Error handling wrapper
-
-2. **src/cli/commands/scan.ts** — Primary scanning command
-   - `codeprobe scan [path] [--fix] [--json] [--verbose]`
-   - Mocked engine calls (ready for Stage 1 integration)
-   - Report saving to ~/.codeprobe/scans/
-   - Colored terminal output
-
-3. **src/cli/commands/scan-with-fix.ts** — Git integration
-   - Git repository validation
-   - Branch creation (codeprobe-fix-{timestamp})
-   - Patch application and commit
-   - User guidance output
-
-4. **src/cli/commands/report.ts** — Report display
-   - Load latest scan results
-   - Display as formatted table or JSON
-   - CVE details with patch info
-
-5. **src/cli/config.ts** — Configuration management
-   - AES-256-GCM encryption for sensitive tokens (recommended option B)
-   - Load/save ~/.codeprobe/config.json
-   - Environment variable fallback
-   - File permissions: 0600 (owner read/write only)
-
-6. **src/cli/progress.ts** — Event logging
-   - Event emitter integration (ready for Stage 1)
-   - Colored terminal output (chalk)
-   - Timestamps (dayjs)
-   - Verbose/quiet modes
-
-7. **src/cli/errors.ts** — Error handling
-   - Custom error types (BrightDataError, DaytonaError, GitError, etc.)
-   - Retry logic with exponential backoff
-   - Timeout wrapper
-   - User-friendly error messages
-
-8. **src/shared/types.ts** — Shared type definitions
-   - Report, CVE, Scan, ScanEvent interfaces
-   - CliOptions, ScanResult types
-   - Ready to import from Stage 1
-
-9. **src/shared/constants.ts** — Configuration constants
-   - API paths and timeouts
-   - File permissions
-   - Exit codes
-   - Risk scoring weights
-
-10. **src/shared/utils.ts** — Utility functions
-    - Risk score formatting (0-10 scale)
-    - Risk level classification (CRITICAL/HIGH/MEDIUM/LOW)
-    - Duration formatting (ms to human readable)
-    - ID generation
-
-11. **src/test/cli.test.ts** — Test suite
-    - 16 unit tests (all passing)
-    - Config management tests
-    - Error handling tests
-    - Type validation tests
-    - Utils tests
-
-### Demo & Documentation Files
-
-- **demo.sh** — Automated demo script for rehearsal
-- **.env.example** — API key template
-- **package.json** — Dependencies (chalk, dayjs, zod, axios)
-
----
-
-## Features Implemented
-
-### ✅ CLI Commands
-
-```bash
-codeprobe scan [path]           # Scan repo for vulnerabilities
-codeprobe scan --fix             # Apply patches + create git branch
-codeprobe scan --json            # Output as JSON
-codeprobe scan --verbose         # Detailed logging
-codeprobe report                 # Display last scan
-codeprobe config get [key]       # View config
-codeprobe config set [key] [val] # Set config value
-codeprobe config clear [key]     # Remove config value
-codeprobe --help                 # Show help
-```
-
-### ✅ Output Formatting
-
-- **Colored output** — Green/Yellow/Red for success/warn/error
-- **Timestamps** — HH:mm:ss format for each event
-- **Progress indicators** — ▶️/✓/❌ icons for status
-- **Formatted tables** — CVE details with aligned columns
-- **JSON export** — Valid, parseable JSON output
-
-### ✅ Error Handling & Fallbacks
-
-- **Timeout handling** — Configurable timeouts for API calls
-- **Retry logic** — Exponential backoff (max 2 retries)
-- **Graceful degradation** — Continue on partial failures
-- **User guidance** — Helpful error messages with next steps
-
-### ✅ Security
-
-- **Encryption** — AES-256-GCM for sensitive tokens
-- **File permissions** — ~/.codeprobe/ is 0700, reports are 0600
-- **Environment precedence** — Env vars override config file
-- **Token handling** — Encrypted storage, never logged
-
-### ✅ Git Integration
-
-- **Repository validation** — Check if repo exists
-- **Dirty repo detection** — Warn before applying patches
-- **Branch creation** — Timestamped branch names
-- **Automatic commits** — Detailed commit messages with CVE info
-
-### ✅ Testing
-
-- **Unit tests** — Config, errors, utils, types (16 tests)
-- **Test isolation** — Temp directories for config testing
-- **Mock integration** — Ready for Stage 1 engine mocking
-
----
-
-## How It Works (Mock Flow)
-
-```
-$ bun run src/cli/index.ts scan .
-
-⚡ CodeProbe v1.0.0
-[12:47:44] ▶️  Parsing dependencies...
-[12:47:45] ✓ Found 1 dependency
-[12:47:45] ▶️  Fetching CVE data...
-[12:47:46] ✓ Found 1 CVE
-[12:47:46] ▶️  Running exploit verification...
-[12:47:48] ✓ CONFIRMED EXPLOITABLE
-[12:47:48] ✓ Report saved to ~/.codeprobe/scans/scan_*.json
-
-────────────────────────────────────────────────
-SCAN COMPLETE
-Risk Score: 8.5/10 (CRITICAL)
-Confirmed Exploitable: 1 | Theoretical Risk: 0
-Patches Available: 1
-Duration: 4s
-
-CVE Details:
-  CVE-2023-44487: http2-server 1.0.0 [CRITICAL] ✓ CONFIRMED EXPLOITABLE
-    → Patch available: 1.0.1
-────────────────────────────────────────────────
-```
-
----
-
-## File Structure
-
-```
-src/
-├── cli/
-│   ├── index.ts                    ✅ Entry point
-│   ├── config.ts                   ✅ Token storage (AES-256-GCM)
-│   ├── progress.ts                 ✅ Event logging
-│   ├── errors.ts                   ✅ Error handling + retries
-│   └── commands/
-│       ├── scan.ts                 ✅ Main scan command
-│       ├── scan-with-fix.ts        ✅ Git integration
-│       └── report.ts               ✅ Display results
-│
-├── shared/
-│   ├── types.ts                    ✅ Type definitions
-│   ├── constants.ts                ✅ Configuration
-│   └── utils.ts                    ✅ Helper functions
-│
-├── engine/                         ⏳ Stage 1 (external)
-│   └── (will be imported from Stage 1)
-│
-└── test/
-    ├── cli.test.ts                 ✅ Unit tests (16/16 passing)
-    └── e2e.cli.test.ts             ⏳ E2E tests (after Stage 1)
-```
-
----
-
-## Test Results
-
-```
-bun test v1.3.14 (0d9b296a)
-
-src/test/cli.test.ts:
-✓ Config saved: test_key
-
- 16 pass
- 0 fail
- 34 expect() calls
-Ran 16 tests across 1 file. [72.00ms]
-```
-
-**Tests Passing:**
-- ✅ Config directory creation
-- ✅ Config save/load roundtrip
-- ✅ Missing config handling
-- ✅ Progress logger
-- ✅ Event handling
-- ✅ Error types (BrightData, Daytona, Git, Config)
-- ✅ Retry with backoff
-- ✅ Unique scan ID generation
-- ✅ Risk score formatting
-- ✅ Risk level classification
-- ✅ Duration formatting
-- ✅ Type validation
-- ✅ Exit codes
-- ✅ File permissions
-- ✅ Risk score weights
-
----
-
-## Next Steps (Stage 1 Integration)
-
-### When Stage 1 Engine Is Ready
-
-1. **Import real engine** — Replace mock in scan.ts with `import { runFullScan } from '../engine'`
-2. **Wire event handler** — Connect Stage 1 event emitter to progress.ts
-3. **Run E2E tests** — `bun test src/test/e2e.cli.test.ts` (currently skipped)
-4. **Demo rehearsal** — `bash demo.sh` (target <3 minutes)
-
-### Stage 1 Dependency Interface
-
-Stage 2 expects Stage 1 to export:
-
-```typescript
-export async function runFullScan(
-  repoPath: string,
-  options?: { verbose?: boolean; onEvent?: (event: ScanEvent) => void }
-): Promise<Report>
-
-export interface ScanEvent { ... }
-export type Report { ... }
-export type CVE { ... }
-```
-
-### Known Blockers for Full E2E
-
-- ✗ Stage 1 engine not complete yet
-- ✗ Demo vulnerable app not created
-- ✗ Bright Data integration not tested
-- ✗ Daytona sandbox not provisioned
-- ✓ All Stage 2 CLI surface ready
-
----
-
-## Configuration
-
-### Encryption Decision (Locked as Option B)
-
-**Token Encryption**: AES-256-GCM with machine fingerprint  
-- Cross-platform (works on all OSes)
-- No system setup required
-- Fallback to plaintext if key derivation fails
-- Tokens stored in `~/.codeprobe/config.json` (0600 perms)
-
-### API Key Precedence
-
-1. Environment variables (e.g., `BRIGHT_DATA_API_KEY`)
-2. Config file (`~/.codeprobe/config.json`)
-3. Error if neither found
-
-### Exit Codes
-
-- `0` — Success (no vulnerabilities or patches applied)
-- `1` — Vulnerabilities found
-- `2` — Scan failed or operation error
-
----
-
-## Performance Metrics
-
-- **CLI startup** — <100ms (Bun fast)
-- **Config read** — <10ms
-- **JSON output** — <5ms
-- **Test suite** — ~72ms (all 16 tests)
-- **Demo rehearsal** — 4s (mocked engine)
-
----
-
-## Known Limitations (MVP)
-
-- ✓ Mocked engine (real engine integration TBD)
-- ✓ Single demo CVE (HTTP/2 Rapid Reset)
-- ✓ File-based scan storage (no database)
-- ✓ No authentication for dashboard (Stage 3)
-- ✓ No GitHub PR auto-commenting (Stage 3)
-- ✓ No multi-language support (Node.js only)
-
----
-
-## What's Ready for Demo Day
-
-✅ Working CLI that accepts arguments  
-✅ Scan command that outputs results  
-✅ Report command that displays results  
-✅ Config management with encryption  
-✅ Error handling + retry logic  
-✅ JSON output  
-✅ Git integration (--fix flag)  
-✅ All tests passing  
-✅ Demo script ready  
-
-**Blocked on Stage 1:**
-⏳ Real exploit verification  
-⏳ Real CVE data from Bright Data  
-⏳ Real sandbox from Daytona  
-⏳ E2E testing  
-
----
-
-## Summary
-
-Stage 2 CLI is **feature-complete and ready for integration with Stage 1 engine**. All 11 core files implemented, 16 tests passing, error handling robust. The system is architected for easy swapping of the mocked engine with the real Stage 1 implementation once ready.
-
-**Next: Build Stage 1 engine and integrate with Stage 2 CLI.**