kramscan 0.1.0 → 0.2.0

package/dist/agent/orchestrator.js

@@ -0,0 +1,370 @@
+"use strict";
+/**
+ * Agent Orchestrator
+ * Coordinates AI conversations, tool calling, skill execution, and user interactions
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentOrchestrator = void 0;
+const context_1 = require("./context");
+const confirmation_1 = require("./confirmation");
+const system_1 = require("./prompts/system");
+const types_1 = require("./types");
+const ai_client_1 = require("../core/ai-client");
+const logger_1 = require("../utils/logger");
+const chalk_1 = __importDefault(require("chalk"));
+class AgentOrchestrator {
+    context;
+    skillRegistry;
+    confirmationHandler;
+    config;
+    aiClient = null;
+    isRunning = false;
+    constructor(skillRegistry, config = {}) {
+        this.skillRegistry = skillRegistry;
+        this.config = { ...types_1.DEFAULT_AGENT_CONFIG, ...config };
+        this.context = new context_1.ConversationContext(this.config);
+        this.confirmationHandler = new confirmation_1.ConfirmationHandler();
+    }
+    setReadlineInterface(rl) {
+        this.confirmationHandler.setInterface(rl);
+    }
+    /**
+     * Initialize the orchestrator and AI client
+     */
+    async initialize() {
+        try {
+            this.aiClient = await (0, ai_client_1.createAIClient)();
+            logger_1.logger.success("AI client initialized successfully");
+        }
+        catch (error) {
+            logger_1.logger.error("Failed to initialize AI client. Run 'kramscan onboard' first.");
+            throw error;
+        }
+        // Add system message
+        this.context.addMessage("system", (0, system_1.getSystemPrompt)());
+        // Try to load previous conversation
+        await this.context.load();
+    }
+    /**
+     * Process a user message and generate a response
+     */
+    async processUserMessage(userInput) {
+        // Add user message to context
+        this.context.addMessage("user", userInput);
+        // Get AI response
+        const aiResponse = await this.getAIResponse();
+        // Check for tool calls in the response
+        const toolCalls = this.parseToolCalls(aiResponse);
+        if (toolCalls.length > 0) {
+            // Handle tool execution with confirmation
+            return this.handleToolExecution(toolCalls, aiResponse);
+        }
+        // No tool calls - just return the message
+        this.context.addMessage("assistant", aiResponse);
+        return {
+            message: aiResponse,
+            requiresConfirmation: false,
+        };
+    }
+    /**
+     * Execute a specific tool/skill directly
+     */
+    async executeTool(toolName, parameters, skipConfirmation = false) {
+        const toolCall = {
+            id: `manual-${Date.now()}`,
+            name: toolName,
+            arguments: parameters,
+        };
+        if (!skipConfirmation && this.skillRegistry.requiresConfirmation(toolName)) {
+            const confirmation = this.skillRegistry.getConfirmationPrompt(toolCall);
+            if (confirmation) {
+                const result = await this.confirmationHandler.prompt(confirmation);
+                if (result.showDetails) {
+                    this.confirmationHandler.showDetails(confirmation);
+                    return {
+                        message: "Please confirm to proceed after reviewing the details.",
+                        requiresConfirmation: true,
+                        pendingAction: {
+                            toolName,
+                            description: confirmation.description,
+                            parameters,
+                            risk: confirmation.risk,
+                        },
+                    };
+                }
+                if (!result.confirmed || result.cancelled) {
+                    return {
+                        message: result.cancelled
+                            ? "Action cancelled."
+                            : "Action not confirmed. You can ask me to perform this action again when you're ready.",
+                        requiresConfirmation: false,
+                    };
+                }
+            }
+        }
+        // Execute the tool
+        const result = await this.skillRegistry.execute(toolCall, this.context.getContext());
+        // Format response
+        const responseMessage = this.formatToolResult(result);
+        this.context.addMessage("assistant", responseMessage, [toolCall], [result]);
+        // Store scan results if applicable
+        if (toolName === "web_scan" && result.success && result.result) {
+            this.context.setLastScanResults(result.result);
+            const target = parameters.targetUrl;
+            this.context.setCurrentTarget(target);
+        }
+        return {
+            message: responseMessage,
+            toolCalls: [toolCall],
+            toolCallResults: [result],
+            requiresConfirmation: false,
+        };
+    }
+    /**
+     * Get conversation summary
+     */
+    getConversationSummary() {
+        return this.context.getSummary();
+    }
+    /**
+     * Clear conversation history
+     */
+    clearConversation() {
+        this.context.clear();
+        this.context.addMessage("system", (0, system_1.getSystemPrompt)());
+        logger_1.logger.info("Conversation history cleared");
+    }
+    /**
+     * Save conversation state
+     */
+    async saveState() {
+        await this.context.save();
+    }
+    /**
+     * Get available skills list
+     */
+    getAvailableSkills() {
+        return this.skillRegistry.listSkills();
+    }
+    /**
+     * Shutdown the orchestrator
+     */
+    async shutdown() {
+        this.isRunning = false;
+        this.confirmationHandler.close();
+        await this.saveState();
+    }
+    /**
+     * Check if orchestrator is running
+     */
+    isActive() {
+        return this.isRunning;
+    }
+    /**
+     * Start the agent session
+     */
+    start() {
+        this.isRunning = true;
+    }
+    // Private methods
+    async getAIResponse() {
+        if (!this.aiClient) {
+            throw new Error("AI client not initialized");
+        }
+        try {
+            const messages = this.context.formatForAI();
+            const prompt = this.buildPromptWithTools(messages);
+            const response = await this.aiClient.analyze(prompt);
+            return response.content;
+        }
+        catch (error) {
+            logger_1.logger.error(`Failed to get AI response: ${error}`);
+            return "I apologize, but I'm having trouble processing your request right now. Please try again.";
+        }
+    }
+    buildPromptWithTools(messages) {
+        const conversation = messages
+            .map((m) => `${m.role}: ${m.content}`)
+            .join("\n\n");
+        const tools = this.skillRegistry.getToolDefinitions();
+        const toolsDescription = tools
+            .map((tool) => `
+Tool: ${tool.name}
+Description: ${tool.description}
+Parameters:
+${tool.parameters
+            .map((p) => `  - ${p.name} (${p.type}${p.required ? ", required" : ""}): ${p.description}${p.default !== undefined ? ` (default: ${p.default})` : ""}`)
+            .join("\n")}
+`)
+            .join("\n");
+        return `${conversation}
+
+Available Tools:
+${toolsDescription}
+
+When you need to use a tool, format your response exactly like this:
+
+<tool_call>
+{
+  "name": "tool_name",
+  "arguments": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+</tool_call>
+
+If you don't need a tool, just respond naturally.`;
+    }
+    parseToolCalls(response) {
+        const toolCalls = [];
+        const regex = /<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/g;
+        let match;
+        while ((match = regex.exec(response)) !== null) {
+            try {
+                const parsed = JSON.parse(match[1]);
+                toolCalls.push({
+                    id: `tool-${Date.now()}-${toolCalls.length}`,
+                    name: parsed.name,
+                    arguments: parsed.arguments || {},
+                });
+            }
+            catch (error) {
+                logger_1.logger.warn(`Failed to parse tool call: ${match[1]}`);
+            }
+        }
+        // Fallback: some models respond with <web_scan> { ...args } </web_scan> blocks.
+        // Accept any <toolName>{json}</toolName> where json is either {arguments} or {name, arguments}.
+        if (toolCalls.length === 0) {
+            const alt = /<([a-zA-Z0-9_]+)>\s*([\s\S]*?)\s*<\/\1>/g;
+            let m;
+            while ((m = alt.exec(response)) !== null) {
+                const tag = m[1];
+                if (tag === "tool_call")
+                    continue;
+                try {
+                    const parsed = JSON.parse(m[2]);
+                    const name = typeof parsed?.name === "string" ? parsed.name : tag;
+                    const args = parsed && typeof parsed === "object" && "arguments" in parsed
+                        ? parsed.arguments
+                        : parsed;
+                    toolCalls.push({
+                        id: `tool-${Date.now()}-${toolCalls.length}`,
+                        name,
+                        arguments: args || {},
+                    });
+                }
+                catch {
+                    // Ignore non-json blocks.
+                }
+            }
+        }
+        return toolCalls;
+    }
+    async handleToolExecution(toolCalls, aiMessage) {
+        // Extract message without tool calls
+        const skillTags = this.skillRegistry
+            .getAll()
+            .map((s) => s.id)
+            .join("|");
+        const toolCallBlock = /<tool_call>[\s\S]*?<\/tool_call>/g;
+        const altToolBlocks = skillTags
+            ? new RegExp(`<(${skillTags})>\\s*[\\s\\S]*?\\s*<\\/\\1>`, "g")
+            : null;
+        const cleanMessage = aiMessage
+            .replace(toolCallBlock, "")
+            .replace(altToolBlocks ?? /$^/, "")
+            .trim();
+        // Check if any tool requires confirmation
+        const needsConfirmation = toolCalls.some((call) => this.skillRegistry.requiresConfirmation(call.name));
+        if (needsConfirmation && this.config.enableConfirmation) {
+            // Get confirmation for first tool (simplify UX)
+            const firstTool = toolCalls.find((call) => this.skillRegistry.requiresConfirmation(call.name));
+            const confirmation = this.skillRegistry.getConfirmationPrompt(firstTool);
+            if (confirmation) {
+                const result = await this.confirmationHandler.prompt(confirmation);
+                if (result.showDetails) {
+                    this.confirmationHandler.showDetails(confirmation);
+                    return {
+                        message: cleanMessage || "Please review the details and confirm to proceed.",
+                        requiresConfirmation: true,
+                        pendingAction: {
+                            toolName: firstTool.name,
+                            description: confirmation.description,
+                            parameters: firstTool.arguments,
+                            risk: confirmation.risk,
+                        },
+                    };
+                }
+                if (!result.confirmed) {
+                    return {
+                        message: result.cancelled
+                            ? "Action cancelled."
+                            : "Action not confirmed. Let me know when you're ready to proceed.",
+                        requiresConfirmation: false,
+                    };
+                }
+            }
+        }
+        // Execute all tools
+        console.log(chalk_1.default.gray("\nExecuting tools...\n"));
+        const results = await this.skillRegistry.executeBatch(toolCalls, this.context.getContext());
+        // Format results
+        const resultMessage = results
+            .map((result) => this.formatToolResult(result))
+            .join("\n\n");
+        const fullMessage = cleanMessage
+            ? `${cleanMessage}\n\n${resultMessage}`
+            : resultMessage;
+        this.context.addMessage("assistant", fullMessage, toolCalls, results);
+        // Update context with scan results
+        const scanCall = toolCalls.find((t) => t.name === "web_scan");
+        if (scanCall) {
+            const scanExec = results.find((r) => r.toolCallId === scanCall.id);
+            if (scanExec?.success && scanExec.result) {
+                this.context.setLastScanResults(scanExec.result);
+                const target = scanCall.arguments.targetUrl;
+                if (target) {
+                    this.context.setCurrentTarget(target);
+                }
+            }
+        }
+        return {
+            message: fullMessage,
+            toolCalls,
+            toolCallResults: results,
+            requiresConfirmation: false,
+        };
+    }
+    formatToolResult(result) {
+        if (!result.success) {
+            return chalk_1.default.red(`❌ Error: ${result.error || "Unknown error"}`);
+        }
+        const skillResult = result.result;
+        if (!skillResult) {
+            return chalk_1.default.gray("✓ Completed");
+        }
+        const findings = skillResult.findings || [];
+        if (findings.length === 0) {
+            return chalk_1.default.green("✓ No issues found");
+        }
+        const critical = findings.filter((f) => f.severity === "critical").length;
+        const high = findings.filter((f) => f.severity === "high").length;
+        const medium = findings.filter((f) => f.severity === "medium").length;
+        const low = findings.filter((f) => f.severity === "low").length;
+        const parts = [];
+        if (critical > 0)
+            parts.push(chalk_1.default.red(`${critical} Critical`));
+        if (high > 0)
+            parts.push(chalk_1.default.red(`${high} High`));
+        if (medium > 0)
+            parts.push(chalk_1.default.yellow(`${medium} Medium`));
+        if (low > 0)
+            parts.push(chalk_1.default.blue(`${low} Low`));
+        return `Found: ${parts.join(", ") || chalk_1.default.green("None")}`;
+    }
+}
+exports.AgentOrchestrator = AgentOrchestrator;

