kramscan 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Akram Shaikh
+Copyright (c) 2026 Akram Shaikh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -42,15 +42,17 @@ Web security is complex and often fragmented. Developers rely on multiple disjoi
 ## ✨ Key Features
 | Feature | Description |
 | :--- | :--- |
-| 🔍 **Automated Vulnerability Engine** | Detects XSS, SQL Injection, CSRF, insecure headers, and more using Puppeteer-powered crawling. |
-| 🔌 **Modular Plugin System** | Extensible architecture for custom vulnerability detection plugins. Built-in plugins for common vulnerabilities. |
+| 🔍 **Automated Vulnerability Engine** | Detects XSS, SQL Injection, CSRF, insecure headers, CORS misconfigs, open redirects, and more. |
+| 🔌 **10 Built-in Security Plugins** | CORS, debug endpoints, directory traversal, cookie auditing, open redirects, sensitive data, and more. |
+| 🛠️ **Dev Mode (Watch Scanner)** | Watch your localhost for file changes and auto re-scan with diff reports (new vs resolved vulns). |
+| 🚧 **CI/CD Security Gate** | `kramscan gate` exits with code 1 if vulnerabilities exceed your threshold. Plug into any pipeline. |
 | 🤖 **Interactive AI Agent** | A conversational security assistant with **Autonomous Verification** skills to confirm findings live. |
 | 🧠 **Multi-Provider AI Analysis** | Supports OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, and more for results auditing. |
 | 📝 **AI Executive Summaries** | Automatically generates business-oriented summaries for Word, JSON, and TXT reports. |
 | 📊 **Event-Driven Feedback** | Real-time progress updates with dynamic spinners and live vulnerability alerts during scanning. |
 | 📄 **Professional Reporting** | Generates detailed PDF, DOCX, TXT, and JSON reports with remediation steps and error tracking. |
 | 🌐 **Headless Browser Testing** | Renders modern SPAs (Single Page Applications) to find vulnerabilities in dynamic content. |
-| ⚡ **Smarter User Flow** | Revamped interactive menu and post-scan "Golden Path" prompts for a guided experience. |
+| ⚡ **Smarter User Flow** | Interactive menu and post-scan "Golden Path" prompts for a guided experience. |
 | 🛡️ **Error Resilience** | Robust configuration defaults and graceful recovery if individual URLs or plugins fail. |
 
 <br />
@@ -82,19 +84,24 @@ graph LR
 
 ### Plugin Architecture
 
-KramScan now features a modular plugin system that makes extending vulnerability detection effortless:
+KramScan is built on a modular plugin system that makes extending vulnerability detection effortless:
 
 ```
 src/plugins/
-├── types.ts              # Base interfaces and types
-├── PluginManager.ts      # Plugin orchestration
-├── index.ts             # Plugin exports
-└── vulnerabilities/     # Built-in plugins
-    ├── XSSPlugin.ts
-    ├── SQLInjectionPlugin.ts
-    ├── SecurityHeadersPlugin.ts
-    ├── SensitiveDataPlugin.ts
-    └── CSRFPlugin.ts
+├── types.ts                        # Base interfaces and types
+├── PluginManager.ts                # Plugin orchestration
+├── index.ts                        # Plugin exports
+└── vulnerabilities/                # Built-in plugins
+    ├── XSSPlugin.ts                # Cross-Site Scripting
+    ├── SQLInjectionPlugin.ts       # SQL Injection
+    ├── SecurityHeadersPlugin.ts    # Missing security headers
+    ├── SensitiveDataPlugin.ts      # Exposed secrets & API keys
+    ├── CSRFPlugin.ts               # Cross-Site Request Forgery
+    ├── CORSAnalyzerPlugin.ts       # CORS misconfiguration
+    ├── DebugEndpointPlugin.ts      # Exposed debug/dev endpoints
+    ├── DirectoryTraversalPlugin.ts # Path traversal / LFI
+    ├── CookieSecurityPlugin.ts     # Insecure cookie flags
+    └── OpenRedirectPlugin.ts       # Open redirect detection
 ```
 
 **Creating a custom plugin:**
@@ -183,10 +190,10 @@ You can provide API keys via environment variables (useful for CI/CD) instead of
 KramScan automatically detects API keys in your environment variables. During `kramscan onboard`, the tool will identify and pre-configure providers like OpenAI, Anthropic, and Gemini if their keys are found in your session.
 
 ### AI-Powered Context-Aware Payloads
