kramscan 0.1.0 → 0.2.0

package/dist/agent/skill-registry.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Skill Registry and Execution System
+ * Manages AI-callable security skills with validation, confirmation, and execution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillRegistry = exports.SkillRegistry = void 0;
+const logger_1 = require("../utils/logger");
+class SkillRegistry {
+    skills = new Map();
+    executionHistory = [];
+    /**
+     * Register a skill with the registry
+     */
+    register(skill) {
+        if (this.skills.has(skill.id)) {
+            logger_1.logger.warn(`Skill ${skill.id} is already registered. Overwriting.`);
+        }
+        this.skills.set(skill.id, skill);
+        logger_1.logger.debug(`Registered skill: ${skill.id}`);
+    }
+    /**
+     * Unregister a skill
+     */
+    unregister(skillId) {
+        return this.skills.delete(skillId);
+    }
+    /**
+     * Get a skill by ID
+     */
+    get(skillId) {
+        return this.skills.get(skillId);
+    }
+    /**
+     * Get all registered skills
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Get all tool definitions for AI function calling
+     */
+    getToolDefinitions() {
+        return this.getAll().map((skill) => skill.toolDefinition);
+    }
+    /**
+     * Validate tool call parameters
+     */
+    validateToolCall(toolCall) {
+        const skill = this.get(toolCall.name);
+        if (!skill) {
+            return {
+                valid: false,
+                errors: [`Unknown skill: ${toolCall.name}`],
+            };
+        }
+        return skill.validateParameters(toolCall.arguments);
+    }
+    /**
+     * Check if a tool call requires confirmation
+     */
+    requiresConfirmation(toolName) {
+        const skill = this.get(toolName);
+        if (!skill)
+            return false;
+        return skill.requiresConfirmation;
+    }
+    /**
+     * Get confirmation prompt for a tool call
+     */
+    getConfirmationPrompt(toolCall) {
+        const skill = this.get(toolCall.name);
+        if (!skill)
+            return null;
+        return {
+            action: skill.name,
+            description: skill.description,
+            parameters: toolCall.arguments,
+            risk: skill.riskLevel,
+            estimatedTime: this.formatDuration(skill.estimatedDuration),
+        };
+    }
+    /**
+     * Execute a skill by tool call
+     */
+    async execute(toolCall, context) {
+        const skill = this.get(toolCall.name);
+        if (!skill) {
+            return {
+                toolCallId: toolCall.id,
+                success: false,
+                error: `Unknown skill: ${toolCall.name}`,
+                executionTime: 0,
+            };
+        }
+        // Validate parameters
+        const validation = skill.validateParameters(toolCall.arguments);
+        if (!validation.valid) {
+            return {
+                toolCallId: toolCall.id,
+                success: false,
+                error: `Validation failed: ${validation.errors.join(", ")}`,
+                executionTime: 0,
+            };
+        }
+        const startTime = Date.now();
+        let result;
+        let success = false;
+        let error;
+        try {
+            logger_1.logger.info(`Executing skill: ${skill.id}`);
+            result = await skill.execute(toolCall.arguments, context);
+            success = true;
+            logger_1.logger.success(`Skill ${skill.id} completed successfully`);
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : String(err);
+            logger_1.logger.error(`Skill ${skill.id} failed: ${error}`);
+            result = {
+                skillId: skill.id,
+                findings: [],
+                metadata: { error },
+            };
+        }
+        const executionTime = Date.now() - startTime;
+        // Record execution history
+        this.executionHistory.push({
+            timestamp: new Date(),
+            skillName: skill.id,
+            success,
+            duration: executionTime,
+        });
+        return {
+            toolCallId: toolCall.id,
+            success,
+            result,
+            error,
+            executionTime,
+        };
+    }
+    /**
+     * Execute multiple skills in parallel
+     */
+    async executeBatch(toolCalls, context) {
+        const promises = toolCalls.map((call) => this.execute(call, context));
+        return Promise.all(promises);
+    }
+    /**
+     * Get execution statistics
+     */
+    getStats() {
+        const total = this.executionHistory.length;
+        const successful = this.executionHistory.filter((e) => e.success).length;
+        const failed = total - successful;
+        const avgDuration = total > 0
+            ? this.executionHistory.reduce((sum, e) => sum + e.duration, 0) / total
+            : 0;
+        const skillUsage = {};
+        for (const entry of this.executionHistory) {
+            skillUsage[entry.skillName] = (skillUsage[entry.skillName] || 0) + 1;
+        }
+        return {
+            totalExecutions: total,
+            successfulExecutions: successful,
+            failedExecutions: failed,
+            averageDuration: Math.round(avgDuration),
+            skillUsage,
+        };
+    }
+    /**
+     * Clear execution history
+     */
+    clearHistory() {
+        this.executionHistory = [];
+    }
+    /**
+     * List available skills with descriptions
+     */
+    listSkills() {
+        return this.getAll().map((skill) => ({
+            id: skill.id,
+            name: skill.name,
+            description: skill.description,
+            risk: skill.riskLevel,
+            requiresConfirmation: skill.requiresConfirmation,
+        }));
+    }
+    formatDuration(seconds) {
+        if (seconds < 60) {
+            return `${seconds}s`;
+        }
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = seconds % 60;
+        if (remainingSeconds === 0) {
+            return `${minutes}m`;
+        }
+        return `${minutes}m ${remainingSeconds}s`;
+    }
+}
+exports.SkillRegistry = SkillRegistry;
+// Global skill registry instance
+exports.skillRegistry = new SkillRegistry();