package/dist/agent/prompts/system.d.ts

@@ -0,0 +1,6 @@
+/**
+ * System prompts for the AI Security Agent
+ * Defines the AI's role, capabilities, and behavior
+ */
+export declare const SYSTEM_PROMPT = "You are KramScan Security Agent, an expert AI security assistant that helps users identify and fix vulnerabilities in web applications.\n\n## Your Role\n- Analyze security-related requests and select appropriate tools/skills\n- Guide users through security testing workflows\n- Explain findings in clear, actionable terms\n- Prioritize safety and never perform destructive actions without explicit confirmation\n\n## Available Tools\nYou have access to the following security testing tools:\n\n1. **web_scan** - Comprehensive web application security scan\n   - Tests for XSS, SQL injection, CSRF, security headers\n   - Crawls the target website\n   - Provides detailed vulnerability report\n   - Risk: Medium (may trigger WAFs)\n\n2. **analyze_findings** - AI-powered analysis of scan results\n   - Reviews vulnerabilities and provides expert insights\n   - Generates remediation recommendations\n   - Assesses overall risk level\n   - Risk: Low (read-only analysis)\n\n3. **generate_report** - Create professional security reports\n   - Formats: DOCX, TXT, JSON\n   - Includes executive summary and technical details\n   - Risk: Low (file generation only)\n\n4. **health_check** - Verify system setup and configuration\n   - Checks API keys, dependencies, permissions\n   - Risk: Low (diagnostic only)\n\n## Guidelines\n\n### When to Use Tools\n- **Always** use web_scan when user asks to scan, test, or check a website\n- **Always** use analyze_findings after a scan completes to provide insights\n- Use generate_report when user asks for a report or documentation\n- Use health_check when user mentions setup issues\n\n### Tool Calling Format\nWhen you need to execute a tool, respond with a tool call in this format:\n\n<tool_call>\n{\n  \"name\": \"web_scan\",\n  \"arguments\": {\n    \"targetUrl\": \"https://example.com\",\n    \"depth\": 2,\n    \"timeout\": 30000\n  }\n}\n</tool_call>\n\nYou can make multiple tool calls if needed. Wait for results before proceeding.\n\nImportant:\n- Only use the <tool_call> ... </tool_call> wrapper. Do not invent tags like <web_scan> ... </web_scan>.\n\n### Confirmation Requirements\n- **High/Medium risk tools** (like web_scan): Always ask for confirmation before executing\n- **Low risk tools** (analyze, report): Can execute directly\n- **Destructive actions**: Never perform without explicit user approval\n\n### Response Format\n1. Acknowledge the user's request\n2. Explain what you plan to do\n3. If tool execution is needed, make the tool call\n4. After receiving results, provide:\n   - Summary of findings\n   - Severity assessment\n   - Specific recommendations\n   - Next steps\n\n### Safety Rules\n- Never scan targets without user confirmation\n- Respect rate limits and don't overwhelm targets\n- Clearly label all findings with severity levels\n- Provide remediation steps for each vulnerability\n- If uncertain, ask clarifying questions\n\n### Conversation Context\n- You can reference previous scans and findings in the conversation\n- Keep track of the current target being discussed\n- Remember user preferences from earlier in the conversation\n\n## Example Interactions\n\nUser: \"Check my website for security issues\"\nAssistant: \"I'll help you scan your website for security vulnerabilities. Could you please provide the URL you'd like me to scan?\"\n\nUser: \"Scan https://example.com\"\nAssistant: \"I'll perform a comprehensive security scan of https://example.com. This will check for XSS, SQL injection, CSRF vulnerabilities, and security header misconfigurations. The scan will crawl up to 2 levels deep and respect a 30-second timeout.\n\nWould you like me to proceed with the scan? [Y/n/details]\"\n\n[After confirmation]\n<tool_call>\n{\n  \"name\": \"web_scan\",\n  \"arguments\": {\n    \"targetUrl\": \"https://example.com\",\n    \"depth\": 2,\n    \"timeout\": 30000\n  }\n}\n</tool_call>";
+export declare const getSystemPrompt: () => string;

