@cencori/scan 0.3.3 → 0.3.5

package/README.md

@@ -1,85 +1,171 @@
 # @cencori/scan
 
-Security scanner for AI apps. Detect hardcoded secrets, PII leaks, and exposed routes.
+**Security scanner for AI apps.** Detect hardcoded secrets, PII leaks, exposed routes, and security vulnerabilities — with AI-powered auto-fix.
+
+[![npm version](https://img.shields.io/npm/v/@cencori/scan.svg)](https://www.npmjs.com/package/@cencori/scan)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+```bash
+npx @cencori/scan
+```
+
+That's it. Run it in any project directory to instantly scan for security issues.
+
+## Features
+
+- 🔍 **Pattern-based scanning** - Detects 50+ types of secrets, PII, and vulnerabilities
+- 🤖 **AI-powered auto-fix** - Automatically fixes issues with one command
+- ⚡ **Fast** - Scans thousands of files in seconds
+- 🎯 **Zero config** - Works out of the box
+- 📊 **Security scoring** - A through F tier grading
 
 ## Installation
 
 ```bash
-# Run directly with npx
+# Run directly (recommended)
 npx @cencori/scan
 
 # Or install globally
 npm install -g @cencori/scan
+
+# Or as a dev dependency
+npm install -D @cencori/scan
 ```
 
 ## Usage
 
+### Basic Scan
+
 ```bash
 # Scan current directory
-cencori-scan
+npx @cencori/scan
 
 # Scan specific path
-cencori-scan ./my-project
+npx @cencori/scan ./my-project
 
-# Output JSON
-cencori-scan --json
+# Output JSON (for CI/CD)
+npx @cencori/scan --json
 
 # Quiet mode (score only)
-cencori-scan --quiet
+npx @cencori/scan --quiet
+
+# Skip interactive prompts
+npx @cencori/scan --no-prompt
+```
+
+### AI Auto-Fix (Pro)
+
+After scanning, you'll be prompted:
+
+```
+? Would you like Cencori to auto-fix these issues? (y/n)
+```
+
+Enter `y` and you'll be asked for your API key (if not already saved):
+
+```
+? Enter your Cencori API key: ************************
 ```
 
+The AI will:
+1. Analyze each issue for false positives
+2. Generate secure code fixes
+3. Apply fixes automatically
+
+Your API key is saved to `~/.cencorirc` for future scans.
+
+**Get your free API key at [cencori.com/dashboard](https://cencori.com/dashboard)**
+
 ## What It Detects
 
-### API Keys & Secrets
-- OpenAI, Anthropic, Google AI
-- Supabase, Firebase
-- Stripe, AWS, GitHub
-- And 20+ more providers
+### 🔐 API Keys & Secrets
+
+| Provider | Pattern |
+|----------|---------|
+| OpenAI | `sk-...`, `sk-proj-...` |
+| Anthropic | `sk-ant-...` |
+| Google AI | `AIza...` |
+| Supabase | `eyJh...` (service role) |
+| Stripe | `sk_live_...`, `sk_test_...` |
+| AWS | `AKIA...` |
+| GitHub | `ghp_...`, `gho_...` |
+| Firebase | `firebase-adminsdk-...` |
+| And 20+ more... | |
 
-### PII (Personal Identifiable Information)
-- Email addresses
+### 👤 PII (Personal Identifiable Information)
+
+- Email addresses in code
 - Phone numbers
 - Social Security Numbers
 - Credit card numbers
 
-### Exposed Routes
-- Next.js API routes without auth
-- Express routes without middleware
-- Sensitive files in public folders
+### 🛣️ Exposed Routes
+
+- Next.js API routes without authentication
+- Express routes without auth middleware
+- Sensitive files in `/public` folders
+- Dashboard/admin routes without protection
+
+### ⚠️ Security Vulnerabilities
+
+- SQL injection patterns
+- XSS vulnerabilities (innerHTML, dangerouslySetInnerHTML)
+- Insecure CORS configuration (`Access-Control-Allow-Origin: *`)
+- Hardcoded passwords
+- Debug modes in production
 
 ## Security Score
 
-| Score | Meaning |
-|-------|---------|
-| A-Tier | Excellent - No issues found |
-| B-Tier | Good - Minor improvements needed |
-| C-Tier | Fair - Some concerns |
-| D-Tier | Poor - Significant issues |
-| F-Tier | Critical - Leaking secrets |
+| Score | Meaning | Action Required |
+|-------|---------|-----------------|
+| **A-Tier** | Excellent | No security issues detected |
+| **B-Tier** | Good | Minor improvements recommended |
+| **C-Tier** | Fair | Some concerns need attention |
+| **D-Tier** | Poor | Significant issues found |
+| **F-Tier** | Critical | Secrets or major vulnerabilities exposed |
 
 ## Example Output
 
 ```
-Cencori Scan
-v0.1.0
+  Cencori Scan
+  v0.3.4
+
+✔ Scanned 142 files
+
+  ┌─────────────────────────────────────────────┐
+  │   Security Score: D-Tier                    │
+  └─────────────────────────────────────────────┘
 
-Scanned 142 files
+  Poor! Significant security issues found.
 
-┌─────────────────────────────────────────────┐
-│   Security Score: F-Tier                    │
-└─────────────────────────────────────────────┘
+  SECRETS (3)
+  ├─ src/api.ts:12  sk-proj-****
+  │  Hardcoded API key - use environment variables
+  ├─ src/lib.ts:5   eyJh****
+  │  Supabase service role key exposed
+  └─ .env.local:3   ANTH****
+     Anthropic API key in tracked file
 
-SECRETS (3)
-├─ src/api.ts:12  sk-proj-****
-├─ src/lib.ts:5   eyJh****
-└─ .env.local:3   ANTH****
+  VULNERABILITIES (2)
+  ├─ src/db.ts:45  `SELECT * FROM users WHERE id = ${userId}`
+  │  Potential SQL injection - use parameterized queries
+  └─ src/page.tsx:23  dangerouslySetInnerHTML={{ __html: content }}
+     XSS vulnerability - sanitize content first
 
-Recommendations:
-  - Use environment variables for secrets
-  - Never commit API keys to version control
+  ─────────────────────────────────────────────
 
-Share: https://scan.cencori.com
-Docs:  https://cencori.com/docs
+  Summary
+    Files scanned: 142
+    Scan time: 89ms
+
+  Recommendations:
+    - Use environment variables for secrets
+    - Never commit API keys to version control
+    - Sanitize user input before rendering HTML
+
+? Would you like Cencori to auto-fix these issues? (y/n)
 ```
 
 ## Programmatic Usage
@@ -89,10 +175,106 @@ import { scan } from '@cencori/scan';
 
 const result = await scan('./my-project');
 
-console.log(result.score);  // 'A' | 'B' | 'C' | 'D' | 'F'
-console.log(result.issues); // Array of detected issues
+console.log(result.score);        // 'A' | 'B' | 'C' | 'D' | 'F'
+console.log(result.issues);       // Array of detected issues
+console.log(result.filesScanned); // Number of files scanned
+console.log(result.scanDuration); // Time in milliseconds
+```
+
+### TypeScript Types
+
+```typescript
+interface ScanResult {
+  score: 'A' | 'B' | 'C' | 'D' | 'F';
+  tierDescription: string;
+  issues: ScanIssue[];
+  filesScanned: number;
+  scanDuration: number;
+  summary: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+  };
+}
+
+interface ScanIssue {
+  type: 'secret' | 'pii' | 'route' | 'config' | 'vulnerability';
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  name: string;
+  match: string;
+  file: string;
+  line: number;
+  description?: string;
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Security Scan
+
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Cencori Scan
+        run: npx @cencori/scan --json > scan-results.json
+      - name: Check for failures
+        run: |
+          SCORE=$(jq -r '.score' scan-results.json)
+          if [[ "$SCORE" == "F" ]]; then
+            echo "Security scan failed with F-Tier score"
+            exit 1
+          fi
 ```
 
+### Pre-commit Hook
+
+Add to `.husky/pre-commit`:
+
+```bash
+#!/bin/sh
+npx @cencori/scan --quiet --no-prompt
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CENCORI_API_KEY` | API key for AI features (optional) |
+
+### Config File
+
+API keys are automatically saved to `~/.cencorirc`:
+
+```
+api_key=your_cencori_api_key
+```
+
+## Privacy
+
+Cencori Scan collects **anonymous usage metrics** to improve the product:
+- Number of files scanned
+- Number of issues found
+- Security score
+- Platform (macOS/Linux/Windows)
+
+**No code, file paths, or sensitive data is ever transmitted.**
+
+## Links
+
+- **Documentation**: [cencori.com/docs](https://cencori.com/docs)
+- **Dashboard**: [cencori.com/dashboard](https://cencori.com/dashboard)
+- **Web Scanner**: [scan.cencori.com](https://scan.cencori.com)
+
 ## License
 
-MIT - Cencori
+MIT - [Cencori](https://cencori.com)

package/dist/cli.js

@@ -925,10 +925,58 @@ async function applyFixes(fixes, fileContents) {
   return fixes;
 }
 
+// src/telemetry.ts
+var TELEMETRY_URL = "https://cencori.com/api/v1/telemetry/scan";
+var pendingTelemetry = null;
+function sendTelemetry(data) {
+  pendingTelemetry = fetch(TELEMETRY_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(data)
+  }).then(() => {
+  }).catch(() => {
+  });
+  return pendingTelemetry;
+}
+async function flushTelemetry() {
+  if (pendingTelemetry) {
+    await pendingTelemetry;
+    pendingTelemetry = null;
+  }
+}
+function buildTelemetryData(result, version, hasApiKey) {
+  const breakdown = {
+    secrets: 0,
+    pii: 0,
+    routes: 0,
+    config: 0,
+    vulnerabilities: 0
+  };
+  for (const issue of result.issues) {
+    const type = issue.type;
+    if (type in breakdown) {
+      breakdown[type]++;
+    }
+  }
+  return {
+    event: "scan_completed",
+    version,
+    platform: process.platform,
+    filesScanned: result.filesScanned,
+    issuesFound: result.issues.length,
+    score: result.score,
+    hasApiKey,
+    scanDuration: result.scanDuration,
+    issueBreakdown: breakdown
+  };
+}
+
 // src/cli.ts
 var fs3 = __toESM(require("fs"));
 var path3 = __toESM(require("path"));
-var VERSION = "0.3.3";
+var VERSION = "0.3.4";
 var scoreStyles = {
   A: { color: import_chalk.default.green },
   B: { color: import_chalk.default.blue },
@@ -1192,7 +1240,9 @@ async function main() {
   import_commander.program.name("cencori-scan").description("Security scanner for AI apps. Detect secrets, PII, and exposed routes.").version(VERSION).argument("[path]", "Path to scan", ".").option("-j, --json", "Output results as JSON").option("-q, --quiet", "Only output the score").option("--no-prompt", "Skip interactive prompts").option("--no-color", "Disable colored output").action(async (targetPath, options) => {
     if (options.json) {
       const result = await scan(targetPath);
+      sendTelemetry(buildTelemetryData(result, VERSION, !!getApiKey()));
       console.log(JSON.stringify(result, null, 2));
+      await flushTelemetry();
       process.exit(result.score === "A" || result.score === "B" ? 0 : 1);
       return;
     }
@@ -1203,12 +1253,14 @@ async function main() {
     }).start();
     try {
       const result = await scan(targetPath);
+      sendTelemetry(buildTelemetryData(result, VERSION, !!getApiKey()));
       spinner.succeed(`Scanned ${result.filesScanned} files`);
       if (options.quiet) {
         const style = scoreStyles[result.score];
         console.log(`
   Score: ${style.color.bold(result.score + "-Tier")}
 `);
+        await flushTelemetry();
         process.exit(result.score === "A" || result.score === "B" ? 0 : 1);
         return;
       }
@@ -1220,11 +1272,13 @@ async function main() {
         await handleAutoFix(result, targetPath);
       }
       printFooter();
+      await flushTelemetry();
       process.exit(result.score === "A" || result.score === "B" ? 0 : 1);
     } catch (error) {
       spinner.fail("Scan failed");
       console.error(import_chalk.default.red(`
   Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+      await flushTelemetry();
       process.exit(1);
     }
   });