package/dist/agent/skills/analyze-findings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Analyze Findings Skill
+ * AI-powered analysis of security scan results with remediation recommendations
+ */
+import { AgentSkill, ToolDefinition, AgentContext, SkillResult } from "../types";
+export declare class AnalyzeFindingsSkill implements AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    requiresConfirmation: boolean;
+    riskLevel: "low";
+    estimatedDuration: number;
+    toolDefinition: ToolDefinition;
+    validateParameters(params: Record<string, unknown>): {
+        valid: boolean;
+        errors: string[];
+    };
+    execute(params: Record<string, unknown>, context: AgentContext): Promise<SkillResult>;
+    private buildAnalysisPrompt;
+    run(): Promise<SkillResult>;
+}

package/dist/agent/skills/analyze-findings.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Analyze Findings Skill
+ * AI-powered analysis of security scan results with remediation recommendations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyzeFindingsSkill = void 0;
+const ai_client_1 = require("../../core/ai-client");
+const logger_1 = require("../../utils/logger");
+class AnalyzeFindingsSkill {
+    id = "analyze_findings";
+    name = "Analyze Findings";
+    description = "Uses AI to analyze security scan results and provide expert insights, risk assessment, and remediation recommendations.";
+    tags = ["analysis", "ai", "reporting", "recommendations"];
+    requiresConfirmation = false;
+    riskLevel = "low";
+    estimatedDuration = 15; // seconds
+    toolDefinition = {
+        name: "analyze_findings",
+        description: "Analyze security scan findings using AI to provide expert insights and remediation recommendations",
+        parameters: [
+            {
+                name: "useLastScan",
+                type: "boolean",
+                description: "Use results from the most recent scan. If true, scanResults parameter is optional.",
+                required: false,
+                default: true,
+            },
+            {
+                name: "scanResults",
+                type: "object",
+                description: "Scan results to analyze (if not using last scan). Must contain findings array.",
+                required: false,
+            },
+            {
+                name: "focus",
+                type: "string",
+                description: "Optional focus area for analysis: 'executive', 'technical', 'remediation', or 'all'",
+                required: false,
+                default: "all",
+                enum: ["executive", "technical", "remediation", "all"],
+            },
+        ],
+    };
+    validateParameters(params) {
+        const errors = [];
+        // If not using last scan, must provide scanResults
+        if (params.useLastScan === false && !params.scanResults) {
+            errors.push("scanResults is required when useLastScan is false");
+        }
+        // Validate focus if provided
+        if (params.focus) {
+            const validFocus = ["executive", "technical", "remediation", "all"];
+            if (!validFocus.includes(params.focus)) {
+                errors.push(`focus must be one of: ${validFocus.join(", ")}`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    async execute(params, context) {
+        const useLastScan = params.useLastScan ?? true;
+        const focus = params.focus ?? "all";
+        let scanData;
+        // Get scan data
+        if (useLastScan) {
+            const lastResults = context.lastScanResults;
+            if (!lastResults) {
+                return {
+                    skillId: this.id,
+                    findings: [],
+                    metadata: {
+                        error: "No previous scan results found. Please run a scan first.",
+                    },
+                };
+            }
+            scanData = lastResults;
+        }
+        else {
+            scanData = params.scanResults;
+        }
+        if (!scanData.findings || scanData.findings.length === 0) {
+            return {
+                skillId: this.id,
+                findings: [],
+                metadata: {
+                    message: "No vulnerabilities to analyze.",
+                    target: scanData.target,
+                },
+            };
+        }
+        logger_1.logger.info(`Analyzing ${scanData.findings.length} findings with focus: ${focus}`);
+        try {
+            const aiClient = await (0, ai_client_1.createAIClient)();
+            const prompt = this.buildAnalysisPrompt(scanData, focus);
+            const response = await aiClient.analyze(prompt);
+            // Create a finding for the analysis itself
+            const analysisFinding = {
+                id: `analysis-${Date.now()}`,
+                skillId: this.id,
+                title: "AI Security Analysis",
+                severity: "info",
+                description: response.content,
+                metadata: {
+                    focus,
+                    target: scanData.target,
+                    timestamp: new Date().toISOString(),
+                    totalFindings: scanData.findings.length,
+                    tokensUsed: response.usage,
+                },
+            };
+            logger_1.logger.success("Analysis complete");
+            return {
+                skillId: this.id,
+                findings: [analysisFinding],
+                metadata: {
+                    target: scanData.target,
+                    focus,
+                    totalFindings: scanData.findings.length,
+                    tokensUsed: response.usage,
+                    timestamp: new Date().toISOString(),
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger_1.logger.error(`Analysis failed: ${errorMessage}`);
+            return {
+                skillId: this.id,
+                findings: [],
+                metadata: {
+                    error: errorMessage,
+                    target: scanData.target,
+                },
+            };
+        }
+    }
+    buildAnalysisPrompt(scanData, focus) {
+        const vulnList = scanData.findings
+            .map((f, i) => `${i + 1}. [${f.severity.toUpperCase()}] ${f.title}
+   Description: ${f.description}
+   ${f.evidence ? `Evidence: ${f.evidence}` : ""}
+   ${f.recommendation ? `Current recommendation: ${f.recommendation}` : ""}
+   ${f.metadata?.cwe ? `CWE: ${f.metadata.cwe}` : ""}`)
+            .join("\n\n");
+        let focusInstructions = "";
+        switch (focus) {
+            case "executive":
+                focusInstructions =
+                    "Focus on business impact and high-level recommendations. Keep technical details minimal.";
+                break;
+            case "technical":
+                focusInstructions =
+                    "Provide detailed technical analysis including root causes and specific code/configuration fixes.";
+                break;
+            case "remediation":
+                focusInstructions =
+                    "Focus primarily on step-by-step remediation actions and prioritization.";
+                break;
+            default:
+                focusInstructions =
+                    "Provide comprehensive analysis covering all aspects.";
+        }
+        return `You are a senior security analyst reviewing web application vulnerabilities.
+
+Target: ${scanData.target || "Unknown"}
+Scan Date: ${scanData.timestamp || new Date().toISOString()}
+Total Vulnerabilities: ${scanData.findings.length}
+
+Vulnerabilities Found:
+${vulnList}
+
+Please provide a detailed analysis:
+
+1. **Executive Summary**: Brief overview of security posture and business risk
+2. **Risk Assessment**: Overall risk level with justification
+3. **Prioritized Recommendations**: Top 3-5 issues to fix first with specific actions
+4. **Attack Scenarios**: How vulnerabilities could be chained or exploited
+5. **Remediation Roadmap**: Step-by-step plan with effort estimates
+
+${focusInstructions}
+
+Format in clear markdown with headers and bullet points.`;
+    }
+    async run() {
+        throw new Error("Use execute() method with AgentContext for analyze findings skill");
+    }
+}
+exports.AnalyzeFindingsSkill = AnalyzeFindingsSkill;

package/dist/agent/skills/generate-report.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generate Report Skill
+ * Creates professional security reports in multiple formats (DOCX, TXT, JSON)
+ */
+import { AgentSkill, ToolDefinition, AgentContext, SkillResult } from "../types";
+export declare class GenerateReportSkill implements AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    requiresConfirmation: boolean;
+    riskLevel: "low";
+    estimatedDuration: number;
+    toolDefinition: ToolDefinition;
+    validateParameters(params: Record<string, unknown>): {
+        valid: boolean;
+        errors: string[];
+    };
+    execute(params: Record<string, unknown>, context: AgentContext): Promise<SkillResult>;
+    private generateDocxReport;
+    private generateTxtReport;
+    private generateJsonReport;
+    private getSeverityCount;
+    private getSeverityColor;
+    run(): Promise<SkillResult>;
+}