package/dist/agent/prompts/system.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * System prompts for the AI Security Agent
+ * Defines the AI's role, capabilities, and behavior
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSystemPrompt = exports.SYSTEM_PROMPT = void 0;
+exports.SYSTEM_PROMPT = `You are KramScan Security Agent, an expert AI security assistant that helps users identify and fix vulnerabilities in web applications.
+
+## Your Role
+- Analyze security-related requests and select appropriate tools/skills
+- Guide users through security testing workflows
+- Explain findings in clear, actionable terms
+- Prioritize safety and never perform destructive actions without explicit confirmation
+
+## Available Tools
+You have access to the following security testing tools:
+
+1. **web_scan** - Comprehensive web application security scan
+   - Tests for XSS, SQL injection, CSRF, security headers
+   - Crawls the target website
+   - Provides detailed vulnerability report
+   - Risk: Medium (may trigger WAFs)
+
+2. **analyze_findings** - AI-powered analysis of scan results
+   - Reviews vulnerabilities and provides expert insights
+   - Generates remediation recommendations
+   - Assesses overall risk level
+   - Risk: Low (read-only analysis)
+
+3. **generate_report** - Create professional security reports
+   - Formats: DOCX, TXT, JSON
+   - Includes executive summary and technical details
+   - Risk: Low (file generation only)
+
+4. **health_check** - Verify system setup and configuration
+   - Checks API keys, dependencies, permissions
+   - Risk: Low (diagnostic only)
+
+## Guidelines
+
+### When to Use Tools
+- **Always** use web_scan when user asks to scan, test, or check a website
+- **Always** use analyze_findings after a scan completes to provide insights
+- Use generate_report when user asks for a report or documentation
+- Use health_check when user mentions setup issues
+
+### Tool Calling Format
+When you need to execute a tool, respond with a tool call in this format:
+
+<tool_call>
+{
+  "name": "web_scan",
+  "arguments": {
+    "targetUrl": "https://example.com",
+    "depth": 2,
+    "timeout": 30000
+  }
+}
+</tool_call>
+
+You can make multiple tool calls if needed. Wait for results before proceeding.
+
+Important:
+- Only use the <tool_call> ... </tool_call> wrapper. Do not invent tags like <web_scan> ... </web_scan>.
+
+### Confirmation Requirements
+- **High/Medium risk tools** (like web_scan): Always ask for confirmation before executing
+- **Low risk tools** (analyze, report): Can execute directly
+- **Destructive actions**: Never perform without explicit user approval
+
+### Response Format
+1. Acknowledge the user's request
+2. Explain what you plan to do
+3. If tool execution is needed, make the tool call
+4. After receiving results, provide:
+   - Summary of findings
+   - Severity assessment
+   - Specific recommendations
+   - Next steps
+
+### Safety Rules
+- Never scan targets without user confirmation
+- Respect rate limits and don't overwhelm targets
+- Clearly label all findings with severity levels
+- Provide remediation steps for each vulnerability
+- If uncertain, ask clarifying questions
+
+### Conversation Context
+- You can reference previous scans and findings in the conversation
+- Keep track of the current target being discussed
+- Remember user preferences from earlier in the conversation
+
+## Example Interactions
+
+User: "Check my website for security issues"
+Assistant: "I'll help you scan your website for security vulnerabilities. Could you please provide the URL you'd like me to scan?"
+
+User: "Scan https://example.com"
+Assistant: "I'll perform a comprehensive security scan of https://example.com. This will check for XSS, SQL injection, CSRF vulnerabilities, and security header misconfigurations. The scan will crawl up to 2 levels deep and respect a 30-second timeout.
+
+Would you like me to proceed with the scan? [Y/n/details]"
+
+[After confirmation]
+<tool_call>
+{
+  "name": "web_scan",
+  "arguments": {
+    "targetUrl": "https://example.com",
+    "depth": 2,
+    "timeout": 30000
+  }
+}
+</tool_call>`;
+const getSystemPrompt = () => exports.SYSTEM_PROMPT;
+exports.getSystemPrompt = getSystemPrompt;

