kramscan 0.1.1 → 0.3.0

package/dist/core/server-probe.d.ts

@@ -0,0 +1,20 @@
+export interface ProbeResult {
+    reachable: boolean;
+    statusCode?: number;
+    server?: string;
+    framework?: string;
+    responseTime: number;
+}
+/**
+ * Probes a localhost URL for server readiness.
+ * Polls with exponential backoff until the server responds or timeout is reached.
+ */
+export declare function probeServer(url: string, options?: {
+    timeout?: number;
+    interval?: number;
+    maxAttempts?: number;
+}): Promise<ProbeResult>;
+/**
+ * Checks if a URL points to localhost.
+ */
+export declare function isLocalhost(url: string): boolean;

package/dist/core/server-probe.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeServer = probeServer;
+exports.isLocalhost = isLocalhost;
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+/**
+ * Probes a localhost URL for server readiness.
+ * Polls with exponential backoff until the server responds or timeout is reached.
+ */
+async function probeServer(url, options = {}) {
+    const { timeout = 30000, interval = 1000, maxAttempts = 20 } = options;
+    const startTime = Date.now();
+    let attempts = 0;
+    let lastError = null;
+    while (attempts < maxAttempts && Date.now() - startTime < timeout) {
+        attempts++;
+        try {
+            const result = await pingUrl(url);
+            if (result.reachable) {
+                return result;
+            }
+            lastError = `HTTP ${result.statusCode}`;
+        }
+        catch (err) {
+            lastError = err.message;
+        }
+        // Exponential backoff with cap
+        const delay = Math.min(interval * Math.pow(1.5, attempts - 1), 5000);
+        await sleep(delay);
+    }
+    return {
+        reachable: false,
+        responseTime: Date.now() - startTime,
+    };
+}
+/**
+ * Single ping to a URL — returns immediately.
+ */
+function pingUrl(url) {
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const parsedUrl = new URL(url);
+        const client = parsedUrl.protocol === "https:" ? https_1.default : http_1.default;
+        const req = client.get(url, {
+            timeout: 5000,
+            rejectUnauthorized: false, // Allow self-signed certs in dev
+        }, (res) => {
+            const responseTime = Date.now() - startTime;
+            const server = res.headers["server"] || undefined;
+            const poweredBy = res.headers["x-powered-by"] || "";
+            // Detect framework from headers
+            let framework;
+            if (poweredBy.includes("Express"))
+                framework = "Express.js";
+            else if (poweredBy.includes("Next.js"))
+                framework = "Next.js";
+            else if (poweredBy.includes("Nuxt"))
+                framework = "Nuxt.js";
+            else if (poweredBy.includes("PHP"))
+                framework = "PHP";
+            else if (poweredBy.includes("ASP.NET"))
+                framework = "ASP.NET";
+            else if (res.headers["x-django-request-id"])
+                framework = "Django";
+            else if (res.headers["x-request-id"] && server?.includes("nginx"))
+                framework = "Rails/nginx";
+            // Consume body to free socket
+            res.resume();
+            resolve({
+                reachable: (res.statusCode || 0) >= 100 && (res.statusCode || 0) < 600,
+                statusCode: res.statusCode,
+                server: server,
+                framework,
+                responseTime,
+            });
+        });
+        req.on("error", (err) => {
+            reject(err);
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("Connection timed out"));
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Checks if a URL points to localhost.
+ */
+function isLocalhost(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.toLowerCase();
+        return (host === "localhost" ||
+            host === "127.0.0.1" ||
+            host === "0.0.0.0" ||
+            host === "::1" ||
+            host.endsWith(".localhost"));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/vulnerability-detector.d.ts

@@ -28,11 +28,15 @@ export interface ScanResult {
         testedForms: number;
         requestsMade: number;
     };
+    score: number;
 }
 export declare class VulnerabilityDetector {
     private vulnerabilities;
     private reportedHeaders;
     private reportedPaths;
+    private onVulnerabilityFound?;
+    setOnVulnerabilityFound(callback: (vuln: Vulnerability) => void): void;
+    addVulnerability(vuln: Vulnerability): void;
     detectXSS(url: string, param: string, payload: string, response: string): void;
     detectStoredXSS(url: string, payload: string, response: string): void;
     detectSQLi(url: string, param: string, errorResponse: string): void;
@@ -56,5 +60,10 @@ export declare class VulnerabilityDetector {
         low: number;
         info: number;
     };
+    /**
+     * Calculates a security score from 0-100
+     * 100 is perfect, 0 is very poor
+     */
+    calculateScore(): number;
     clear(): void;
 }

package/dist/core/vulnerability-detector.js

@@ -5,12 +5,22 @@ class VulnerabilityDetector {
     vulnerabilities = [];
     reportedHeaders = new Set();
     reportedPaths = new Set();
+    onVulnerabilityFound;
+    setOnVulnerabilityFound(callback) {
+        this.onVulnerabilityFound = callback;
+    }
+    addVulnerability(vuln) {
+        this.vulnerabilities.push(vuln);
+        if (this.onVulnerabilityFound) {
+            this.onVulnerabilityFound(vuln);
+        }
+    }
     detectXSS(url, param, payload, response) {
         if (response.includes(payload)) {
             const existing = this.vulnerabilities.find(v => v.type === "xss" && v.url === url && v.evidence?.includes(param));
             if (existing)
                 return;
-            this.vulnerabilities.push({
+            this.addVulnerability({
                 type: "xss",
                 severity: "high",
                 title: "Reflected Cross-Site Scripting (XSS)",
@@ -27,7 +37,7 @@ class VulnerabilityDetector {
             const existing = this.vulnerabilities.find(v => v.type === "xss" && v.url === url && v.title.includes("Stored"));
             if (existing)
                 return;
-            this.vulnerabilities.push({
+            this.addVulnerability({
                 type: "xss",
                 severity: "critical",
                 title: "Stored Cross-Site Scripting (XSS)",
@@ -65,7 +75,7 @@ class VulnerabilityDetector {
             return;
         for (const error of sqlErrors) {
             if (errorResponse.includes(error)) {
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "sqli",
                     severity: "critical",
                     title: "SQL Injection",
@@ -84,7 +94,7 @@ class VulnerabilityDetector {
             const existing = this.vulnerabilities.find(v => v.type === "sqli" && v.url === url && v.title.includes("Blind"));
             if (existing)
                 return;
-            this.vulnerabilities.push({
+            this.addVulnerability({
                 type: "sqli",
                 severity: "high",
                 title: "Blind SQL Injection",
@@ -105,7 +115,7 @@ class VulnerabilityDetector {
             const existing = this.vulnerabilities.find(v => v.type === "csrf" && v.url === url);
             if (existing)
                 return;
-            this.vulnerabilities.push({
+            this.addVulnerability({
                 type: "csrf",
                 severity: "medium",
                 title: "Missing CSRF Protection",
@@ -157,7 +167,7 @@ class VulnerabilityDetector {
         for (const [header, config] of Object.entries(requiredHeaders)) {
             if (!headers[header.toLowerCase()]) {
                 missingCount++;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "header",
                     severity: config.severity,
                     title: config.title,
@@ -190,7 +200,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "sensitive_data" && v.url === url && v.title.includes(pattern.name));
                 if (existing)
                     continue;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "sensitive_data",
                     severity: pattern.severity,
                     title: `Exposed ${pattern.name}`,
@@ -210,7 +220,7 @@ class VulnerabilityDetector {
             const existing = this.vulnerabilities.find(v => v.type === "idor" && v.url === url && v.evidence?.includes(paramName));
             if (existing)
                 return;
-            this.vulnerabilities.push({
+            this.addVulnerability({
                 type: "idor",
                 severity: "high",
                 title: "Insecure Direct Object Reference (IDOR)",
@@ -239,7 +249,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "lfi" && v.url === url);
                 if (existing)
                     return;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "lfi",
                     severity: "critical",
                     title: "Local File Inclusion (LFI)",
@@ -270,7 +280,7 @@ class VulnerabilityDetector {
                     if (this.reportedPaths.has(pathKey))
                         return;
                     this.reportedPaths.add(pathKey);
-                    this.vulnerabilities.push({
+                    this.addVulnerability({
                         type: "lfi",
                         severity: "high",
                         title: "Path Traversal",
@@ -305,7 +315,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "cmdi" && v.url === url);
                 if (existing)
                     return;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "cmdi",
                     severity: "critical",
                     title: "OS Command Injection",
@@ -336,7 +346,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "ssrf" && v.url === url);
                 if (existing)
                     return;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "ssrf",
                     severity: "high",
                     title: "Server-Side Request Forgery (SSRF)",
@@ -361,7 +371,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "redirect" && v.url === url);
                 if (existing)
                     return;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "redirect",
                     severity: "medium",
                     title: "Open Redirect",
@@ -378,7 +388,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "redirect" && v.url === url);
                 if (existing)
                     return;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "redirect",
                     severity: "medium",
                     title: "Open Redirect",
@@ -412,7 +422,7 @@ class VulnerabilityDetector {
                 const existing = this.vulnerabilities.find(v => v.type === "info" && v.url === url && v.title === pattern.name);
                 if (existing)
                     continue;
-                this.vulnerabilities.push({
+                this.addVulnerability({
                     type: "info",
                     severity: pattern.severity,
                     title: pattern.name,
@@ -442,6 +452,27 @@ class VulnerabilityDetector {
         }
         return summary;
     }
+    /**
+     * Calculates a security score from 0-100
+     * 100 is perfect, 0 is very poor
+     */
+    calculateScore() {
+        if (this.vulnerabilities.length === 0)
+            return 100;
+        const weights = {
+            critical: 25,
+            high: 10,
+            medium: 5,
+            low: 2,
+            info: 0,
+        };
+        let totalDeduction = 0;
+        for (const vuln of this.vulnerabilities) {
+            totalDeduction += weights[vuln.severity] || 0;
+        }
+        const score = Math.max(0, 100 - totalDeduction);
+        return Math.round(score);
+    }
     clear() {
         this.vulnerabilities = [];
         this.reportedHeaders.clear();

package/dist/core/vulnerability-detector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/vulnerability-detector.test.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vulnerability_detector_1 = require("./vulnerability-detector");
+describe("VulnerabilityDetector", () => {
+    let detector;
+    beforeEach(() => {
+        detector = new vulnerability_detector_1.VulnerabilityDetector();
+    });
+    // ─── detectXSS ─────────────────────────────────────────────────
+    describe("detectXSS", () => {
+        it("should detect reflected XSS when payload is in response", () => {
+            const payload = "<script>alert('XSS')</script>";
+            detector.detectXSS("https://example.com/search?q=test", "q", payload, `<html><body>${payload}</body></html>`);
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].type).toBe("xss");
+            expect(vulns[0].severity).toBe("high");
+            expect(vulns[0].cwe).toBe("CWE-79");
+        });
+        it("should not report XSS when payload is not reflected", () => {
+            detector.detectXSS("https://example.com/search", "q", "<script>alert(1)</script>", "<html><body>Safe content</body></html>");
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+        it("should report XSS for each detection call (no deduplication)", () => {
+            const payload = "<script>alert('XSS')</script>";
+            const response = `<html>${payload}</html>`;
+            detector.detectXSS("https://example.com", "q", payload, response);
+            detector.detectXSS("https://example.com", "q", payload, response);
+            // XSS detection does not deduplicate — each call adds a separate finding
+            expect(detector.getVulnerabilities()).toHaveLength(2);
+        });
+    });
+    // ─── detectSQLi ────────────────────────────────────────────────
+    describe("detectSQLi", () => {
+        it("should detect SQL injection from error messages", () => {
+            detector.detectSQLi("https://example.com/users?id=1", "id", "You have an error in your SQL syntax near '1'");
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].type).toBe("sqli");
+            expect(vulns[0].severity).toBe("critical");
+            expect(vulns[0].cwe).toBe("CWE-89");
+        });
+        it("should detect PostgreSQL errors", () => {
+            detector.detectSQLi("https://example.com/api", "q", "ERROR: PostgreSQL syntax error at position 42");
+            expect(detector.getVulnerabilities()).toHaveLength(1);
+        });
+        it("should not report when no SQL errors found", () => {
+            detector.detectSQLi("https://example.com", "q", "<html><body>Normal content</body></html>");
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+        it("should deduplicate SQLi findings for the same URL", () => {
+            detector.detectSQLi("https://example.com", "id", "SQL syntax error");
+            detector.detectSQLi("https://example.com", "name", "ORA-00933 error");
+            expect(detector.getVulnerabilities()).toHaveLength(1);
+        });
+    });
+    // ─── detectBlindSQLi ───────────────────────────────────────────
+    describe("detectBlindSQLi", () => {
+        it("should detect time-based blind SQLi when delay exceeds threshold", () => {
+            detector.detectBlindSQLi("https://example.com", "id", 500, 4000);
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].type).toBe("sqli");
+            expect(vulns[0].title).toContain("Blind");
+        });
+        it("should not report when delay is within threshold", () => {
+            detector.detectBlindSQLi("https://example.com", "id", 500, 2000);
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+    });
+    // ─── detectCSRF ────────────────────────────────────────────────
+    describe("detectCSRF", () => {
+        it("should detect missing CSRF token", () => {
+            detector.detectCSRF("https://example.com/form", '<form method="POST"><input name="email" /></form>');
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].type).toBe("csrf");
+            expect(vulns[0].severity).toBe("medium");
+        });
+        it("should not report when CSRF token is present", () => {
+            detector.detectCSRF("https://example.com/form", '<form method="POST"><input name="csrf_token" /><input name="email" /></form>');
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+        it("should recognize _token as a valid CSRF token", () => {
+            detector.detectCSRF("https://example.com", '<form><input name="_token" value="abc123" /></form>');
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+    });
+    // ─── analyzeSecurityHeaders ────────────────────────────────────
+    describe("analyzeSecurityHeaders", () => {
+        it("should detect missing security headers", () => {
+            detector.analyzeSecurityHeaders("https://example.com", {});
+            const vulns = detector.getVulnerabilities();
+            expect(vulns.length).toBeGreaterThanOrEqual(3);
+            expect(vulns.every((v) => v.type === "header")).toBe(true);
+        });
+        it("should not report when all headers are present", () => {
+            detector.analyzeSecurityHeaders("https://example.com", {
+                "content-security-policy": "default-src 'self'",
+                "x-frame-options": "DENY",
+                "strict-transport-security": "max-age=31536000",
+                "x-content-type-options": "nosniff",
+                "referrer-policy": "strict-origin-when-cross-origin",
+                "permissions-policy": "camera=()",
+            });
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+        it("should only check headers once per host", () => {
+            detector.analyzeSecurityHeaders("https://example.com/page1", {});
+            const count1 = detector.getVulnerabilities().length;
+            detector.analyzeSecurityHeaders("https://example.com/page2", {});
+            const count2 = detector.getVulnerabilities().length;
+            expect(count2).toBe(count1);
+        });
+    });
+    // ─── detectSensitiveData ──────────────────────────────────────
+    describe("detectSensitiveData", () => {
+        it("should detect exposed AWS access keys", () => {
+            detector.detectSensitiveData("https://example.com", 'config = { key: "AKIAIOSFODNN7EXAMPLE" }');
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].type).toBe("sensitive_data");
+            expect(vulns[0].severity).toBe("critical");
+        });
+        it("should detect exposed JWT tokens", () => {
+            detector.detectSensitiveData("https://example.com", 'let token = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"');
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].title).toContain("JWT");
+        });
+        it("should detect private keys", () => {
+            detector.detectSensitiveData("https://example.com", "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAK...");
+            const vulns = detector.getVulnerabilities();
+            expect(vulns).toHaveLength(1);
+            expect(vulns[0].severity).toBe("critical");
+        });
+        it("should not report on clean responses", () => {
+            detector.detectSensitiveData("https://example.com", "<html><body>Hello World</body></html>");
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+        });
+    });
+    // ─── getSummary ────────────────────────────────────────────────
+    describe("getSummary", () => {
+        it("should return correct severity counts", () => {
+            // Add mixed severity vulns
+            detector.addVulnerability({
+                type: "xss", severity: "high", title: "XSS",
+                description: "test", url: "https://example.com",
+            });
+            detector.addVulnerability({
+                type: "sqli", severity: "critical", title: "SQLi",
+                description: "test", url: "https://example.com",
+            });
+            detector.addVulnerability({
+                type: "header", severity: "low", title: "Header",
+                description: "test", url: "https://example.com",
+            });
+            detector.addVulnerability({
+                type: "info", severity: "info", title: "Info",
+                description: "test", url: "https://example.com",
+            });
+            const summary = detector.getSummary();
+            expect(summary.total).toBe(4);
+            expect(summary.critical).toBe(1);
+            expect(summary.high).toBe(1);
+            expect(summary.low).toBe(1);
+            expect(summary.info).toBe(1);
+            expect(summary.medium).toBe(0);
+        });
+        it("should return zeros when no vulnerabilities", () => {
+            const summary = detector.getSummary();
+            expect(summary.total).toBe(0);
+            expect(summary.critical).toBe(0);
+        });
+    });
+    // ─── clear ─────────────────────────────────────────────────────
+    describe("clear", () => {
+        it("should remove all vulnerabilities and reset state", () => {
+            detector.addVulnerability({
+                type: "xss", severity: "high", title: "XSS",
+                description: "test", url: "https://example.com",
+            });
+            expect(detector.getVulnerabilities()).toHaveLength(1);
+            detector.clear();
+            expect(detector.getVulnerabilities()).toHaveLength(0);
+            expect(detector.getSummary().total).toBe(0);
+        });
+        it("should allow re-detecting after clear", () => {
+            detector.analyzeSecurityHeaders("https://example.com", {});
+            const count1 = detector.getVulnerabilities().length;
+            detector.clear();
+            detector.analyzeSecurityHeaders("https://example.com", {});
+            const count2 = detector.getVulnerabilities().length;
+            expect(count2).toBe(count1);
+        });
+    });
+    // ─── Callback ──────────────────────────────────────────────────
+    describe("onVulnerabilityFound callback", () => {
+        it("should call callback when vulnerability is added", () => {
+            const callback = jest.fn();
+            detector.setOnVulnerabilityFound(callback);
+            detector.addVulnerability({
+                type: "xss", severity: "high", title: "XSS",
+                description: "test", url: "https://example.com",
+            });
+            expect(callback).toHaveBeenCalledTimes(1);
+            expect(callback).toHaveBeenCalledWith(expect.objectContaining({ type: "xss", severity: "high" }));
+        });
+    });
+});

package/dist/index.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const cli_1 = require("./cli");
+const errors_1 = require("./core/errors");
+// Ensure uncaught exceptions and unhandled rejections produce useful output
+(0, errors_1.setupGlobalErrorHandlers)();
 (0, cli_1.run)().catch((err) => {
     console.error("Fatal error:", err);
     process.exit(1);

package/dist/plugins/PluginManager.d.ts

@@ -0,0 +1,27 @@
+import { VulnerabilityPlugin, PluginContext, FormData } from "./types";
+import { Vulnerability } from "../core/vulnerability-detector";
+export interface PluginExecutionResult {
+    plugin: string;
+    vulnerabilities: Vulnerability[];
+    errors: Array<{
+        url: string;
+        error: string;
+    }>;
+    duration: number;
+}
+export declare class PluginManager {
+    private plugins;
+    private enabledPlugins;
+    register(plugin: VulnerabilityPlugin): void;
+    unregister(pluginName: string): boolean;
+    enable(pluginName: string): boolean;
+    disable(pluginName: string): boolean;
+    getPlugin(name: string): VulnerabilityPlugin | undefined;
+    getAllPlugins(): VulnerabilityPlugin[];
+    getEnabledPlugins(): VulnerabilityPlugin[];
+    testParameter(context: PluginContext, param: string, value: string): Promise<PluginExecutionResult[]>;
+    testFormInput(context: PluginContext, formData: FormData): Promise<PluginExecutionResult[]>;
+    analyzeContent(context: PluginContext, content: string): Promise<PluginExecutionResult[]>;
+    analyzeHeaders(context: PluginContext, headers: Record<string, string>): Promise<PluginExecutionResult[]>;
+}
+export declare const pluginManager: PluginManager;