-The scanning engine now utilizes AI to generate payloads tailored to the specific context of your application, significantly increasing detection rates against filtered inputs and complex WAFs.
+The scanning engine utilizes AI to generate payloads tailored to the specific context of your application, significantly increasing detection rates against filtered inputs and complex WAFs.
 
 ### Autonomous Finding Verification
-The `kramscan agent` can now independently verify reported vulnerabilities using non-destructive, context-aware payloads to differentiate between theoretical findings and exploitable risks.
+The `kramscan agent` independently verifies reported vulnerabilities using non-destructive, context-aware payloads to differentiate between theoretical findings and exploitable risks.
 
 <br />
 
@@ -225,18 +232,64 @@ kramscan scan https://example.com
 
 ## 📖 Usage & Commands
 
-| Command | Description | Status |
-| :--- | :--- | :---: |
-| `kramscan` | Launch the interactive dashboard menu with smart argument prompting. | ✅ Stable |
-| `kramscan scan <url>` | Run a comprehensive vulnerability scan with post-scan prompts. | ✅ Stable |
-| `kramscan agent` | Start the AI security assistant with autonomous verification skills. | ✅ Stable |
-| `kramscan analyze` | AI-powered analysis with proactive onboarding redirection. | ✅ Stable |
-| `kramscan report` | Generate professional reports with optional AI executive summaries. | ✅ Stable |
-| `kramscan onboard` | Smart setup wizard with environment key detection. | ✅ Stable |
-| `kramscan doctor` | Verify environment health and check for Docker dependencies. | ✅ Stable |
-| `kramscan config` | View and edit current configuration with robust schema defaults. | ✅ Stable |
-| `kramscan scans` | List and inspect recent scans from the persistent index. | ✅ Stable |
-| `kramscan ai` | AI helpers (model listing and connectivity test). | ✅ Stable |
+| Command | Description |
+| :--- | :--- |
+| `kramscan` | Launch the interactive dashboard menu with smart argument prompting. |
+| `kramscan scan <url>` | Run a comprehensive vulnerability scan with post-scan prompts. |
+| `kramscan dev [url]` | Watch-mode localhost scanner with diff reports and desktop notifications. |
+| `kramscan gate <url>` | CI/CD security quality gate — exits with code 1 on threshold breach. |
+| `kramscan agent` | Start the AI security assistant with autonomous verification skills. |
+| `kramscan analyze` | AI-powered analysis with proactive onboarding redirection. |
+| `kramscan report` | Generate professional reports with optional AI executive summaries. |
+| `kramscan onboard` | Smart setup wizard with environment key detection. |
+| `kramscan doctor` | Verify environment health and check for Docker dependencies. |
+| `kramscan config` | View and edit current configuration with robust schema defaults. |
+| `kramscan scans` | List and inspect recent scans from the persistent index. |
+| `kramscan ai` | AI helpers (model listing and connectivity test). |
+
+<br />
+
+### 🛠️ Dev Mode — Localhost Watch Scanner
+
+Scan your local dev server continuously. KramScan watches for file changes and **auto re-scans**, showing a diff of new vs. resolved vulnerabilities:
+
+```bash
+# Watch-mode with port shorthand
+kramscan dev --port 3000
+
+# Full URL with notifications
+kramscan dev http://localhost:3000 --watch-dir ./src --notify
+
+# Single scan (no watching)
+kramscan dev http://localhost:8080 --no-watch --fail-on high
+```
+
+**How it works:**
+1. Probes your server until it's ready (auto-detects Express, Next.js, Django, etc.)
+2. Runs an initial security scan
+3. Watches `--watch-dir` for file changes (debounced)
+4. Re-scans and shows only **new** and **resolved** vulnerabilities
+
+### 🚧 CI/CD Security Gate
+
+Block deployments with vulnerabilities above your threshold:
+
+```bash
+# Fail if any high+ vulnerabilities found
+kramscan gate http://localhost:3000 --fail-on high
+
+# JSON output for pipeline processing
+kramscan gate $APP_URL --fail-on medium --json
+
+# Allow up to 3 low-severity findings
+kramscan gate http://staging.example.com --fail-on low --max-vulns 3
+```
+
+**Pipeline example (GitHub Actions):**
+```yaml
+- name: Security Gate
+  run: npx kramscan gate http://localhost:3000 --fail-on high
+```
 
 <br />
 
