kramscan

v0.2.0

Published

5 days ago

KramScan CLI — AI-powered web app security testing

0High
0Medium
0Low

security cli scanner vulnerability pentesting web-security analysis

🔬 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, modular plugin architecture, and an interactive AI agent.

🌐 NPM Package · 📖 Documentation · 🐞 Report Bug

🚀 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, leverages Generative AI (OpenAI, Gemini, Anthropic) for analysis, and features a modular plugin system for extensibility. It delivers actionable, human-readable insights alongside raw vulnerability data—all in seconds.

✨ Key Features

| Feature | Description | | :--- | :--- | | 🔍 Automated Vulnerability Engine | Detects XSS, SQL Injection, CSRF, insecure headers, and more using Puppeteer-powered crawling. | | 🔌 Modular Plugin System | Extensible architecture for custom vulnerability detection plugins. Built-in plugins for common vulnerabilities. | | 🤖 Interactive AI Agent | A conversational security assistant with Autonomous Verification skills to confirm findings live. | | 🧠 Multi-Provider AI Analysis | Supports OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, and more for results auditing. | | 📝 AI Executive Summaries | Automatically generates business-oriented summaries for Word, JSON, and TXT reports. | | 📊 Event-Driven Feedback | Real-time progress updates with dynamic spinners and live vulnerability alerts during scanning. | | 📄 Professional Reporting | Generates detailed PDF, DOCX, TXT, and JSON reports with remediation steps and error tracking. | | 🌐 Headless Browser Testing | Renders modern SPAs (Single Page Applications) to find vulnerabilities in dynamic content. | | ⚡ Smarter User Flow | Revamped interactive menu and post-scan "Golden Path" prompts for a guided experience. | | 🛡️ Error Resilience | Robust configuration defaults and graceful recovery if individual URLs or plugins fail. |

🏗️ Architecture & Workflow

graph LR
    A[User Command] --> B{CLI Controller};
    B --> C[Scanner Module<br/>Puppeteer / Plugin System];
    B --> D[AI Agent<br/>NLP Processing];
    
    C --> E[Plugin Manager<br/>XSS / SQLi / Headers / CSRF];
    E --> F[Vulnerability Detection];
    C --> G[Event System<br/>Progress / Results];
    
    F & G --> H[AI Analysis Engine<br/>LLM Provider];
    
    H --> I[Risk Assessment<br/>Confidence Scoring];
    I --> J[Report Generator<br/>PDF / DOCX / JSON / TXT];
    J --> K((Final Output<br/>+ Error Report));

Plugin Architecture

KramScan now features a modular plugin system that makes extending vulnerability detection effortless:

src/plugins/
├── types.ts              # Base interfaces and types
├── PluginManager.ts      # Plugin orchestration
├── index.ts             # Plugin exports
└── vulnerabilities/     # Built-in plugins
    ├── XSSPlugin.ts
    ├── SQLInjectionPlugin.ts
    ├── SecurityHeadersPlugin.ts
    ├── SensitiveDataPlugin.ts
    └── CSRFPlugin.ts

Creating a custom plugin:

import { BaseVulnerabilityPlugin, PluginContext } from 'kramscan/plugins';

export class MyCustomPlugin extends BaseVulnerabilityPlugin {
  readonly name = "Custom Detector";
  readonly type = "custom";
  readonly description = "Detects custom vulnerability";
  
  async testParameter(context: PluginContext, param: string, value: string) {
    // Your detection logic here
    if (/* vulnerability found */) {
      return this.success(this.createVulnerability(
        "Custom Vulnerability",
        "Description...",
        context.url,
        "high",
        "Evidence...",
        "Remediation..."
      ));
    }
    return this.failure();
  }
}

🧪 Tech Stack

🧠 Supported AI Providers

Switch providers instantly with kramscan onboard or by editing ~/.kramscan/config.json.

API Key Environment Variables

You can provide API keys via environment variables (useful for CI/CD) instead of saving them locally:

Smart Environment Detection

KramScan automatically detects API keys in your environment variables. During kramscan onboard, the tool will identify and pre-configure providers like OpenAI, Anthropic, and Gemini if their keys are found in your session.

AI-Powered Context-Aware Payloads

The scanning engine now utilizes AI to generate payloads tailored to the specific context of your application, significantly increasing detection rates against filtered inputs and complex WAFs.

Autonomous Finding Verification

The kramscan agent can now independently verify reported vulnerabilities using non-destructive, context-aware payloads to differentiate between theoretical findings and exploitable risks.

🚀 Quick Start

1. Installation

Install KramScan globally using npm:

npm install -g kramscan

2. First-Time Setup

Initialize the configuration wizard to set up your AI provider and API keys:

kramscan onboard

3. Run a Scan

Execute a full security scan on a target URL:

kramscan scan https://example.com

📖 Usage & Commands

Scan Profiles and Limits

KramScan supports profiles for quick tuning:

kramscan scan https://example.com --profile quick
kramscan scan https://example.com --profile balanced
kramscan scan https://example.com --profile deep

You can also control crawl limits and URL scope:

kramscan scan https://example.com --max-pages 30 --max-links-per-page 50
kramscan scan https://example.com --exclude "logout|signout"
kramscan scan https://example.com --include "^https://example\.com/docs"

Automatic PDF Report After Scan

After each scan, KramScan automatically generates a PDF report (no separate command required).

The file is saved to:

JSON: ~/.kramscan/scans/scan-<timestamp>.json
PDF: ~/.kramscan/reports/scanreport_<hostname>_<timestamp>.pdf

You can disable it with:

kramscan scan https://example.com --no-pdf

Error Tracking and Recovery

KramScan now features comprehensive error handling:

Continue on Failure: Scan continues even if individual URLs fail to load
Plugin Error Isolation: If one vulnerability plugin fails, others continue working
Error Reports: PDF reports include a "⚠️ Scan Errors & Skipped Items" section
CLI Feedback: Real-time error messages during scanning

Event-Driven Progress Feedback

Watch your scan progress in real-time:

🔍 Starting Security Scan
──────────────────────────────────────────────────

✔ Initializing scanner...
⠴ Crawling: https://example.com (5/30)
⚠️ Found high vulnerability: Reflected Cross-Site Scripting (XSS)
⠴ Continuing scan (1 vulns found)...
⠴ Testing forms on https://example.com/login (3 forms)...
✔ Scan complete!

Scan History

Every scan is indexed in ~/.kramscan/scans/index.json.

kramscan scans list -n 10
kramscan scans latest

AI Diagnostics

List models and test your configured provider/model:

kramscan ai models -n 10
kramscan ai test

Example Agent Session

$ 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?

🗺️ Roadmap

[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
[x] Plugin system for custom scan modules ✅
[x] PDF report generation ✅
[x] Event-driven progress feedback ✅
[x] Error resilience and recovery ✅
[x] Zod schema validation ✅
[x] AI Executive Summaries ✅
[x] Autonomous Verification Agent ✅
[x] Smarter Interactive Flows ✅
[ ] CI/CD integration (GitHub Actions, GitLab CI)
[ ] Web-based dashboard UI
[ ] SARIF export format
[ ] OWASP ZAP integration

🔒 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.
Error Tracking: Failed scan attempts are logged locally for debugging but never transmitted.

👤 Author

Akram Shaikh

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.