package/dist/agent/skill-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Skill Registry and Execution System
+ * Manages AI-callable security skills with validation, confirmation, and execution
+ */
+import { AgentSkill, ToolDefinition, ToolCall, ToolCallResult, AgentContext, ConfirmationPrompt } from "./types";
+export declare class SkillRegistry {
+    private skills;
+    private executionHistory;
+    /**
+     * Register a skill with the registry
+     */
+    register(skill: AgentSkill): void;
+    /**
+     * Unregister a skill
+     */
+    unregister(skillId: string): boolean;
+    /**
+     * Get a skill by ID
+     */
+    get(skillId: string): AgentSkill | undefined;
+    /**
+     * Get all registered skills
+     */
+    getAll(): AgentSkill[];
+    /**
+     * Get all tool definitions for AI function calling
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Validate tool call parameters
+     */
+    validateToolCall(toolCall: ToolCall): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Check if a tool call requires confirmation
+     */
+    requiresConfirmation(toolName: string): boolean;
+    /**
+     * Get confirmation prompt for a tool call
+     */
+    getConfirmationPrompt(toolCall: ToolCall): ConfirmationPrompt | null;
+    /**
+     * Execute a skill by tool call
+     */
+    execute(toolCall: ToolCall, context: AgentContext): Promise<ToolCallResult>;
+    /**
+     * Execute multiple skills in parallel
+     */
+    executeBatch(toolCalls: ToolCall[], context: AgentContext): Promise<ToolCallResult[]>;
+    /**
+     * Get execution statistics
+     */
+    getStats(): {
+        totalExecutions: number;
+        successfulExecutions: number;
+        failedExecutions: number;
+        averageDuration: number;
+        skillUsage: Record<string, number>;
+    };
+    /**
+     * Clear execution history
+     */
+    clearHistory(): void;
+    /**
+     * List available skills with descriptions
+     */
+    listSkills(): Array<{
+        id: string;
+        name: string;
+        description: string;
+        risk: string;
+        requiresConfirmation: boolean;
+    }>;
+    private formatDuration;
+}
+export declare const skillRegistry: SkillRegistry;