kramscan 0.1.0 → 0.2.0

package/dist/agent/skills/web-scan.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Web Scan Skill
+ * Comprehensive web application security scanner as an AI-callable skill
+ * Tests for XSS, SQL injection, CSRF, and security header vulnerabilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebScanSkill = void 0;
+const scanner_1 = require("../../core/scanner");
+const logger_1 = require("../../utils/logger");
+class WebScanSkill {
+    id = "web_scan";
+    name = "Web Scan";
+    description = "Performs a comprehensive security scan of a web application. Tests for XSS, SQL injection, CSRF, and security header misconfigurations.";
+    tags = ["scanning", "web", "security", "vulnerability"];
+    requiresConfirmation = true;
+    riskLevel = "medium";
+    estimatedDuration = 60; // seconds
+    toolDefinition = {
+        name: "web_scan",
+        description: "Scan a web application for security vulnerabilities including XSS, SQL injection, CSRF, and security headers",
+        parameters: [
+            {
+                name: "targetUrl",
+                type: "string",
+                description: "The URL of the web application to scan (e.g., https://example.com)",
+                required: true,
+            },
+            {
+                name: "depth",
+                type: "number",
+                description: "How many levels deep to crawl (1-5). Higher values scan more pages but take longer.",
+                required: false,
+                default: 2,
+            },
+            {
+                name: "timeout",
+                type: "number",
+                description: "Request timeout in milliseconds (10000-120000)",
+                required: false,
+                default: 30000,
+            },
+            {
+                name: "headless",
+                type: "boolean",
+                description: "Run browser in headless mode (no visible window)",
+                required: false,
+                default: true,
+            },
+            {
+                name: "maxPages",
+                type: "number",
+                description: "Maximum pages to crawl before stopping",
+                required: false,
+                default: 30,
+            },
+            {
+                name: "maxLinksPerPage",
+                type: "number",
+                description: "Maximum links to follow per page",
+                required: false,
+                default: 50,
+            },
+            {
+                name: "include",
+                type: "array",
+                description: "Only include URLs matching these regex patterns (strings)",
+                required: false,
+            },
+            {
+                name: "exclude",
+                type: "array",
+                description: "Exclude URLs matching these regex patterns (strings)",
+                required: false,
+            },
+        ],
+    };
+    validateParameters(params) {
+        const errors = [];
+        // Validate targetUrl
+        if (!params.targetUrl) {
+            errors.push("targetUrl is required");
+        }
+        else if (typeof params.targetUrl !== "string") {
+            errors.push("targetUrl must be a string");
+        }
+        else {
+            try {
+                const url = new URL(params.targetUrl);
+                if (!["http:", "https:"].includes(url.protocol)) {
+                    errors.push("targetUrl must use HTTP or HTTPS protocol");
+                }
+            }
+            catch {
+                errors.push("targetUrl must be a valid URL");
+            }
+        }
+        // Validate depth
+        if (params.depth !== undefined) {
+            const depth = Number(params.depth);
+            if (isNaN(depth) || depth < 1 || depth > 5) {
+                errors.push("depth must be a number between 1 and 5");
+            }
+        }
+        // Validate timeout
+        if (params.timeout !== undefined) {
+            const timeout = Number(params.timeout);
+            if (isNaN(timeout) || timeout < 10000 || timeout > 120000) {
+                errors.push("timeout must be a number between 10000 and 120000");
+            }
+        }
+        if (params.maxPages !== undefined) {
+            const maxPages = Number(params.maxPages);
+            if (isNaN(maxPages) || maxPages < 1 || maxPages > 10000) {
+                errors.push("maxPages must be a positive number");
+            }
+        }
+        if (params.maxLinksPerPage !== undefined) {
+            const maxLinks = Number(params.maxLinksPerPage);
+            if (isNaN(maxLinks) || maxLinks < 1 || maxLinks > 10000) {
+                errors.push("maxLinksPerPage must be a positive number");
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    async execute(params, context) {
+        const targetUrl = params.targetUrl;
+        const depth = params.depth ?? 2;
+        const timeout = params.timeout ?? 30000;
+        const headless = params.headless ?? true;
+        const maxPages = params.maxPages ?? 30;
+        const maxLinksPerPage = params.maxLinksPerPage ?? 50;
+        const include = params.include;
+        const exclude = params.exclude;
+        logger_1.logger.info(`Starting web scan of ${targetUrl}`);
+        const scanner = new scanner_1.Scanner();
+        try {
+            const scanResult = await scanner.scan(targetUrl, {
+                depth,
+                timeout,
+                headless,
+                maxPages,
+                maxLinksPerPage,
+                include,
+                exclude,
+            });
+            // Convert vulnerabilities to findings
+            const findings = scanResult.vulnerabilities.map((vuln) => ({
+                id: `${vuln.type}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                skillId: this.id,
+                title: vuln.title,
+                severity: vuln.severity,
+                description: vuln.description,
+                evidence: vuln.evidence,
+                recommendation: vuln.remediation,
+                references: [],
+                metadata: {
+                    url: vuln.url,
+                    type: vuln.type,
+                    cwe: vuln.cwe,
+                },
+            }));
+            logger_1.logger.success(`Scan complete. Found ${findings.length} vulnerabilities.`);
+            return {
+                skillId: this.id,
+                findings,
+                metadata: {
+                    target: scanResult.target,
+                    timestamp: scanResult.timestamp,
+                    duration: scanResult.duration,
+                    summary: scanResult.summary,
+                    crawledUrls: scanResult.metadata.crawledUrls,
+                    testedForms: scanResult.metadata.testedForms,
+                    requestsMade: scanResult.metadata.requestsMade,
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger_1.logger.error(`Scan failed: ${errorMessage}`);
+            return {
+                skillId: this.id,
+                findings: [],
+                metadata: {
+                    error: errorMessage,
+                    target: targetUrl,
+                    timestamp: new Date().toISOString(),
+                },
+            };
+        }
+        finally {
+            await scanner.close();
+        }
+    }
+    async run() {
+        // This method is required by Skill interface but not used in agent context
+        throw new Error("Use execute() method with AgentContext for web scan skill");
+    }
+}
+exports.WebScanSkill = WebScanSkill;

package/dist/agent/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Core types for the KramScan AI Agent system
+ * Defines interfaces for skills, tool calling, conversation context, and agent responses
+ */
+export type Severity = "info" | "low" | "medium" | "high" | "critical";
+export interface Finding {
+    id: string;
+    skillId: string;
+    title: string;
+    severity: Severity;
+    description: string;
+    evidence?: string;
+    recommendation?: string;
+    references?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface SkillMetadata {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    category?: string;
+}
+export interface SkillResult {
+    skillId: string;
+    findings: Finding[];
+    metadata?: Record<string, unknown>;
+}
+export interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    run(context: SkillContext): Promise<SkillResult>;
+}
+export interface SkillContext {
+    targetUrl: string;
+    timeoutSeconds: number;
+    logger: {
+        info(message: string): void;
+        warn(message: string): void;
+        error(message: string): void;
+    };
+    http: {
+        get: <T = unknown>(url: string) => Promise<{
+            data: T;
+            headers: Record<string, string>;
+        }>;
+    };
+}
+export interface ToolParameter {
+    name: string;
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description: string;
+    required: boolean;
+    default?: unknown;
+    enum?: string[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolCallResult {
+    toolCallId: string;
+    success: boolean;
+    result?: SkillResult | unknown;
+    error?: string;
+    executionTime: number;
+}
+export interface ConversationMessage {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    timestamp: Date;
+    toolCalls?: ToolCall[];
+    toolCallResults?: ToolCallResult[];
+}
+export interface AgentContext {
+    sessionId: string;
+    userId: string;
+    startTime: Date;
+    currentTarget?: string;
+    lastScanResults?: SkillResult;
+    workingDirectory: string;
+    environment: {
+        nodeVersion: string;
+        platform: string;
+    };
+}
+export interface AgentResponse {
+    message: string;
+    toolCalls?: ToolCall[];
+    toolCallResults?: ToolCallResult[];
+    requiresConfirmation: boolean;
+    pendingAction?: {
+        toolName: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        risk: "low" | "medium" | "high";
+    };
+}
+export interface AgentSkill extends Skill {
+    /** Tool definition for AI function calling */
+    toolDefinition: ToolDefinition;
+    /** Whether this skill requires user confirmation before execution */
+    requiresConfirmation: boolean;
+    /** Risk level of the skill */
+    riskLevel: "low" | "medium" | "high";
+    /** Estimated execution time in seconds */
+    estimatedDuration: number;
+    /** Validate parameters before execution */
+    validateParameters(params: Record<string, unknown>): {
+        valid: boolean;
+        errors: string[];
+    };
+    /** Execute the skill with given parameters */
+    execute(params: Record<string, unknown>, context: AgentContext): Promise<SkillResult>;
+}
+export interface ConfirmationPrompt {
+    action: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    risk: "low" | "medium" | "high";
+    estimatedTime: string;
+}
+export interface AgentConfig {
+    maxConversationHistory: number;
+    enableConfirmation: boolean;
+    autoConfirmLowRisk: boolean;
+    maxTokensPerRequest: number;
+    temperature: number;
+    model: string;
+    systemPrompt: string;
+}
+export declare const DEFAULT_AGENT_CONFIG: AgentConfig;

package/dist/agent/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Core types for the KramScan AI Agent system
+ * Defines interfaces for skills, tool calling, conversation context, and agent responses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENT_CONFIG = void 0;
+exports.DEFAULT_AGENT_CONFIG = {
+    maxConversationHistory: 20,
+    enableConfirmation: true,
+    autoConfirmLowRisk: false,
+    maxTokensPerRequest: 4096,
+    temperature: 0.3,
+    model: "claude-3-opus-4-6",
+    systemPrompt: ``, // Will be loaded from prompts/system.ts
+};

package/dist/cli.d.ts

@@ -1 +1,4 @@
+export declare function isVerbose(): boolean;
+export declare function isDebug(): boolean;
+export declare function debugLog(...args: unknown[]): void;
 export declare function run(): Promise<void>;