kramscan 0.3.0 → 0.4.0

package/README.md

@@ -3,298 +3,160 @@
 
   <h3 align="center">AI-Powered Web Application Security Testing CLI</h3>
 
-  <br />
-
+  [![CI](https://img.shields.io/github/actions/workflow/status/shaikhakramshakil/kramscan/ci.yml?branch=main&style=for-the-badge&logo=github-actions&logoColor=white&label=CI)](https://github.com/shaikhakramshakil/kramscan/actions)
   [![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, modular plugin architecture, 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>
 
 ---
 
-<br />
+KramScan is a command-line security auditing tool that combines automated vulnerability scanning with multi-provider AI analysis. It orchestrates headless browser crawling, runs a modular plugin system against discovered pages, and passes findings through a generative AI layer (OpenAI, Gemini, Anthropic, and others) to produce actionable, context-aware reports.
 
-## 🚀 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.
-
-<br />
+[NPM Package](https://www.npmjs.com/package/kramscan) · [Documentation](#usage--commands) · [Report Bug](https://github.com/shaikhakramshakil/kramscan/issues) · [Request Feature](https://github.com/shaikhakramshakil/kramscan/issues)
 
 ---
 
-<br />
-
-## ✨ Key Features
-| Feature | Description |
-| :--- | :--- |
-| 🔍 **Automated Vulnerability Engine** | Detects XSS, SQL Injection, CSRF, insecure headers, CORS misconfigs, open redirects, and more. |
-| 🔌 **10 Built-in Security Plugins** | CORS, debug endpoints, directory traversal, cookie auditing, open redirects, sensitive data, and more. |
-| 🛠️ **Dev Mode (Watch Scanner)** | Watch your localhost for file changes and auto re-scan with diff reports (new vs resolved vulns). |
-| 🚧 **CI/CD Security Gate** | `kramscan gate` exits with code 1 if vulnerabilities exceed your threshold. Plug into any pipeline. |
-| 🤖 **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** | 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. |
-
-<br />
+## Features
+
+- **Automated vulnerability detection** — XSS, SQL injection, CSRF, insecure headers, CORS misconfigurations, open redirects, and more.
+- **10 built-in security plugins** — CORS, debug endpoints, directory traversal, cookie auditing, open redirects, sensitive data exposure, and others. Easily extensible.
+- **Dev mode (watch scanner)** — Watches your localhost for file changes and auto re-scans, showing a diff of new vs. resolved findings.
+- **CI/CD security gate** — `kramscan gate` exits with code 1 when vulnerabilities exceed a configurable threshold.
+- **Interactive AI agent** — Conversational security assistant with autonomous verification capabilities to confirm findings live.
+- **Multi-provider AI analysis** — Supports OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, Groq, and Kimi.
+- **AI executive summaries** — Generates business-oriented summaries included in Word, JSON, and TXT reports.
+- **Professional reporting** — PDF, DOCX, Markdown, TXT, and JSON output with remediation steps and error tracking.
+- **Headless browser testing** — Renders SPAs via Puppeteer to find vulnerabilities in dynamically generated content.
+- **Real-time feedback** — Event-driven progress with live spinners and vulnerability alerts during scanning.
+- **Error resilience** — Graceful recovery when individual URLs or plugins fail; errors are logged but never halt a scan.
 
 ---
 
-<br />
+## Quick Start
 
-## 🏗️ Architecture & Workflow
+### Installation
 
-```mermaid
-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));
+```bash
+npm install -g kramscan
 ```
 
-<br />
-
-### Plugin Architecture
+Or run directly without installing:
 
-KramScan is built on 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                # Cross-Site Scripting
-    ├── SQLInjectionPlugin.ts       # SQL Injection
-    ├── SecurityHeadersPlugin.ts    # Missing security headers
-    ├── SensitiveDataPlugin.ts      # Exposed secrets & API keys
-    ├── CSRFPlugin.ts               # Cross-Site Request Forgery
-    ├── CORSAnalyzerPlugin.ts       # CORS misconfiguration
-    ├── DebugEndpointPlugin.ts      # Exposed debug/dev endpoints
-    ├── DirectoryTraversalPlugin.ts # Path traversal / LFI
-    ├── CookieSecurityPlugin.ts     # Insecure cookie flags
-    └── OpenRedirectPlugin.ts       # Open redirect detection
+```bash
+npx kramscan scan https://example.com
 ```
 
-**Creating a custom plugin:**
-
-```typescript
-import { BaseVulnerabilityPlugin, PluginContext } from 'kramscan/plugins';
+### First-Time Setup
 
-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();
-  }
-}
+```bash
+kramscan onboard
 ```
 
-<br />
-
----
-
-<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 |
-| **Schema Validation** | Zod |
-| **Reporting** | Docx, Puppeteer (PDF), Chalk |
-| **Package Manager** | NPM / Yarn / PNPM |
-
-</div>
-
-<br />
-
----
-
-<br />
-
-## 🧠 Supported AI Providers
-
-| 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` |
-| **Mistral** | `@mistralai/mistralai` | `mistral-large-latest` |
-| **OpenRouter** | OpenAI-compatible | `anthropic/claude-3.5-sonnet` |
-| **Kimi** | OpenAI-compatible | `moonshot-v1-8k` |
-| **Groq** | OpenAI-compatible | `llama-3.1-8b-instant` |
-
-> 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:
+This runs the configuration wizard to set up your AI provider and API keys. KramScan auto-detects keys already present in your environment variables.
 
-| Provider | Env Var |
-| :--- | :--- |
-| OpenAI | `OPENAI_API_KEY` |
-| Anthropic | `ANTHROPIC_API_KEY` |
-| Gemini | `GEMINI_API_KEY` |
-| Mistral | `MISTRAL_API_KEY` |
-| OpenRouter | `OPENROUTER_API_KEY` |
-| Kimi | `KIMI_API_KEY` |
-| Groq | `GROQ_API_KEY` |
-
-### 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 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` independently verifies reported vulnerabilities using non-destructive, context-aware payloads to differentiate between theoretical findings and exploitable risks.
-
-<br />
-
----
-
-<br />
-
-## 🚀 Quick Start
-
-### 1. Installation
-Install KramScan globally using npm:
+### Run a Scan
 
 ```bash
-npm install -g kramscan
+kramscan scan https://example.com
 ```
 
-### 2. First-Time Setup
-Initialize the configuration wizard to set up your AI provider and API keys:
+### View Results
 
 ```bash
-kramscan onboard
+kramscan scans list     # List recent scans
+kramscan scans latest   # View the latest scan
 ```
 
-### 3. Run a Scan
-Execute a full security scan on a target URL:
+---
 
-```bash
-kramscan scan https://example.com
+## Usage & Commands
+
+```
+kramscan                      Interactive dashboard menu
+kramscan scan <url>           Full vulnerability scan with post-scan prompts
+kramscan dev [url]            Watch-mode localhost scanner with diff reports
+kramscan gate <url>           CI/CD security gate (exits 1 on threshold breach)
+kramscan agent                AI security assistant with autonomous verification
+kramscan analyze              AI-powered analysis of scan results
+kramscan report               Generate reports with optional AI executive summaries
+kramscan onboard              Setup wizard with environment key detection
+kramscan doctor               Verify environment health and dependencies
+kramscan config               View and edit configuration
+kramscan scans                List and inspect recent scans
+kramscan init                 Generate a .kramscanrc config for this project
+kramscan ai                   AI helpers (model listing, connectivity test)
 ```
 
-<br />
+### Project Configuration
 
----
+Run `kramscan init` in your project root to generate a `.kramscanrc` file with team-shareable defaults:
 
-<br />
-
-## 📖 Usage & Commands
+```bash
+kramscan init          # interactive setup
+kramscan init -y       # generate with defaults
+kramscan init --force  # overwrite an existing .kramscanrc
+```
 
-| Command | Description |
-| :--- | :--- |
-| `kramscan` | Launch the interactive dashboard menu with smart argument prompting. |
-| `kramscan scan <url>` | Run a comprehensive vulnerability scan with post-scan prompts. |
-| `kramscan dev [url]` | Watch-mode localhost scanner with diff reports and desktop notifications. |
-| `kramscan gate <url>` | CI/CD security quality gate — exits with code 1 on threshold breach. |
-| `kramscan agent` | Start the AI security assistant with autonomous verification skills. |
-| `kramscan analyze` | AI-powered analysis with proactive onboarding redirection. |
-| `kramscan report` | Generate professional reports with optional AI executive summaries. |
-| `kramscan onboard` | Smart setup wizard with environment key detection. |
-| `kramscan doctor` | Verify environment health and check for Docker dependencies. |
-| `kramscan config` | View and edit current configuration with robust schema defaults. |
-| `kramscan scans` | List and inspect recent scans from the persistent index. |
-| `kramscan ai` | AI helpers (model listing and connectivity test). |
+The generated file looks like this:
+
+```json
+{
+  "scan": {
+    "defaultProfile": "balanced",
+    "defaultTimeout": 30000,
+    "strictScope": true,
+    "exclude": ["logout", "signout", "delete"]
+  },
+  "report": {
+    "defaultFormat": "markdown",
+    "companyName": "Your Company"
+  },
+  "gate": {
+    "failOn": "high",
+    "maxVulns": 0
+  },
+  "plugins": {
+    "disabled": []
+  }
+}
+```
 
-<br />
+Project-level settings override the global config (`~/.kramscan/config.json`). API keys are never stored in `.kramscanrc` — use `kramscan onboard` or environment variables for credentials. Commit the file to version control so your team shares the same scan settings.
 
-### 🛠️ Dev Mode — Localhost Watch Scanner
+### Dev Mode
 
-Scan your local dev server continuously. KramScan watches for file changes and **auto re-scans**, showing a diff of new vs. resolved vulnerabilities:
+Scan your local dev server continuously. KramScan watches for file changes and auto re-scans, showing a diff of new vs. resolved vulnerabilities:
 
 ```bash
-# Watch-mode with port shorthand
 kramscan dev --port 3000
-
-# Full URL with notifications
 kramscan dev http://localhost:3000 --watch-dir ./src --notify
-
-# Single scan (no watching)
 kramscan dev http://localhost:8080 --no-watch --fail-on high
 ```
 
-**How it works:**
-1. Probes your server until it's ready (auto-detects Express, Next.js, Django, etc.)
-2. Runs an initial security scan
-3. Watches `--watch-dir` for file changes (debounced)
-4. Re-scans and shows only **new** and **resolved** vulnerabilities
+It probes your server until it's ready (auto-detects Express, Next.js, Django, etc.), runs an initial scan, then watches the specified directory for changes and re-scans on each update.
 
-### 🚧 CI/CD Security Gate
+### CI/CD Security Gate
 
-Block deployments with vulnerabilities above your threshold:
+Block deployments when vulnerabilities exceed your threshold:
 
 ```bash
-# Fail if any high+ vulnerabilities found
 kramscan gate http://localhost:3000 --fail-on high
-
-# JSON output for pipeline processing
 kramscan gate $APP_URL --fail-on medium --json
-
-# Allow up to 3 low-severity findings
 kramscan gate http://staging.example.com --fail-on low --max-vulns 3
 ```
 
-**Pipeline example (GitHub Actions):**
+GitHub Actions example:
+
 ```yaml
 - name: Security Gate
   run: npx kramscan gate http://localhost:3000 --fail-on high
 ```
 
-<br />
-
-### Scan Profiles and Limits
-KramScan supports profiles for quick tuning:
+### Scan Profiles
 
 ```bash
 kramscan scan https://example.com --profile quick
@@ -302,7 +164,7 @@ kramscan scan https://example.com --profile balanced
 kramscan scan https://example.com --profile deep
 ```
 
-You can also control crawl limits and URL scope:
+Control crawl limits and URL scope:
 
 ```bash
 kramscan scan https://example.com --max-pages 30 --max-links-per-page 50
@@ -310,45 +172,18 @@ 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).
+### Automatic PDF Reports
 
-The file is saved to:
+After each scan, a PDF report is generated automatically:
 
 - JSON: `~/.kramscan/scans/scan-<timestamp>.json`
 - PDF: `~/.kramscan/reports/scanreport_<hostname>_<timestamp>.pdf`
 
-You can disable it with:
-
-```bash
-kramscan scan https://example.com --no-pdf
-```
-
-### Error Tracking and Recovery
-KramScan 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!
-```
+Disable with `--no-pdf`.
 
 ### Scan History
-Every scan is indexed in `~/.kramscan/scans/index.json`.
+
+Every scan is indexed in `~/.kramscan/scans/index.json`:
 
 ```bash
 kramscan scans list -n 10
@@ -356,64 +191,151 @@ kramscan scans latest
 ```
 
 ### AI Diagnostics
-List models and test your configured provider/model:
 
 ```bash
 kramscan ai models -n 10
 kramscan ai test
 ```
 
-### 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?
+---
+
+## Architecture
+
+```mermaid
+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));
 ```
 
-<br />
+### Plugin System
+
+KramScan's detection layer is built on a modular plugin architecture:
+
+```
+src/plugins/
+├── types.ts                        # Base interfaces and types
+├── PluginManager.ts                # Plugin orchestration
+├── index.ts                        # Plugin exports
+└── vulnerabilities/
+    ├── XSSPlugin.ts
+    ├── SQLInjectionPlugin.ts
+    ├── SecurityHeadersPlugin.ts
+    ├── SensitiveDataPlugin.ts
+    ├── CSRFPlugin.ts
+    ├── CORSAnalyzerPlugin.ts
+    ├── DebugEndpointPlugin.ts
+    ├── DirectoryTraversalPlugin.ts
+    ├── CookieSecurityPlugin.ts
+    └── OpenRedirectPlugin.ts
+```
+
+To add a custom plugin:
+
+```typescript
+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();
+  }
+}
+```
 
 ---
 
+## Supported AI Providers
 
+KramScan supports the following AI providers out of the box. Switch providers with `kramscan onboard` or by editing `~/.kramscan/config.json`.
 
-## 🔒 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.
+- **OpenAI** — `gpt-4` (env: `OPENAI_API_KEY`)
+- **Anthropic** — `claude-3-5-sonnet-20241022` (env: `ANTHROPIC_API_KEY`)
+- **Google Gemini** — `gemini-2.0-flash` (env: `GEMINI_API_KEY`)
+- **Mistral** — `mistral-large-latest` (env: `MISTRAL_API_KEY`)
+- **OpenRouter** — `anthropic/claude-3.5-sonnet` (env: `OPENROUTER_API_KEY`)
+- **Kimi** — `moonshot-v1-8k` (env: `KIMI_API_KEY`)
+- **Groq** — `llama-3.1-8b-instant` (env: `GROQ_API_KEY`)
 
-<br />
+API keys can be provided via environment variables (useful for CI/CD) or saved locally during onboarding. KramScan auto-detects keys present in your environment.
+
+The scanning engine can also use AI to generate context-aware payloads, improving detection rates against filtered inputs and WAFs. The `kramscan agent` independently verifies reported vulnerabilities using non-destructive payloads to separate theoretical findings from exploitable risks.
 
 ---
 
-<br />
+## Tech Stack
 
-## 👤 Author
-<div align="center">
+- **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
+- **Schema Validation:** Zod
+- **Reporting:** Docx, Puppeteer (PDF), Chalk
+- **Testing:** Jest, ts-jest
+- **CI/CD:** GitHub Actions (lint, build, test on Node 18/20/22, security audit)
 
-**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/)
+## Security & Privacy
 
-</div>
+- All scanning logic runs locally on your machine.
+- API keys are stored in your local home directory and are never sent to our servers.
+- Scan data is sent only to your chosen AI provider for analysis and is not stored by KramScan.
+- Failed scan attempts are logged locally for debugging but never transmitted.
+
+---
 
-<br />
+## Contributing
+
+```bash
+git clone https://github.com/shaikhakramshakil/kramscan.git
+cd kramscan
+npm install
+npm run build
+npm test
+```
+
+Before submitting a PR:
+
+1. Run `npm run lint` — ensure zero ESLint errors.
+2. Run `npm test` — ensure all tests pass.
+3. Add tests for new features when possible.
 
 ---
 
-<br />
+## Author
 
-## 📄 License
-This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
+**Akram Shaikh**
 
-<div align="center">
-  <sub>Made with ❤️ by Akram Shaikh</sub>
-</div>
+[![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/)
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

package/dist/agent/skills/generate-report.js

@@ -199,7 +199,7 @@ class GenerateReportSkill {
         if (!docx) {
             throw new Error("DOCX generation requires the 'docx' package. Please install it: npm install docx");
         }
-        const { Document, Paragraph, TextRun, HeadingLevel, Table, TableCell, TableRow, WidthType, BorderStyle, } = docx;
+        const { Document, Paragraph, TextRun, HeadingLevel, } = docx;
         const findings = scanData.findings || [];
         const analysisFinding = includeAnalysis
             ? findings.find((f) => f.skillId === "analyze_findings")

package/dist/agent/skills/health-check.d.ts

@@ -12,11 +12,11 @@ export declare class HealthCheckSkill implements AgentSkill {
     riskLevel: "low";
     estimatedDuration: number;
     toolDefinition: ToolDefinition;
-    validateParameters(params: Record<string, unknown>): {
+    validateParameters(_params: Record<string, unknown>): {
         valid: boolean;
         errors: string[];
     };
-    execute(params: Record<string, unknown>, context: AgentContext): Promise<SkillResult>;
+    execute(params: Record<string, unknown>, _context: AgentContext): Promise<SkillResult>;
     private checkNodeVersion;
     private checkConfiguration;
     private checkAIProvider;