kramscan 0.1.0 → 0.2.0

package/dist/core/errors.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Custom Error Types for KramScan
+ * Provides structured error handling with error codes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportError = exports.AiError = exports.NetworkError = exports.ConfigError = exports.PluginError = exports.ScannerError = exports.KramScanError = exports.ErrorCode = void 0;
+exports.isRetryable = isRetryable;
+exports.shouldRetry = shouldRetry;
+exports.getRetryDelay = getRetryDelay;
+exports.setupGlobalErrorHandlers = setupGlobalErrorHandlers;
+var ErrorCode;
+(function (ErrorCode) {
+    // Scanner errors (SCN-xxx)
+    ErrorCode["SCN_INIT_FAILED"] = "SCN_INIT_FAILED";
+    ErrorCode["SCN_CRAWL_FAILED"] = "SCN_CRAWL_FAILED";
+    ErrorCode["SCN_TIMEOUT"] = "SCN_TIMEOUT";
+    ErrorCode["SCN_INVALID_URL"] = "SCN_INVALID_URL";
+    ErrorCode["SCN_SCOPE_VIOLATION"] = "SCN_SCOPE_VIOLATION";
+    ErrorCode["SCN_BROWSER_ERROR"] = "SCN_BROWSER_ERROR";
+    // Plugin errors (PLG-xxx)
+    ErrorCode["PLG_INIT_FAILED"] = "PLG_INIT_FAILED";
+    ErrorCode["PLG_EXECUTION_FAILED"] = "PLG_EXECUTION_FAILED";
+    ErrorCode["PLG_NOT_FOUND"] = "PLG_NOT_FOUND";
+    ErrorCode["PLG_DISABLED"] = "PLG_DISABLED";
+    ErrorCode["PLG_TIMEOUT"] = "PLG_TIMEOUT";
+    // Config errors (CFG-xxx)
+    ErrorCode["CFG_INVALID"] = "CFG_INVALID";
+    ErrorCode["CFG_NOT_FOUND"] = "CFG_NOT_FOUND";
+    ErrorCode["CFG_WRITE_FAILED"] = "CFG_WRITE_FAILED";
+    // Network errors (NET-xxx)
+    ErrorCode["NET_REQUEST_FAILED"] = "NET_REQUEST_FAILED";
+    ErrorCode["NET_RATE_LIMITED"] = "NET_RATE_LIMITED";
+    ErrorCode["NET_SSL_ERROR"] = "NET_SSL_ERROR";
+    // AI errors (AI-xxx)
+    ErrorCode["AI_INIT_FAILED"] = "AI_INIT_FAILED";
+    ErrorCode["AI_REQUEST_FAILED"] = "AI_REQUEST_FAILED";
+    ErrorCode["AI_QUOTA_EXCEEDED"] = "AI_QUOTA_EXCEEDED";
+    // Report errors (RPT-xxx)
+    ErrorCode["RPT_GENERATION_FAILED"] = "RPT_GENERATION_FAILED";
+    ErrorCode["RPT_INVALID_FORMAT"] = "RPT_INVALID_FORMAT";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+class KramScanError extends Error {
+    code;
+    statusCode;
+    retryable;
+    context;
+    timestamp;
+    constructor(message, options) {
+        super(message);
+        this.name = "KramScanError";
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.retryable = options.retryable ?? false;
+        this.context = options.context;
+        this.timestamp = new Date().toISOString();
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, KramScanError);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            statusCode: this.statusCode,
+            retryable: this.retryable,
+            context: this.context,
+            timestamp: this.timestamp,
+            stack: this.stack,
+        };
+    }
+}
+exports.KramScanError = KramScanError;
+// Convenience error classes for common scenarios
+class ScannerError extends KramScanError {
+    constructor(message, code = ErrorCode.SCN_CRAWL_FAILED, context) {
+        super(message, { code, retryable: true, context });
+        this.name = "ScannerError";
+    }
+}
+exports.ScannerError = ScannerError;
+class PluginError extends KramScanError {
+    constructor(message, code = ErrorCode.PLG_EXECUTION_FAILED, context) {
+        super(message, { code, retryable: false, context });
+        this.name = "PluginError";
+    }
+}
+exports.PluginError = PluginError;
+class ConfigError extends KramScanError {
+    constructor(message, code = ErrorCode.CFG_INVALID, context) {
+        super(message, { code, retryable: false, context });
+        this.name = "ConfigError";
+    }
+}
+exports.ConfigError = ConfigError;
+class NetworkError extends KramScanError {
+    constructor(message, code = ErrorCode.NET_REQUEST_FAILED, context) {
+        super(message, { code, retryable: true, context });
+        this.name = "NetworkError";
+    }
+}
+exports.NetworkError = NetworkError;
+class AiError extends KramScanError {
+    constructor(message, code = ErrorCode.AI_REQUEST_FAILED, context) {
+        super(message, { code, retryable: true, context });
+        this.name = "AiError";
+    }
+}
+exports.AiError = AiError;
+class ReportError extends KramScanError {
+    constructor(message, code = ErrorCode.RPT_GENERATION_FAILED, context) {
+        super(message, { code, retryable: false, context });
+        this.name = "ReportError";
+    }
+}
+exports.ReportError = ReportError;
+const defaultErrorHandlerConfig = {
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 10000,
+    retryableCodes: [
+        ErrorCode.SCN_CRAWL_FAILED,
+        ErrorCode.SCN_TIMEOUT,
+        ErrorCode.SCN_BROWSER_ERROR,
+        ErrorCode.NET_REQUEST_FAILED,
+        ErrorCode.PLG_EXECUTION_FAILED,
+        ErrorCode.AI_REQUEST_FAILED,
+    ],
+};
+function isRetryable(error, config = defaultErrorHandlerConfig) {
+    if (!error.retryable)
+        return false;
+    return config.retryableCodes.includes(error.code);
+}
+function shouldRetry(error, attempt, config = defaultErrorHandlerConfig) {
+    return attempt < config.maxRetries && isRetryable(error, config);
+}
+function getRetryDelay(error, attempt, config = defaultErrorHandlerConfig) {
+    const delay = Math.min(config.baseDelay * Math.pow(2, attempt), config.maxDelay);
+    // Add jitter to prevent thundering herd
+    const jitter = Math.random() * 0.3 * delay;
+    return Math.floor(delay + jitter);
+}
+// Global error handler for uncaught errors
+function setupGlobalErrorHandlers() {
+    process.on("uncaughtException", (error) => {
+        console.error("[FATAL] Uncaught Exception:");
+        console.error(error.message);
+        if (error.stack) {
+            console.error(error.stack);
+        }
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason, promise) => {
+        console.error("[FATAL] Unhandled Promise Rejection:");
+        console.error("Reason:", reason);
+        console.error("Promise:", promise);
+        process.exit(1);
+    });
+}