@@ -272,7 +325,7 @@ kramscan scan https://example.com --no-pdf
 ```
 
 ### Error Tracking and Recovery
-KramScan now features comprehensive error handling:
+KramScan features comprehensive error handling:
 
 - **Continue on Failure**: Scan continues even if individual URLs fail to load
 - **Plugin Error Isolation**: If one vulnerability plugin fails, others continue working
@@ -327,33 +380,7 @@ Agent: Scan complete! Found 2 High severity issues.
 
 ---
 
-<br />
 
-## 🗺️ Roadmap
-
-- [x] Core vulnerability scanner (XSS, SQLi, CSRF, headers)
-- [x] Multi-provider AI analysis engine
-- [x] Interactive AI agent mode
-- [x] Professional report generation (DOCX, TXT, JSON)
-- [x] Configuration wizard & management
-- [x] **Plugin system for custom scan modules** ✅
-- [x] **PDF report generation** ✅
-- [x] **Event-driven progress feedback** ✅
-- [x] **Error resilience and recovery** ✅
-- [x] **Zod schema validation** ✅
-- [x] **AI Executive Summaries** ✅
-- [x] **Autonomous Verification Agent** ✅
-- [x] **Smarter Interactive Flows** ✅
-- [ ] CI/CD integration (GitHub Actions, GitLab CI)
-- [ ] Web-based dashboard UI
-- [ ] SARIF export format
-- [ ] OWASP ZAP integration
-
-<br />
-
----
-
-<br />
 
 ## 🔒 Security & Privacy
 - **Local Execution:** All scanning logic runs locally on your machine.

package/dist/cli.js

@@ -51,6 +51,8 @@ const doctor_1 = require("./commands/doctor");
 const agent_1 = require("./commands/agent");
 const scans_1 = require("./commands/scans");
 const ai_1 = require("./commands/ai");
+const dev_1 = require("./commands/dev");
+const gate_1 = require("./commands/gate");
 const config_2 = require("./core/config");
 const theme_1 = require("./utils/theme");
 let verboseMode = false;
@@ -70,6 +72,8 @@ const menuChoices = [
     { label: "Agent", value: "agent", description: "AI-powered interactive security assistant", icon: "🤖", status: "active" },
     { label: "Onboard", value: "onboard", description: "First-time setup wizard", icon: "⚡", status: "active" },
     { label: "Scan", value: "scan", description: "Scan a target URL for vulnerabilities", icon: "🔍", status: "active" },
+    { label: "Dev", value: "dev", description: "Watch-mode scanning for localhost dev servers", icon: "🛠️", status: "active" },
+    { label: "Gate", value: "gate", description: "CI/CD security quality gate", icon: "🚧", status: "active" },
     { label: "Analyze", value: "analyze", description: "Deep AI analysis of scan results", icon: "🧠", status: "active" },
     { label: "Report", value: "report", description: "Generate a professional report", icon: "📄", status: "active" },
     { label: "Config", value: "config", description: "View or edit your configuration", icon: "⚙️", status: "active" },
@@ -220,6 +224,8 @@ function createProgram() {
     (0, agent_1.registerAgentCommand)(program);
     (0, scans_1.registerScansCommand)(program);
     (0, ai_1.registerAiCommand)(program);
+    (0, dev_1.registerDevCommand)(program);
+    (0, gate_1.registerGateCommand)(program);
     // Version subcommand with detailed environment info
     program
         .command("version")

package/dist/commands/dev.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerDevCommand(program: Command): void;

package/dist/commands/dev.js

@@ -0,0 +1,236 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDevCommand = registerDevCommand;
+const scanner_1 = require("../core/scanner");
+const server_probe_1 = require("../core/server-probe");
+const diff_engine_1 = require("../core/diff-engine");
+const theme_1 = require("../utils/theme");
+const logger_1 = require("../utils/logger");
+const theme_2 = require("../utils/theme");
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+function registerDevCommand(program) {
+    program
+        .command("dev [url]")
+        .description("Watch-mode security scanning for localhost development servers")
+        .option("--port <number>", "Shorthand for http://localhost:<port>")
+        .option("--watch-dir <path>", "Directory to watch for file changes", "./src")
+        .option("--debounce <ms>", "Debounce time before re-scanning (ms)", "2000")
+        .option("--profile <name>", "Scan profile: quick|balanced", "quick")
+        .option("--notify", "Enable desktop notifications for critical findings")
+        .option("--fail-on <severity>", "Exit with code 1 if severity threshold met")
+        .option("--no-watch", "Run a single scan without watching (useful for CI)")
+        .action(async (url, options) => {
+        // Resolve target URL
+        const targetUrl = url || (options.port ? `http://localhost:${options.port}` : null);
+        if (!targetUrl) {
+            console.log("");
+            console.log(theme_1.theme.error("✗ No target URL specified."));
+            console.log(theme_1.theme.gray("  Usage: kramscan dev http://localhost:3000"));
+            console.log(theme_1.theme.gray("     or: kramscan dev --port 3000"));
+            console.log("");
+            process.exit(1);
+        }
+        const isLocal = (0, server_probe_1.isLocalhost)(targetUrl);
+        console.log("");
+        console.log(theme_1.theme.brand.bold("🛠️  KramScan Dev Mode"));
+        console.log(theme_1.theme.gray("─".repeat(50)));
+        console.log("");
+        console.log(theme_1.theme.white("Target:"), theme_1.theme.cyan(targetUrl));
+        console.log(theme_1.theme.white("Profile:"), theme_1.theme.cyan(options.profile));
+        if (isLocal) {
+            console.log(theme_1.theme.white("Environment:"), theme_1.theme.green("localhost (dev mode)"));
+        }
+        console.log("");
+        // Probe server readiness
+        const probeSpinner = logger_1.logger.spinner(`Waiting for ${targetUrl} to be ready...`);
+        const probeResult = await (0, server_probe_1.probeServer)(targetUrl, { timeout: 30000 });
+        if (!probeResult.reachable) {
+            probeSpinner.fail(`Server at ${targetUrl} is not responding`);
+            console.log("");
+            console.log(theme_1.theme.warning("⚠️  Make sure your dev server is running:"));
+            console.log(theme_1.theme.gray("  • npm run dev"));
+            console.log(theme_1.theme.gray("  • yarn dev"));
+            console.log(theme_1.theme.gray("  • python manage.py runserver"));
+            console.log("");
+            process.exit(1);
+        }
+        probeSpinner.succeed(`Server ready! (${probeResult.responseTime}ms` +
+            `${probeResult.framework ? `, ${probeResult.framework}` : ""}` +
+            `${probeResult.server ? `, ${probeResult.server}` : ""})`);
+        // Run initial scan
+        let previousResult = null;
+        const runScan = async (isRescan = false) => {
+            const scanSpinner = logger_1.logger.spinner(isRescan ? "Re-scanning after code change..." : "Running initial security scan...");
+            try {
+                const scanner = new scanner_1.Scanner(true);
+                const scanOptions = {
+                    depth: 2,
+                    timeout: 10000,
+                    headless: true,
+                    maxPages: 15,
+                    maxLinksPerPage: 30,
+                    profile: options.profile,
+                };
+                const result = await scanner.scan(targetUrl, scanOptions);
+                scanSpinner.succeed(isRescan
+                    ? `Re-scan complete: ${result.summary.total} vulnerabilities`
+                    : `Initial scan complete: ${result.summary.total} vulnerabilities`);
+                await scanner.close();
+                if (isRescan && previousResult) {
+                    // Show diff
+                    const diff = (0, diff_engine_1.diffScanResults)(previousResult, result);
+                    displayDiff(diff);
+                }
+                else {
+                    // Show full summary for initial scan
+                    (0, theme_1.displayScanSummary)({
+                        target: result.target,
+                        duration: result.duration,
+                        metadata: result.metadata,
+                        summary: result.summary,
+                        vulnerabilities: result.vulnerabilities,
+                        score: result.score,
+                        filepath: "(dev mode — results in memory)",
+                    });
+                }
+                // Desktop notification for critical/high findings
+                if (options.notify && result.summary.critical + result.summary.high > 0) {
+                    try {
+                        // node-notifier is optional — skip if not installed
+                        // eslint-disable-next-line @typescript-eslint/no-var-requires
+                        const notifier = require("node-notifier");
+                        notifier.notify({
+                            title: "⚠️ KramScan Security Alert",
+                            message: `Found ${result.summary.critical} critical, ${result.summary.high} high vulnerabilities on ${targetUrl}`,
+                            sound: true,
+                        });
+                    }
+                    catch {
+                        // node-notifier not installed, skip silently
+                    }
+                }
+                // Check fail threshold
+                if (options.failOn) {
+                    const shouldFail = checkThreshold(result, options.failOn);
+                    if (shouldFail && !options.watch) {
+                        console.log(theme_1.theme.error(`\n✗ Security gate failed: found vulnerabilities at or above '${options.failOn}' severity.\n`));
+                        process.exit(1);
+                    }
+                }
+                return result;
+            }
+            catch (err) {
+                scanSpinner.fail(`Scan failed: ${err.message}`);
+                return previousResult;
+            }
+        };
+        // Initial scan
+        previousResult = await runScan(false);
+        // Watch mode
+        if (options.watch !== false) {
+            const watchDir = path_1.default.resolve(options.watchDir);
+            try {
+                await promises_1.default.access(watchDir);
+            }
+            catch {
+                console.log(theme_1.theme.warning(`⚠️  Watch directory not found: ${watchDir}`));
+                console.log(theme_1.theme.gray("  Falling back to current directory."));
+            }
+            console.log("");
+            console.log(theme_1.theme.brand("👁️  Watching for changes..."));
+            console.log(theme_1.theme.gray(`  Directory: ${watchDir}`));
+            console.log(theme_1.theme.gray(`  Debounce: ${options.debounce}ms`));
+            console.log(theme_1.theme.gray("  Press Ctrl+C to stop."));
+            console.log("");
+            // Use fs.watch with recursive option (Node.js 19+)
+            let debounceTimer = null;
+            let scanning = false;
+            try {
+                const watcher = promises_1.default.watch(watchDir, { recursive: true });
+                for await (const event of watcher) {
+                    if (scanning)
+                        continue;
+                    // Ignore node_modules, dist, .git, etc.
+                    const filename = event.filename || "";
+                    if (filename.includes("node_modules") ||
+                        filename.includes("dist") ||
+                        filename.includes(".git") ||
+                        filename.includes(".next") ||
+                        filename.includes("__pycache__")) {
+                        continue;
+                    }
+                    if (debounceTimer)
+                        clearTimeout(debounceTimer);
+                    debounceTimer = setTimeout(async () => {
+                        scanning = true;
+                        console.log("");
+                        console.log(theme_1.theme.dim(`📝 Change detected: ${filename}`));
+                        previousResult = await runScan(true);
+                        scanning = false;
+                    }, parseInt(options.debounce, 10));
+                }
+            }
+            catch (err) {
+                console.log(theme_1.theme.warning(`⚠️  File watching failed: ${err.message}`));
+                console.log(theme_1.theme.gray("  Make sure the watch directory exists and is readable."));
+            }
+        }
+    });
+}
+function displayDiff(diff) {
+    console.log("");
+    console.log(theme_1.theme.brightWhite.bold("🔄 Scan Diff Report"));
+    console.log(theme_1.theme.gray("─".repeat(50)));
+    if (diff.newVulnerabilities.length === 0 && diff.resolvedVulnerabilities.length === 0) {
+        console.log(theme_1.theme.gray("  No changes since last scan."));
+        console.log(theme_1.theme.gray(`  ${diff.unchangedCount} vulnerabilities unchanged.`));
+    }
+    else {
+        // New vulnerabilities
+        if (diff.newVulnerabilities.length > 0) {
+            console.log("");
+            console.log(theme_1.theme.error(`  🆕 ${diff.newVulnerabilities.length} New Vulnerabilities`));
+            for (const v of diff.newVulnerabilities) {
+                const color = (0, theme_2.getSeverityColor)(v.severity);
+                console.log(color(`    [${v.severity.toUpperCase()}] ${v.title}`));
+                console.log(theme_1.theme.gray(`      ${v.url}`));
+            }
+        }
+        // Resolved vulnerabilities
+        if (diff.resolvedVulnerabilities.length > 0) {
+            console.log("");
+            console.log(theme_1.theme.success(`  ✅ ${diff.resolvedVulnerabilities.length} Resolved`));
+            for (const v of diff.resolvedVulnerabilities) {
+                console.log(theme_1.theme.green(`    ✓ ${v.title}`));
+            }
+        }
+        console.log("");
+        console.log(theme_1.theme.gray(`  Total: ${diff.previousTotal} → ${diff.currentTotal} `) +
+            (diff.currentTotal < diff.previousTotal
+                ? theme_1.theme.green(`(↓ ${diff.previousTotal - diff.currentTotal})`)
+                : diff.currentTotal > diff.previousTotal
+                    ? theme_1.theme.error(`(↑ ${diff.currentTotal - diff.previousTotal})`)
+                    : theme_1.theme.gray("(no change)")));
+    }
+    console.log("");
+}
+function checkThreshold(result, failOn) {
+    const severityLevels = {
+        critical: 4,
+        high: 3,
+        medium: 2,
+        low: 1,
+        info: 0,
+    };
+    const threshold = severityLevels[failOn.toLowerCase()] ?? 3;
+    for (const v of result.vulnerabilities) {
+        if ((severityLevels[v.severity] ?? 0) >= threshold) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/commands/gate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerGateCommand(program: Command): void;

package/dist/commands/gate.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGateCommand = registerGateCommand;
+const scanner_1 = require("../core/scanner");
+const server_probe_1 = require("../core/server-probe");
+const theme_1 = require("../utils/theme");
+const logger_1 = require("../utils/logger");
+function registerGateCommand(program) {
+    program
+        .command("gate <url>")
+        .description("CI/CD security quality gate — scan and exit with code 1 if thresholds are breached")
+        .option("--fail-on <severity>", "Minimum severity to fail on (critical|high|medium|low)", "high")
+        .option("--max-vulns <number>", "Maximum allowed vulnerabilities before failing", "0")
+        .option("--profile <name>", "Scan profile: quick|balanced|deep", "quick")
+        .option("--timeout <ms>", "Maximum scan duration", "60000")
+        .option("--json", "Output results as JSON")
+        .action(async (url, options) => {
+        const jsonMode = options.json === true;
+        if (!jsonMode) {
+            console.log("");
+            console.log(theme_1.theme.brand.bold("🚧 KramScan Security Gate"));
+            console.log(theme_1.theme.gray("─".repeat(50)));
+            console.log("");
+        }
+        // Probe server
+        if (!jsonMode) {
+            const probeSpinner = logger_1.logger.spinner(`Checking server at ${url}...`);
+            const probeResult = await (0, server_probe_1.probeServer)(url, { timeout: 10000, maxAttempts: 5 });
+            if (!probeResult.reachable) {
+                probeSpinner.fail(`Server at ${url} is not responding`);
+                if (jsonMode) {
+                    console.log(JSON.stringify({ error: "Server unreachable", passed: false }));
+                }
+                process.exit(1);
+            }
+            probeSpinner.succeed(`Server ready (${probeResult.responseTime}ms)`);
+        }
+        // Run scan
+        const scanSpinner = jsonMode ? null : logger_1.logger.spinner("Running security scan...");
+        try {
+            const scanner = new scanner_1.Scanner(true);
+            const scanOptions = {
+                depth: 2,
+                timeout: parseInt(options.timeout, 10) || 60000,
+                headless: true,
+                maxPages: 20,
+                maxLinksPerPage: 30,
+                profile: options.profile,
+            };
+            const result = await scanner.scan(url, scanOptions);
+            await scanner.close();
+            if (scanSpinner)
+                scanSpinner.succeed(`Scan complete: ${result.summary.total} vulnerabilities`);
+            // Evaluate threshold
+            const severityLevels = {
+                critical: 4, high: 3, medium: 2, low: 1, info: 0,
+            };
+            const threshold = severityLevels[options.failOn.toLowerCase()] ?? 3;
+            const maxVulns = parseInt(options.maxVulns, 10) || 0;
+            const vulnsAboveThreshold = result.vulnerabilities.filter((v) => (severityLevels[v.severity] ?? 0) >= threshold);
+            const passed = vulnsAboveThreshold.length <= maxVulns;
+            if (jsonMode) {
+                console.log(JSON.stringify({
+                    passed,
+                    total: result.summary.total,
+                    threshold: options.failOn,
+                    vulnsAboveThreshold: vulnsAboveThreshold.length,
+                    maxAllowed: maxVulns,
+                    summary: result.summary,
+                    vulnerabilities: vulnsAboveThreshold,
+                }, null, 2));
+            }
+            else {
+                console.log("");
+                if (passed) {
+                    console.log(theme_1.theme.success.bold("✅ SECURITY GATE: PASSED"));
+                    console.log(theme_1.theme.gray(`   ${result.summary.total} total vulnerabilities found`));
+                    console.log(theme_1.theme.gray(`   ${vulnsAboveThreshold.length} at or above '${options.failOn}' severity (max allowed: ${maxVulns})`));
+                }
+                else {
+                    console.log(theme_1.theme.error.bold("❌ SECURITY GATE: FAILED"));
+                    console.log(theme_1.theme.error(`   ${vulnsAboveThreshold.length} vulnerabilities at or above '${options.failOn}' severity (max allowed: ${maxVulns})`));
+                    console.log("");
+                    for (const v of vulnsAboveThreshold.slice(0, 10)) {
+                        const color = v.severity === "critical" ? theme_1.theme.critical : theme_1.theme.high;
+                        console.log(color(`   [${v.severity.toUpperCase()}] ${v.title}`));
+                        console.log(theme_1.theme.gray(`     ${v.url}`));
+                        if (v.remediation) {
+                            console.log(theme_1.theme.dim(`     Fix: ${v.remediation}`));
+                        }
+                    }
+                    if (vulnsAboveThreshold.length > 10) {
+                        console.log(theme_1.theme.gray(`   ... and ${vulnsAboveThreshold.length - 10} more`));
+                    }
+                }
+                console.log("");
+            }
+            process.exit(passed ? 0 : 1);
+        }
+        catch (err) {
+            if (scanSpinner)
+                scanSpinner.fail(`Scan failed: ${err.message}`);
+            if (jsonMode) {
+                console.log(JSON.stringify({ error: err.message, passed: false }));
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/scan.js

@@ -226,6 +226,7 @@ function registerScanCommand(program) {
                 metadata: result.metadata,
                 summary: result.summary,
                 vulnerabilities: result.vulnerabilities,
+                score: result.score,
                 filepath,
                 pdfPath,
             });

package/dist/commands/scans.js

@@ -30,6 +30,10 @@ function registerScansCommand(program) {
                 console.log(chalk_1.default.gray("  PDF :"), chalk_1.default.white(entry.pdfPath));
             }
             console.log(chalk_1.default.gray("  Findings:"), chalk_1.default.white(`${entry.summary.total} total (${entry.summary.critical}C ${entry.summary.high}H ${entry.summary.medium}M ${entry.summary.low}L ${entry.summary.info}I)`));
+            if (entry.score !== undefined) {
+                const scoreColor = entry.score > 80 ? chalk_1.default.green : (entry.score > 50 ? chalk_1.default.yellow : chalk_1.default.red);
+                console.log(chalk_1.default.gray("  Score   :"), scoreColor(`${entry.score}/100`));
+            }
             console.log("");
         }
     });

package/dist/core/config-schema.js

@@ -39,7 +39,7 @@ exports.ConfigSchema = zod_1.z.object({
     scan: zod_1.z.object({
         defaultTimeout: zod_1.z.number().int().min(1000).default(30000),
         maxThreads: zod_1.z.number().int().min(1).max(20).default(5),
-        userAgent: zod_1.z.string().default("KramScan/0.1.1"),
+        userAgent: zod_1.z.string().default("KramScan/0.2.0"),
         followRedirects: zod_1.z.boolean().default(true),
         verifySSL: zod_1.z.boolean().default(true),
         rateLimitPerSecond: zod_1.z.number().int().min(1).max(100).default(5),

package/dist/core/config.js

@@ -64,7 +64,7 @@ const defaults = {
         enabled: false,
     },
     scan: {
-        defaultTimeout: 60,
+        defaultTimeout: 30000,
         maxThreads: 5,
         userAgent: `KramScan/${theme_1.CLI_VERSION}`,
         followRedirects: true,
@@ -81,8 +81,8 @@ const defaults = {
         severityThreshold: "low",
     },
     skills: {
-        sqli: { enabled: true, timeout: 120 },
-        xss: { enabled: true, timeout: 90 },
+        sqli: { enabled: true, timeout: 120000 },
+        xss: { enabled: true, timeout: 90000 },
         headers: { enabled: true },
         csrf: { enabled: true },
         idor: { enabled: true },

package/dist/core/diff-engine.d.ts

@@ -0,0 +1,12 @@
+import { Vulnerability, ScanResult } from "./vulnerability-detector";
+export interface ScanDiff {
+    newVulnerabilities: Vulnerability[];
+    resolvedVulnerabilities: Vulnerability[];
+    unchangedCount: number;
+    previousTotal: number;
+    currentTotal: number;
+}
+/**
+ * Compares two scan results and produces a diff of new and resolved vulnerabilities.
+ */
+export declare function diffScanResults(previous: ScanResult, current: ScanResult): ScanDiff;