kramscan 0.1.0 → 0.1.1

package/README.md

@@ -1,87 +1,236 @@
-# KramScan 🛡️
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/6439c670-8d73-4bdd-b8fa-c74de949a31e" width="500" alt="KramScan Logo" />
 
-KramScan is a personal, AI-powered command-line interface (CLI) for web application security testing. It combines automated browser interactions (via Puppeteer) with AI analysis to identify vulnerabilities in modern web apps.
+  <h3 align="center">AI-Powered Web Application Security Testing CLI</h3>
+
+  <br />
+
+  [![npm version](https://img.shields.io/npm/v/kramscan?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/kramscan)
+  [![npm downloads](https://img.shields.io/npm/dm/kramscan?style=for-the-badge&logo=npm&logoColor=white&color=blue)](https://www.npmjs.com/package/kramscan)
+  [![License](https://img.shields.io/github/license/shaikhakramshakil/kramscan?style=for-the-badge&logo=github&logoColor=white&color=green)](https://github.com/shaikhakramshakil/kramscan/blob/main/LICENSE)
+  [![Stars](https://img.shields.io/github/stars/shaikhakramshakil/kramscan?style=for-the-badge&logo=github&logoColor=white&color=yellow)](https://github.com/shaikhakramshakil/kramscan)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178c6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?style=for-the-badge&logo=nodedotjs&logoColor=white)](https://nodejs.org)
+
+  <br />
+
+  🔬 **A next-generation security auditing tool that combines automated vulnerability scanning with multi-provider AI analysis.**
+
+  *Empowering developers and security researchers with institutional-grade insights and an interactive AI agent.*
+
+  <br />
+
+  [🌐 NPM Package](https://www.npmjs.com/package/kramscan) · [📖 Documentation](#-usage) · [🐞 Report Bug](https://github.com/shaikhakramshakil/kramscan/issues)
+
+</div>
 
 ---
 
-## Quick Start
+<br />
 
-```bash
-# Install dependencies
-npm install
+## 🚀 The Problem We Solve
+Web security is complex and often fragmented. Developers rely on multiple disjointed tools for scanning, manual testing, and reporting. Traditional automated scanners generate noise without context, and manual pentesting is time-consuming and expensive.
+
+**KramScan bridges this gap.** We provide a unified command-line interface that orchestrates headless browser scanning, scrapes critical security headers, and leverages **Generative AI** (OpenAI, Gemini, Anthropic) to analyze findings. It delivers actionable, human-readable insights alongside raw vulnerability data—all in seconds.
+
+<br />
+
+---
 
-# Build the project
-npm run build
+<br />
 
-# Link globally so you can use "kramscan" from anywhere
-npm link
+## ✨ Key Features
+| Feature | Description |
+| :--- | :--- |
+| 🔍 **Automated Vulnerability Engine** | Detects XSS, SQL Injection, CSRF, and insecure headers using Puppeteer-powered crawling. |
+| 🤖 **Interactive AI Agent** | A conversational security assistant that understands natural language commands like "scan example.com". |
+| 🧠 **Multi-Provider AI Analysis** | Supports OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, and Kimi (Moonshot). |
+| 📄 **Professional Reporting** | Generates detailed DOCX, TXT, and JSON reports with executive summaries and remediation steps. |
+| 🌐 **Headless Browser Testing** | Renders modern SPAs (Single Page Applications) to find vulnerabilities in dynamic content. |
+| ⚡ **CLI-First Architecture** | Optimized for speed, scriptability, and seamless integration into CI/CD pipelines. |
 
-# Launch the interactive dashboard
-kramscan
+<br />
+
+---
+
+<br />
+
+## 🏗️ Architecture & Workflow
+
+```mermaid
+graph LR
+    A[User Command] --> B{CLI Controller};
+    B --> C[Scanner Module<br/>Puppeteer / Cheerio];
+    B --> D[AI Agent<br/>NLP Processing];
+    
+    C --> E[Vulnerability Detection<br/>XSS / SQLi / Headers];
+    C --> F[Data Aggregation];
+    
+    E & F --> G[AI Analysis Engine<br/>LLM Provider];
+    
+    G --> H[Risk Assessment<br/>Confidence Scoring];
+    H --> I[Report Generator<br/>DOCX / JSON / TXT];
+    I --> J((Final Output));
 ```
 
+<br />
+
 ---
 
-## Commands
+<br />
+
+## 🧪 Tech Stack
+<div align="center">
+
+| Component | Technology |
+| :--- | :--- |
+| **Runtime** | Node.js ≥ 18 |
+| **Language** | TypeScript 5.4 |
+| **CLI Framework** | Commander.js, Inquirer.js |
+| **Browser Automation** | Puppeteer (Headless Chrome) |
+| **AI Integration** | OpenAI SDK, Google Generative AI, Anthropic SDK |
+| **Reporting** | Docx, Chalk|
+| **Package Manager** | NPM / Yarn / PNPM |
+
+</div>
 
-| Command            | Description                          | Status       |
-|:-------------------|:-------------------------------------|:-------------|
-| `kramscan`         | Launch interactive dashboard         | ✅ Active    |
-| `kramscan onboard` | First-time setup wizard              | ✅ Active    |
-| `kramscan scan`    | Scan a target URL                    | 🔜 Coming   |
-| `kramscan analyze` | AI-powered analysis of scan results  | 🔜 Coming   |
-| `kramscan report`  | Generate a professional report       | 🔜 Coming   |
-| `kramscan doctor`  | Check environment health             | 🔜 Coming   |
-| `kramscan --help`  | Show all available commands          | ✅ Active    |
+<br />
 
 ---
 
-## Setup Wizard
+<br />
 
-Run `kramscan onboard` to configure:
+## 🧠 Supported AI Providers
 
-1. **AI Provider** — OpenAI or Anthropic
-2. **API Key** — Your provider API key
-3. **Default Model** — e.g. `gpt-4`
-4. **Report Format** — Word, TXT, or JSON
-5. **Scope Enforcement** — Strict mode on/off
-6. **Rate Limiting** — Requests per second
+| Provider | SDK / Integration | Default Model |
+| :--- | :--- | :--- |
+| **OpenAI** | `openai` | `gpt-4` |
+| **Anthropic** | `@anthropic-ai/sdk` | `claude-3-5-sonnet-20241022` |
+| **Google Gemini** | `@google/generative-ai` | `gemini-2.0-flash-exp` |
+| **Mistral** | `@mistralai/mistralai` | `mistral-large-latest` |
+| **OpenRouter** | OpenAI-compatible | `anthropic/claude-3.5-sonnet` |
+| **Kimi** | OpenAI-compatible | `moonshot-v1-8k` |
 
-Configuration is saved to `~/.kramscan/config.json`.
+> Switch providers instantly with `kramscan onboard` or by editing `~/.kramscan/config.json`.
+
+<br />
 
 ---
 
-## Development
+<br />
+
+## 🚀 Quick Start
+
+### 1. Installation
+Install KramScan globally using npm:
+
+```bash
+npm install -g kramscan
+```
+
+### 2. First-Time Setup
+Initialize the configuration wizard to set up your AI provider and API keys:
 
 ```bash
-# Run without building (using tsx)
-npx tsx src/index.ts
+kramscan onboard
+```
 
-# Run a specific command
-npx tsx src/index.ts onboard
+### 3. Run a Scan
+Execute a full security scan on a target URL:
 
-# Build
-npm run build
+```bash
+kramscan scan https://example.com
+```
+
+<br />
+
+---
+
+<br />
+
+## 📖 Usage & Commands
+
+| Command | Description | Status |
+| :--- | :--- | :---: |
+| `kramscan` | Launch the interactive dashboard menu. | ✅ Stable |
+| `kramscan scan <url>` | Run a comprehensive vulnerability scan. | ✅ Stable |
+| `kramscan agent` | Start the conversational AI security assistant. | ✅ Stable |
+| `kramscan analyze` | Analyze previous scan results using the configured AI. | ✅ Stable |
+| `kramscan report` | Generate a professional report from scan data. | ✅ Stable |
+| `kramscan onboard` | Run the configuration and setup wizard. | ✅ Stable |
+| `kramscan doctor` | Verify environment health and dependencies. | ✅ Stable |
+| `kramscan config` | View and edit current configuration settings. | ✅ Stable |
+
+<br />
+
+### Example Agent Session
+```bash
+$ kramscan agent
+> scan https://example.com
+
+Agent: I'll perform a comprehensive security scan of https://example.com.
+       Checking for XSS, SQLi, and missing headers...
+       [Scanning...]
+       
+Agent: Scan complete! Found 2 High severity issues.
+       Would you like me to generate a report?
 ```
 
+<br />
+
 ---
 
-## Tech Stack
+<br />
+
+## 🗺️ Roadmap
 
-- **TypeScript** + **Node.js**
-- **Commander.js** — CLI framework
-- **Inquirer.js** — Interactive prompts
-- **Puppeteer** — Browser automation
-- **ConfigStore** — Persistent configuration
+- [x] Core vulnerability scanner (XSS, SQLi, CSRF, headers)
+- [x] Multi-provider AI analysis engine
+- [x] Interactive AI agent mode
+- [x] Professional report generation (DOCX, TXT, JSON)
+- [x] Configuration wizard & management
+- [ ] Plugin system for custom scan modules
+- [ ] CI/CD integration (GitHub Actions, GitLab CI)
+- [ ] PDF report generation
+- [ ] Web-based dashboard UI
+
+<br />
 
 ---
 
-## Author
+<br />
+
+## 🔒 Security & Privacy
+- **Local Execution:** All scanning logic runs locally on your machine.
+- **API Key Safety:** AI provider API keys are stored securely in your local home directory and are never sent to our servers.
+- **Data Privacy:** Scan data is sent only to your chosen AI provider for analysis and is not stored by KramScan.
 
-**Akram** — *KramScan*
+<br />
 
 ---
 
-## License
+<br />
+
+## 👤 Author
+<div align="center">
+
+**Akram Shaikh**
+
+[![Website](https://img.shields.io/badge/Website-akramshaikh.me-blue?style=for-the-badge&logo=google-chrome&logoColor=white)](https://akramshaikh.me)
+[![GitHub](https://img.shields.io/badge/GitHub-shaikhakramshakil-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/shaikhakramshakil)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/shaikhakramshakil/)
+
+</div>
+
+<br />
+
+---
+
+<br />
+
+## 📄 License
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
 
-ISC
+<div align="center">
+  <sub>Made with ❤️ by Akram Shaikh</sub>
+</div>

package/dist/agent/confirmation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Confirmation Prompt System
+ * Handles user confirmation for skill execution with detailed risk assessment
+ */
+import { ConfirmationPrompt } from "./types";
+export interface ConfirmationResult {
+    confirmed: boolean;
+    showDetails: boolean;
+    cancelled: boolean;
+}
+export declare class ConfirmationHandler {
+    private rl;
+    constructor();
+    /**
+     * Display confirmation prompt and get user response
+     */
+    prompt(confirmation: ConfirmationPrompt): Promise<ConfirmationResult>;
+    /**
+     * Quick confirmation for low-risk actions
+     */
+    quickConfirm(action: string): Promise<boolean>;
+    /**
+     * Display detailed information about the action
+     */
+    showDetails(confirmation: ConfirmationPrompt): void;
+    /**
+     * Close the readline interface
+     */
+    close(): void;
+    private getUserInput;
+    private getRiskColor;
+    private getDetailedDescription;
+    private getSafetyInfo;
+}

package/dist/agent/confirmation.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Confirmation Prompt System
+ * Handles user confirmation for skill execution with detailed risk assessment
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfirmationHandler = void 0;
+const readline = __importStar(require("readline"));
+const chalk_1 = __importDefault(require("chalk"));
+class ConfirmationHandler {
+    rl;
+    constructor() {
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+    }
+    /**
+     * Display confirmation prompt and get user response
+     */
+    async prompt(confirmation) {
+        console.log("");
+        console.log(chalk_1.default.bold.yellow("⚠️  Action Requires Confirmation"));
+        console.log(chalk_1.default.gray("─".repeat(50)));
+        console.log("");
+        // Display action details
+        console.log(chalk_1.default.white("Action:"), chalk_1.default.cyan(confirmation.action));
+        console.log(chalk_1.default.white("Description:"), confirmation.description);
+        console.log("");
+        // Display risk level with color coding
+        const riskColor = this.getRiskColor(confirmation.risk);
+        console.log(chalk_1.default.white("Risk Level:"), riskColor(confirmation.risk.toUpperCase()));
+        console.log(chalk_1.default.white("Estimated Time:"), confirmation.estimatedTime);
+        console.log("");
+        // Display parameters
+        console.log(chalk_1.default.white("Parameters:"));
+        Object.entries(confirmation.parameters).forEach(([key, value]) => {
+            const displayValue = typeof value === "object" ? JSON.stringify(value) : String(value);
+            console.log(`  ${chalk_1.default.gray(key)}: ${chalk_1.default.white(displayValue)}`);
+        });
+        console.log("");
+        // Risk warnings
+        if (confirmation.risk === "high") {
+            console.log(chalk_1.default.red.bold("⚠️  WARNING: This action may have significant impact."));
+        }
+        else if (confirmation.risk === "medium") {
+            console.log(chalk_1.default.yellow("⚠️  This action will interact with external systems."));
+        }
+        console.log("");
+        // Get user input
+        return this.getUserInput();
+    }
+    /**
+     * Quick confirmation for low-risk actions
+     */
+    async quickConfirm(action) {
+        return new Promise((resolve) => {
+            this.rl.question(chalk_1.default.gray(`${action} [Y/n]: `), (answer) => {
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized === "" || normalized === "y" || normalized === "yes");
+            });
+        });
+    }
+    /**
+     * Display detailed information about the action
+     */
+    showDetails(confirmation) {
+        console.log("");
+        console.log(chalk_1.default.bold.cyan("📋 Action Details"));
+        console.log(chalk_1.default.gray("─".repeat(50)));
+        console.log("");
+        console.log(chalk_1.default.white("What will happen:"));
+        console.log(chalk_1.default.gray(this.getDetailedDescription(confirmation.action)));
+        console.log("");
+        console.log(chalk_1.default.white("Safety considerations:"));
+        console.log(chalk_1.default.gray(this.getSafetyInfo(confirmation.risk)));
+        console.log("");
+        if (confirmation.risk === "high") {
+            console.log(chalk_1.default.yellow("Recommendations:"));
+            console.log(chalk_1.default.gray("• Ensure you have proper authorization"));
+            console.log(chalk_1.default.gray("• Verify the target is correct"));
+            console.log(chalk_1.default.gray("• Consider testing in a safe environment first"));
+            console.log("");
+        }
+    }
+    /**
+     * Close the readline interface
+     */
+    close() {
+        this.rl.close();
+    }
+    async getUserInput() {
+        return new Promise((resolve) => {
+            const askQuestion = () => {
+                this.rl.question(chalk_1.default.gray("Proceed? [Y/n/details/cancel]: "), (answer) => {
+                    const normalized = answer.trim().toLowerCase();
+                    if (normalized === "" || normalized === "y" || normalized === "yes") {
+                        resolve({ confirmed: true, showDetails: false, cancelled: false });
+                    }
+                    else if (normalized === "n" || normalized === "no") {
+                        resolve({ confirmed: false, showDetails: false, cancelled: false });
+                    }
+                    else if (normalized === "details" || normalized === "d") {
+                        resolve({ confirmed: false, showDetails: true, cancelled: false });
+                    }
+                    else if (normalized === "cancel" || normalized === "c") {
+                        resolve({ confirmed: false, showDetails: false, cancelled: true });
+                    }
+                    else {
+                        console.log(chalk_1.default.gray("Please enter: Y, n, details, or cancel"));
+                        askQuestion();
+                    }
+                });
+            };
+            askQuestion();
+        });
+    }
+    getRiskColor(risk) {
+        switch (risk) {
+            case "high":
+                return chalk_1.default.red.bold;
+            case "medium":
+                return chalk_1.default.yellow;
+            case "low":
+                return chalk_1.default.green;
+            default:
+                return chalk_1.default.gray;
+        }
+    }
+    getDetailedDescription(action) {
+        const descriptions = {
+            "Web Scan": "This will crawl the target website and test for common vulnerabilities including XSS, SQL injection, CSRF, and security header misconfigurations. The scan sends HTTP requests to the target.",
+            "Analyze Findings": "This will use AI to analyze previously discovered vulnerabilities and provide detailed remediation recommendations.",
+            "Generate Report": "This will create a professional security report document based on scan results.",
+            "Check Environment": "This will verify your system configuration, API keys, and dependencies.",
+            "View Configuration": "This will display your current KramScan configuration settings.",
+        };
+        return (descriptions[action] ||
+            "This action will execute the requested security operation.");
+    }
+    getSafetyInfo(risk) {
+        switch (risk) {
+            case "high":
+                return "This action may trigger security systems, generate significant network traffic, or have other notable effects. Use with caution.";
+            case "medium":
+                return "This action will make network requests to external systems. Ensure you have permission to test the target.";
+            case "low":
+                return "This is a safe, read-only operation that won't modify any external systems.";
+            default:
+                return "Please review the action details carefully before proceeding.";
+        }
+    }
+}
+exports.ConfirmationHandler = ConfirmationHandler;

package/dist/agent/context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Conversation Context Manager
+ * Manages conversation history, user context, and session state
+ */
+import { ConversationMessage, AgentContext, AgentConfig } from "./types";
+export declare class ConversationContext {
+    private messages;
+    private context;
+    private config;
+    private historyFile;
+    constructor(config?: Partial<AgentConfig>);
+    private initializeContext;
+    /**
+     * Get the current agent context
+     */
+    getContext(): AgentContext;
+    /**
+     * Update the current target URL
+     */
+    setCurrentTarget(target: string): void;
+    /**
+     * Get the current target URL
+     */
+    getCurrentTarget(): string | undefined;
+    /**
+     * Store last scan results
+     */
+    setLastScanResults(results: unknown): void;
+    /**
+     * Get last scan results
+     */
+    getLastScanResults(): unknown | undefined;
+    /**
+     * Add a message to the conversation
+     */
+    addMessage(role: ConversationMessage["role"], content: string, toolCalls?: any[], toolCallResults?: any[]): ConversationMessage;
+    /**
+     * Get all conversation messages
+     */
+    getMessages(): ConversationMessage[];
+    /**
+     * Get recent messages (for AI context)
+     */
+    getRecentMessages(count?: number): ConversationMessage[];
+    /**
+     * Get the last message
+     */
+    getLastMessage(): ConversationMessage | undefined;
+    /**
+     * Get conversation summary for display
+     */
+    getSummary(): {
+        totalMessages: number;
+        sessionDuration: string;
+        currentTarget?: string;
+        hasScanResults: boolean;
+    };
+    /**
+     * Clear conversation history
+     */
+    clear(): void;
+    /**
+     * Trim history to max length
+     */
+    private trimHistory;
+    /**
+     * Persist conversation to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Load conversation from disk
+     */
+    load(): Promise<boolean>;
+    /**
+     * Format messages for AI provider (OpenAI/Anthropic format)
+     */
+    formatForAI(): Array<{
+        role: string;
+        content: string;
+    }>;
+}