package/dist/core/scan-index.d.ts

@@ -0,0 +1,19 @@
+export interface ScanIndexEntry {
+    id: string;
+    target: string;
+    hostname: string;
+    timestamp: string;
+    jsonPath: string;
+    pdfPath?: string;
+    summary: {
+        total: number;
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        info: number;
+    };
+}
+export declare function addScanToIndex(entry: Omit<ScanIndexEntry, "id">): Promise<ScanIndexEntry>;
+export declare function listScans(limit?: number): Promise<ScanIndexEntry[]>;
+export declare function getLatestScan(): Promise<ScanIndexEntry | null>;

package/dist/core/scan-index.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addScanToIndex = addScanToIndex;
+exports.listScans = listScans;
+exports.getLatestScan = getLatestScan;
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function getIndexPath() {
+    return path_1.default.join(os_1.default.homedir(), ".kramscan", "scans", "index.json");
+}
+async function readIndex() {
+    const indexPath = getIndexPath();
+    try {
+        const raw = await promises_1.default.readFile(indexPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+async function writeIndex(entries) {
+    const indexPath = getIndexPath();
+    await promises_1.default.mkdir(path_1.default.dirname(indexPath), { recursive: true });
+    await promises_1.default.writeFile(indexPath, JSON.stringify(entries, null, 2), "utf-8");
+}
+async function addScanToIndex(entry) {
+    const hostname = entry.hostname || "unknown";
+    const id = `${new Date(entry.timestamp).getTime()}-${hostname}-${Math.random().toString(36).slice(2, 8)}`;
+    const full = { ...entry, id };
+    const existing = await readIndex();
+    const merged = [full, ...existing]
+        .filter((e, idx, arr) => arr.findIndex((x) => x.jsonPath === e.jsonPath) === idx)
+        .slice(0, 500);
+    await writeIndex(merged);
+    return full;
+}
+async function listScans(limit = 20) {
+    const entries = await readIndex();
+    return entries.slice(0, Math.max(1, limit));
+}
+async function getLatestScan() {
+    const entries = await readIndex();
+    return entries.length > 0 ? entries[0] : null;
+}

package/dist/core/scan-storage.d.ts

@@ -0,0 +1,11 @@
+export interface ResolvedScanFile {
+    filepath: string;
+    filename: string;
+    isLatest: boolean;
+}
+export declare function getKramScanHome(): string;
+export declare function getScansDirectory(): string;
+export declare function getReportsDirectory(): string;
+export declare function ensureScansDirectory(): Promise<string>;
+export declare function ensureReportsDirectory(): Promise<string>;
+export declare function resolveScanFile(scanFile?: string): Promise<ResolvedScanFile>;

package/dist/core/scan-storage.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKramScanHome = getKramScanHome;
+exports.getScansDirectory = getScansDirectory;
+exports.getReportsDirectory = getReportsDirectory;
+exports.ensureScansDirectory = ensureScansDirectory;
+exports.ensureReportsDirectory = ensureReportsDirectory;
+exports.resolveScanFile = resolveScanFile;
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function getKramScanHome() {
+    return path_1.default.join(os_1.default.homedir(), ".kramscan");
+}
+function getScansDirectory() {
+    return path_1.default.join(getKramScanHome(), "scans");
+}
+function getReportsDirectory() {
+    return path_1.default.join(getKramScanHome(), "reports");
+}
+async function ensureScansDirectory() {
+    const scanDir = getScansDirectory();
+    await promises_1.default.mkdir(scanDir, { recursive: true });
+    return scanDir;
+}
+async function ensureReportsDirectory() {
+    const reportsDir = getReportsDirectory();
+    await promises_1.default.mkdir(reportsDir, { recursive: true });
+    return reportsDir;
+}
+async function resolveScanFile(scanFile) {
+    if (scanFile) {
+        const filepath = path_1.default.isAbsolute(scanFile)
+            ? scanFile
+            : path_1.default.join(process.cwd(), scanFile);
+        return {
+            filepath,
+            filename: path_1.default.basename(filepath),
+            isLatest: false,
+        };
+    }
+    const scanDir = await ensureScansDirectory();
+    const entries = await promises_1.default.readdir(scanDir, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => entry.name);
+    if (files.length === 0) {
+        throw new Error("No scan results found. Run 'kramscan scan <url>' first.");
+    }
+    const filesWithStats = await Promise.all(files.map(async (filename) => {
+        const filepath = path_1.default.join(scanDir, filename);
+        const stats = await promises_1.default.stat(filepath);
+        return {
+            filename,
+            filepath,
+            mtimeMs: stats.mtimeMs,
+        };
+    }));
+    filesWithStats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const latest = filesWithStats[0];
+    return {
+        filepath: latest.filepath,
+        filename: latest.filename,
+        isLatest: true,
+    };
+}

package/dist/core/scanner.d.ts

@@ -1,21 +1,118 @@
-import { ScanResult } from "./vulnerability-detector";
+import { EventEmitter } from "events";
+import { ScanResult, Vulnerability } from "./vulnerability-detector";
+export interface ScanEventMap {
+    "scan:start": {
+        target: string;
+        options: ScanOptions;
+    };
+    "scan:complete": {
+        result: ScanResult;
+    };
+    "scan:error": {
+        error: Error;
+    };
+    "crawl:start": {
+        url: string;
+        depth: number;
+    };
+    "crawl:page": {
+        url: string;
+        crawledCount: number;
+        maxPages: number;
+    };
+    "crawl:complete": {
+        url: string;
+    };
+    "crawl:error": {
+        url: string;
+        error: Error;
+    };
+    "form:test": {
+        url: string;
+        formCount: number;
+    };
+    "vuln:found": {
+        vulnerability: Vulnerability;
+    };
+    "plugin:execute": {
+        plugin: string;
+        url: string;
+        duration: number;
+    };
+    "progress": {
+        stage: string;
+        current: number;
+        total: number;
+        message?: string;
+    };
+}
 export interface ScanOptions {
     depth?: number;
     timeout?: number;
     headless?: boolean;
+    maxPages?: number;
+    maxLinksPerPage?: number;
+    include?: string[];
+    exclude?: string[];
+    strictScope?: boolean;
+    profile?: string;
+    useAiPayloads?: boolean;
+}
+export interface ScanError {
+    url: string;
+    error: string;
+    plugin?: string;
 }
-export declare class Scanner {
+export declare class Scanner extends EventEmitter {
     private browser;
     private detector;
     private visitedUrls;
     private crawledUrls;
     private testedForms;
     private requestsMade;
-    constructor();
+    private headersChecked;
+    private rateLimiter;
+    private retryConfig;
+    private maxConcurrency;
+    private strictScope;
+    private baseOrigin;
+    private maxPages;
+    private maxLinksPerPage;
+    private includePatterns;
+    private excludePatterns;
+    private userAgent;
+    private scanErrors;
+    private pluginErrors;
+    private usePlugins;
+    private useAiPayloads;
+    private payloadGenerator;
+    constructor(usePlugins?: boolean);
+    private registerDefaultPlugins;
+    emit<K extends keyof ScanEventMap>(event: K, data: ScanEventMap[K]): boolean;
+    on<K extends keyof ScanEventMap>(event: K, listener: (data: ScanEventMap[K]) => void): this;
+    once<K extends keyof ScanEventMap>(event: K, listener: (data: ScanEventMap[K]) => void): this;
+    getScanErrors(): ScanError[];
+    getPluginErrors(): Map<string, Array<{
+        url: string;
+        error: string;
+    }>>;
+    private initializeScanSettings;
+    private resetScanState;
     initialize(options?: ScanOptions): Promise<void>;
     scan(targetUrl: string, options?: ScanOptions): Promise<ScanResult>;
+    private applyRateLimit;
+    private withRetry;
+    private createInstrumentedPage;
+    private runInIsolatedPage;
     private crawl;
-    private testForms;
+    private runPlugins;
+    private processPluginResults;
+    private testUrlParametersWithPlugins;
+    private testFormsWithPlugins;
+    private runLegacyDetection;
+    private testFormsLegacy;
+    private testUrlParametersLegacy;
+    private runWithConcurrency;
     private testXSS;
     private testSQLi;
     private buildTestUrl;