kafkacode 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,26 +1,31 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented in this file.
 
-## [1.0.0] - 2024-09-22
+## [1.3.0] - 2026-06-05
 
 ### Added
-- Initial release of KafkaCode Privacy Scanner
-- Pattern-based detection for secrets, API keys, and sensitive data
-- AI-powered contextual analysis using Grok LLM
-- Support for multiple programming languages (Python, JavaScript, TypeScript, Java, Go, Ruby, PHP)
-- Beautiful console reporting with severity levels
-- Privacy grading system (A+ to F)
-- CLI interface with scan command
-- API key obfuscation for commercial distribution
-- Gitignore pattern support
-- Comprehensive test suite
+- Bring-your-own-key AI analysis: set `KAFKACODE_API_KEY` to call an
+  OpenAI-compatible provider directly (defaults to Groq). `KAFKACODE_API_URL`
+  and `KAFKACODE_MODEL` override the endpoint and model.
+- `--badge` flag that prints a shareable privacy-grade badge for your README.
+- `--no-ai` flag to force pattern-only scanning.
 
-### Features
-- Detects AWS keys, Stripe keys, private keys
-- Identifies PII like emails, phone numbers, IP addresses
-- High entropy string detection for potential secrets
-- Context-aware privacy vulnerability analysis
-- Detailed suggestions for remediation
-- Verbose logging option
-- Exit codes for CI/CD integration
+### Changed
+- Open-sourced under the MIT License.
+- AI analysis is now opt-in. With no key configured, scanning is pattern-only
+  and fully offline — no code leaves the machine.
+
+### Removed
+- Silent "mock" analysis fallback; on an API error the snippet is now skipped
+  instead of fabricating findings.
+
+## [1.2.0] - 2025-10-05
+
+### Added
+- Pattern-based detection for hardcoded secrets, API keys, and PII.
+- AI-powered contextual privacy analysis.
+- Support for Python, JavaScript, TypeScript, Java, Go, Ruby, and PHP.
+- Console reporting with severity levels and an A+ to F privacy grade.
+- `.gitignore`-aware file scanning.
+- Non-zero exit codes for CI/CD integration.

package/README.md

@@ -1,98 +1,217 @@
-# KafkaCode Privacy Scanner
-
 <div align="center">
-  <h3>by <a href="https://kafkalabs.com">KafkaLabs</a></h3>
-  <p>🔐 <strong>Shift-left privacy and compliance scanner for source code</strong></p>
-  <p>
-    <a href="https://kafkalabs.com/kafka-code">Website</a> •
-    <a href="https://github.com/nikhil-kapu/KafkacodeFnpm">GitHub</a> •
-    <a href="https://www.npmjs.com/package/kafkacode">npm</a>
-  </p>
+
+<img src="docs/logo4.png" width="104" alt="KafkaCode logo" />
+
+# KafkaCode
+
+**Catch PII leaks, hardcoded secrets, and compliance risks before they ship.**
+
+An AI-powered privacy &amp; compliance scanner for your source code. One command,
+a clear **A+ → F privacy grade**, and CI-ready exit codes. Runs in seconds.
+
+[![npm version](https://img.shields.io/npm/v/kafkacode.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/kafkacode)
+[![npm downloads](https://img.shields.io/npm/dm/kafkacode.svg?color=cb3837)](https://www.npmjs.com/package/kafkacode)
+[![CI](https://img.shields.io/github/actions/workflow/status/nikhil-kapu/kafkacode/ci.yml?branch=main&label=CI&logo=github)](https://github.com/nikhil-kapu/kafkacode/actions)
+[![license](https://img.shields.io/npm/l/kafkacode.svg?color=blue)](LICENSE)
+[![node](https://img.shields.io/node/v/kafkacode.svg?color=339933&logo=node.js)](package.json)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+[Quickstart](#-quickstart) · [Features](#-features) · [Example](#-example-output) · [CI/CD](#-cicd-integration) · [How it works](#-how-it-works) · [Contributing](#-contributing)
+
 </div>
 
 ---
 
-KafkaCode is an AI-powered privacy scanner by **KafkaLabs** that helps developers identify potential privacy issues, PII leaks, and compliance violations in their source code before they reach production.
+## Why KafkaCode?
+
+Most scanners stop at *"you leaked an AWS key."* KafkaCode goes further — it grades how
+your code handles **personal data**, flags **GDPR/CCPA** risks, and catches hardcoded
+secrets, with an optional **AI pass** for the context that regex alone can't see.
 
-## Features
+You get one number a whole team understands — a **privacy grade from A+ to F** — plus a
+non-zero exit code that fails the build when something sensitive slips in.
+
+```bash
+npx kafkacode scan .
+```
 
-- 🔍 **Pattern-based Detection**: Identifies hardcoded secrets, API keys, and sensitive data
-- 🤖 **AI-powered Analysis**: Uses advanced LLM analysis for contextual privacy issues
-- ⚡ **Fast & Efficient**: Scans entire codebases in seconds
-- 🎯 **Multiple File Types**: Supports Python, JavaScript, TypeScript, Java, Go, Ruby, PHP
-- 📊 **Detailed Reports**: Beautiful console reports with severity levels
-- 🚀 **CI/CD Ready**: Easy integration with build pipelines
+No install. No signup. No config.
 
-## Installation
+## ⚡ Quickstart
 
 ```bash
+# Run it once, anywhere (no install)
+npx kafkacode scan .
+
+# Or install globally
 npm install -g kafkacode
+kafkacode scan ./src --verbose
 ```
 
-Or using npx (no installation required):
-```bash
-npx kafkacode scan /path/to/your/project
+## ✨ Features
+
+- 🔑 **Secret detection** — AWS & Stripe keys, private keys, high-entropy strings
+- 🕵️ **PII detection** — emails, phone numbers, IP addresses
+- 🤖 **AI-powered analysis** — contextual privacy issues a regex would miss
+- 🎓 **Privacy grade** — a single, shareable **A+ → F** score
+- 🏷️ **Grade badge** — drop your score into your README (`--badge`)
+- ⚡ **Fast & offline** — pattern scanning needs no network
+- 🌐 **7 languages** — Python, JavaScript, TypeScript, Java, Go, Ruby, PHP
+- 🚀 **CI/CD ready** — clean exit codes + a one-line GitHub Action
+
+## 📊 Example output
+
+```text
+🎯 PRIVACY SCAN REPORT
+════════════════════════════════════════════════════════════════
+
+📊 SCAN SUMMARY
+   📁 Directory:      ./src
+   📄 Files Scanned:  18
+   🔍 Total Issues:   4
+   🏆 Privacy Grade:  🔴 F
+
+   🚨 Critical: 1    🔥 High: 1    ⚠️  Medium: 2    🔵 Low: 0
+
+🚨 CRITICAL
+  ┌─ AWS Access Key ID detected
+  │  📍 src/config.js:12
+  │  💡 Move credentials to environment variables or a secrets manager.
+  └─
+
+⚠️  MEDIUM
+  ┌─ Email address detected (PII)
+  │  📍 src/users.js:47
+  │  💡 Avoid hardcoding personal data; load it at runtime.
+  └─
 ```
 
-## Usage
+## 🏷️ Privacy grade & badge
+
+KafkaCode distills every scan into one grade:
+
+| Grade | Meaning |
+| :---: | ------- |
+| 🟢 **A+ / A / A-** | Excellent — no or only low-severity issues |
+| 🟡 **B+ / B / B-** | Good — a few medium-severity issues |
+| 🟠 **C+ / C / C-** | Needs attention — high-severity issues present |
+| 🔴 **D / F** | Critical privacy/secret exposure |
+
+Show it off in your own README:
 
-**Basic Scan:**
 ```bash
-kafkacode scan /path/to/your/project
+kafkacode scan . --badge
 ```
 
-**Verbose Output:**
-```bash
-kafkacode scan /path/to/your/project --verbose
+```text
+🏷️  Privacy Grade Badge — paste into your README:
+
+    ![Privacy Grade: A+](https://img.shields.io/badge/Privacy%20Grade-A%2B-brightgreen)
 ```
 
-## What it detects
+→ ![Privacy Grade: A+](https://img.shields.io/badge/Privacy%20Grade-A%2B-brightgreen)
+
+## 🚀 CI/CD integration
 
-- **Critical Issues**: AWS keys, Stripe keys, Private keys
-- **High Severity**: Sensitive keywords in assignment context
-- **Medium Severity**: Email addresses, Phone numbers, High entropy strings
-- **Low Severity**: IP addresses, URLs
+### GitHub Action
 
-## Privacy Grade
+```yaml
+# .github/workflows/privacy.yml
+name: Privacy Scan
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: nikhil-kapu/kafkacode@v1
+        with:
+          path: ./src
+```
 
-KafkaCode assigns a privacy grade (A+ to F) based on the severity and number of issues found:
+### Any CI / pre-commit
 
-- **A+/A/A-**: Excellent privacy practices
-- **B+/B/B-**: Good privacy practices with minor issues
-- **C+/C/C-**: Moderate privacy issues that should be addressed
-- **D**: Multiple high-severity privacy issues
-- **F**: Critical privacy vulnerabilities detected
+```bash
+# Exits non-zero when issues are found, failing the build
+npx kafkacode scan ./src
+```
 
-## Example Output
+## 🔍 What it detects
+
+| Severity | Examples |
+| -------- | -------- |
+| 🚨 **Critical** | AWS keys, Stripe live keys, private keys |
+| 🔥 **High** | `password=`, `api_key=`, `token=` and other secrets in assignments |
+| ⚠️ **Medium** | Emails, phone numbers, high-entropy strings |
+| 🔵 **Low** | IP addresses |
+
+## 🧠 How it works
 
 ```
-🎯 PRIVACY SCAN REPORT
-═══════════════════════════════════════
+ your code ─▶ FileScanner ─▶ ┌─ PatternScanner  (regex, fully offline)
+                             └─ LLMAnalyzer     (optional AI context)
+                                      │
+                                      ▼
+                          ReportGenerator ─▶ grade + findings + exit code
+```
 
-📊 SCAN SUMMARY
-📁 Directory: ./src
-⏰ Timestamp: 2024-01-15 10:30:45
-📄 Files Scanned: 25
-🔍 Total Issues: 3
-🏆 Privacy Grade: 🟡B-
+Pattern-based detection runs entirely on your machine with no network calls. The
+optional AI layer adds contextual findings for the cases static rules can't catch.
+
+## 🤖 AI mode (optional, bring-your-own-key)
+
+Pattern scanning works out of the box with **no setup and no network calls**. To add
+AI-powered contextual findings, bring your own API key — KafkaCode calls an
+OpenAI-compatible chat API directly, defaulting to [Groq](https://console.groq.com/keys)
+(which has a free tier):
+
+```bash
+export KAFKACODE_API_KEY=your_key_here
+kafkacode scan ./src
 ```
 
-## License
+| Variable | Default | Purpose |
+| -------- | ------- | ------- |
+| `KAFKACODE_API_KEY` | _(unset)_ | Your provider API key — **enables AI mode** |
+| `KAFKACODE_API_URL` | `https://api.groq.com/openai/v1` | OpenAI-compatible base URL (Groq, OpenAI, OpenRouter, local models…) |
+| `KAFKACODE_MODEL`   | `llama-3.1-8b-instant` | Model name |
 
-MIT License - Copyright (c) 2025 KafkaLabs
+Without a key, KafkaCode runs **pattern-only and never sends your code anywhere**.
+Pass `--no-ai` to force pattern-only even when a key is set.
 
-See [LICENSE](LICENSE) file for details.
+## 🆚 How it compares
 
-## About KafkaLabs
+|                              | KafkaCode | gitleaks / trufflehog | semgrep |
+| ---------------------------- | :-------: | :-------------------: | :-----: |
+| Hardcoded secrets            |     ✅    |   ✅ (deep, git log)  |   ➖    |
+| PII / personal-data findings |     ✅    |          ➖           |   ➖    |
+| Privacy grade (A+ → F)       |     ✅    |          ➖           |   ➖    |
+| AI contextual analysis       |     ✅    |          ➖           |   ➖    |
+| Zero-config, one command     |     ✅    |          ✅           |   ➖    |
 
-KafkaCode is built by [KafkaLabs](https://kafkalabs.com), helping developers build privacy-first applications.
+KafkaCode focuses on **privacy and developer-friendly grading** — it complements
+deep secret scanners rather than replacing them.
 
-- 🌐 **Website**: [kafkalabs.com/kafka-code](https://kafkalabs.com/kafka-code)
-- 📧 **Contact**: contact@kafkalabs.com
-- 💬 **Issues**: [GitHub Issues](https://github.com/nikhil-kapu/KafkacodeFnpm/issues)
+## 🗺️ Roadmap
 
----
+- [x] **Bring-your-own-key AI** — call Groq / OpenAI-compatible providers directly
+- [ ] `--json` and **SARIF** output (GitHub Security tab integration)
+- [ ] Config file &amp; `.kafkacodeignore`
+- [ ] Baseline file to adopt on existing codebases
+- [ ] More file types (`.env`, YAML, Terraform, Dockerfiles)
+
+Ideas and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## 🤝 Contributing
+
+Contributions of all kinds are welcome — bug reports, new detection patterns, and docs.
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), and please report security issues per our
+[Security Policy](SECURITY.md).
+
+## 📄 License
+
+[MIT](LICENSE) © KafkaLabs
 
 <div align="center">
-  Made with ❤️ by <a href="https://kafkalabs.com">KafkaLabs</a>
-</div>
+<sub>🛡️ Keep your code secure, keep your users safe.</sub>
+</div>

package/dist/AnalysisEngine.js

@@ -10,6 +10,16 @@ class AnalysisEngine {
         this.llmAnalyzer.verbose = verbose;
     }
 
+    /** Force pattern-only scanning, even if an API key is configured. */
+    disableAi() {
+        this.llmAnalyzer.disabled = true;
+    }
+
+    /** Whether AI-powered analysis will run for this scan. */
+    aiEnabled() {
+        return this.llmAnalyzer.isEnabled();
+    }
+
     async analyzeFile(filePath) {
         if (this.verbose) {
             console.log(`Analyzing: ${filePath}`);

package/dist/LLMAnalyzer.js

@@ -1,8 +1,28 @@
 const https = require('https');
 
+/**
+ * LLMAnalyzer performs optional AI-powered contextual analysis.
+ *
+ * It is "bring your own key": the user supplies an API key and KafkaCode calls
+ * an OpenAI-compatible chat-completions endpoint directly (defaulting to Groq).
+ * When no key (and no self-hosted backend) is configured, AI analysis is simply
+ * skipped — pattern-based scanning still runs, and no code leaves the machine.
+ */
 class LLMAnalyzer {
     constructor() {
-        this.backendEndpoint = process.env.KAFKACODE_BACKEND_ENDPOINT || 'https://adorable-motivation-production.up.railway.app';
+        // Bring-your-own-key: direct, OpenAI-compatible provider call.
+        this.apiKey = process.env.KAFKACODE_API_KEY || '';
+        this.apiUrl = process.env.KAFKACODE_API_URL || 'https://api.groq.com/openai/v1';
+        this.model = process.env.KAFKACODE_MODEL || 'llama-3.1-8b-instant';
+
+        // Advanced: a self-hosted backend exposing POST /api/analyze. If set,
+        // it takes precedence over a direct provider call.
+        this.backendEndpoint = process.env.KAFKACODE_BACKEND_ENDPOINT || '';
+
+        // Delay between snippet requests, to stay within free-tier rate limits.
+        this.rateLimitMs = parseInt(process.env.KAFKACODE_RATE_LIMIT_MS || '250', 10);
+
+        this.disabled = false;
         this.verbose = false;
         this.interestKeywords = new Set([
             'api', 'db', 'database', 'user', 'password', 'save', 'fetch', 'send', 'log',
@@ -11,6 +31,11 @@ class LLMAnalyzer {
         ]);
     }
 
+    /** AI analysis is available only when a key or a backend endpoint is configured. */
+    isEnabled() {
+        return !this.disabled && Boolean(this.apiKey || this.backendEndpoint);
+    }
+
     _createSnippetPrompt(codeSnippet, filePath, startLine) {
         return `SYSTEM: You are an automated privacy and compliance analysis engine. Your task is to review the following CODE SNIPPET and identify potential privacy vulnerabilities based ONLY on the provided code. The snippet is from a larger file. Do not infer functionality outside of this snippet. Your analysis must focus on how the code handles data that could be considered sensitive or PII.
 
@@ -67,7 +92,6 @@ ${codeSnippet}`;
         const mergedRanges = [];
         for (const [start, end] of ranges) {
             if (mergedRanges.length > 0 && start <= mergedRanges[mergedRanges.length - 1][1] + 10) {
-                // Extend previous range
                 const lastRange = mergedRanges[mergedRanges.length - 1];
                 mergedRanges[mergedRanges.length - 1] = [lastRange[0], Math.max(lastRange[1], end)];
             } else {
@@ -78,27 +102,50 @@ ${codeSnippet}`;
         return mergedRanges;
     }
 
-    async callGrokApi(codeSnippet, filePath, startLine) {
-        try {
-            return await this._callBackendApi(codeSnippet, filePath, startLine);
-        } catch (error) {
-            if (this.verbose) {
-                console.log(`    ❌ LLM call failed, using mock: ${error.message}`);
-            }
-            return this._mockSnippetResponse(codeSnippet, filePath, startLine);
+    /** Route a snippet to either the self-hosted backend or the direct provider. */
+    async _analyzeSnippet(codeSnippet, filePath, startLine) {
+        if (this.backendEndpoint) {
+            return this._callBackendApi(codeSnippet, filePath, startLine);
         }
+        return this._callProviderApi(codeSnippet, filePath, startLine);
     }
 
-    async _callBackendApi(codeSnippet, filePath, startLine) {
+    /** Call an OpenAI-compatible chat-completions endpoint directly (BYOK). */
+    async _callProviderApi(codeSnippet, filePath, startLine) {
+        const prompt = this._createSnippetPrompt(codeSnippet, filePath, startLine);
         const payload = JSON.stringify({
-            codeSnippet,
-            filePath,
-            startLine
+            model: this.model,
+            messages: [{ role: 'user', content: prompt }],
+            temperature: 0,
+            max_tokens: 800
         });
 
-        const url = new URL(this.backendEndpoint);
-        url.pathname = '/api/analyze';
+        const base = this.apiUrl.replace(/\/+$/, '');
+        const url = new URL(`${base}/chat/completions`);
+        const options = {
+            hostname: url.hostname,
+            port: url.port || 443,
+            path: url.pathname + url.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Length': Buffer.byteLength(payload)
+            },
+            timeout: 20000
+        };
+
+        const raw = await this._request(options, payload);
+        const result = JSON.parse(raw);
+        const content = result.choices && result.choices[0] && result.choices[0].message.content;
+        return this._parseVulnerabilities(content || '');
+    }
 
+    /** Call a self-hosted KafkaCode backend (POST /api/analyze). */
+    async _callBackendApi(codeSnippet, filePath, startLine) {
+        const payload = JSON.stringify({ codeSnippet, filePath, startLine });
+        const base = this.backendEndpoint.replace(/\/+$/, '');
+        const url = new URL(`${base}/api/analyze`);
         const options = {
             hostname: url.hostname,
             port: url.port || 443,
@@ -108,68 +155,57 @@ ${codeSnippet}`;
                 'Content-Type': 'application/json',
                 'Content-Length': Buffer.byteLength(payload)
             },
-            timeout: 12000 // 12 second timeout for CLI request
+            timeout: 20000
         };
 
+        const raw = await this._request(options, payload);
+        const result = JSON.parse(raw);
+        const content = result.data && result.data.choices && result.data.choices[0].message.content;
+        return this._parseVulnerabilities(content || '');
+    }
+
+    /** Parse the model's text response into a vulnerabilities array, defensively. */
+    _parseVulnerabilities(content) {
+        try {
+            const parsed = JSON.parse(content);
+            return Array.isArray(parsed.vulnerabilities) ? parsed.vulnerabilities : [];
+        } catch (err) {
+            // Some models wrap JSON in prose or fences — extract the JSON object.
+            const start = content.indexOf('{');
+            const end = content.lastIndexOf('}') + 1;
+            if (start !== -1 && end > start) {
+                try {
+                    const parsed = JSON.parse(content.substring(start, end));
+                    return Array.isArray(parsed.vulnerabilities) ? parsed.vulnerabilities : [];
+                } catch (_) {
+                    return [];
+                }
+            }
+            return [];
+        }
+    }
+
+    /** Promise wrapper around https.request with status + timeout handling. */
+    _request(options, payload) {
         return new Promise((resolve, reject) => {
             const req = https.request(options, (res) => {
                 let data = '';
-
-                res.on('data', (chunk) => {
-                    data += chunk;
-                });
-
+                res.on('data', (chunk) => { data += chunk; });
                 res.on('end', () => {
-                    try {
-                        if (res.statusCode === 429) {
-                            const errorData = JSON.parse(data);
-                            throw new Error(`Rate limit exceeded: ${errorData.message}`);
-                        }
-
-                        if (res.statusCode !== 200) {
-                            throw new Error(`HTTP ${res.statusCode}: ${data}`);
-                        }
-
-                        const result = JSON.parse(data);
-                        const content = result.data.choices[0].message.content;
-
-                        try {
-                            const parsedResponse = JSON.parse(content);
-                            if (this.verbose) {
-                                console.log(`    ✅ LLM returned ${parsedResponse.vulnerabilities?.length || 0} vulnerabilities`);
-                                if (result.rateLimitRemaining !== undefined) {
-                                    console.log(`    📊 Rate limit remaining: ${result.rateLimitRemaining}`);
-                                }
-                            }
-                            parsedResponse.__source = 'llm';
-                            resolve(parsedResponse);
-                        } catch (jsonError) {
-                            const jsonStart = content.indexOf('{');
-                            const jsonEnd = content.lastIndexOf('}') + 1;
-                            if (jsonStart !== -1 && jsonEnd > jsonStart) {
-                                const parsed = JSON.parse(content.substring(jsonStart, jsonEnd));
-                                if (this.verbose) {
-                                    console.log(`    ✅ LLM returned ${parsed.vulnerabilities?.length || 0} vulnerabilities (extracted JSON)`);
-                                }
-                                parsed.__source = 'llm';
-                                resolve(parsed);
-                            } else {
-                                resolve({ vulnerabilities: [] });
-                            }
-                        }
-                    } catch (error) {
-                        reject(error);
+                    if (res.statusCode === 429) {
+                        return reject(new Error('Rate limit exceeded (HTTP 429)'));
+                    }
+                    if (res.statusCode < 200 || res.statusCode >= 300) {
+                        return reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 200)}`));
                     }
+                    resolve(data);
                 });
             });
 
-            req.on('error', (error) => {
-                reject(error);
-            });
-
+            req.on('error', reject);
             req.on('timeout', () => {
                 req.destroy();
-                reject(new Error('Backend API request timeout'));
+                reject(new Error('LLM request timed out'));
             });
 
             req.write(payload);
@@ -177,87 +213,56 @@ ${codeSnippet}`;
         });
     }
 
-
-    _mockSnippetResponse(codeSnippet, filePath, startLine) {
-        const vulnerabilities = [];
-        const lines = codeSnippet.split('\n');
-
-        // Simple heuristic-based mock analysis
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            const lineLower = line.toLowerCase();
-            const actualLineNum = startLine + i;
-
-            // Look for logging of potentially sensitive data
-            if (lineLower.includes('log') && ['email', 'user', 'password', 'token'].some(term => lineLower.includes(term))) {
-                vulnerabilities.push({
-                    line_number: actualLineNum,
-                    severity: 'Medium',
-                    description: 'Potential logging of sensitive user data detected.',
-                    suggestion: 'Consider logging only non-sensitive identifiers or hashing sensitive data before logging.'
-                });
-            }
-
-            // Look for insecure data transmission
-            if (lineLower.includes('http://') && ['api', 'send', 'post', 'request'].some(term => lineLower.includes(term))) {
-                vulnerabilities.push({
-                    line_number: actualLineNum,
-                    severity: 'High',
-                    description: 'Insecure HTTP transmission of potentially sensitive data.',
-                    suggestion: 'Use HTTPS instead of HTTP for all data transmission.'
-                });
-            }
+    async analyzeFile(filePath, content, patternFindings = []) {
+        // AI analysis is opt-in: with no key/backend configured, skip entirely.
+        if (!this.isEnabled()) {
+            return [];
         }
 
-        return { vulnerabilities, __source: 'mock' };
-    }
-
-    async analyzeFile(filePath, content, patternFindings = []) {
         const lines = content.split('\n');
         const areasOfInterest = this._identifyAreasOfInterest(content, patternFindings);
         const findings = [];
 
         if (this.verbose && areasOfInterest.length > 0) {
-            console.log(`  Found ${areasOfInterest.length} areas of interest for LLM analysis`);
+            console.log(`  Found ${areasOfInterest.length} areas of interest for AI analysis`);
         }
 
-        // Analyze each area of interest
         for (const [startLine, endLine] of areasOfInterest) {
-            // Extract snippet
-            const snippetLines = lines.slice(startLine - 1, endLine);
-            const snippet = snippetLines.join('\n');
+            const snippet = lines.slice(startLine - 1, endLine).join('\n');
 
             // Skip very small snippets
             if (snippet.trim().length < 50) {
                 continue;
             }
 
+            let vulnerabilities;
             try {
-                // Call API with rate limiting
-                const grokResponse = await this.callGrokApi(snippet, filePath, startLine);
-
-                // Add delay to prevent rate limiting from free tier
-                await new Promise(resolve => setTimeout(resolve, 1000));
-
-                // Process findings
-                for (const vuln of grokResponse.vulnerabilities || []) {
-                    const finding = {
-                        file_path: filePath,
-                        line_number: vuln.line_number || startLine,
-                        severity: vuln.severity || 'Medium',
-                        finding_type: 'Context-Based Issue',
-                        description: vuln.description || 'Privacy vulnerability detected',
-                        code_snippet: this._getCodeSnippet(content, vuln.line_number || startLine),
-                        suggestion: vuln.suggestion || 'Review and address the identified issue.',
-                        source: grokResponse.__source || 'unknown'
-                    };
-                    findings.push(finding);
-                }
-
+                vulnerabilities = await this._analyzeSnippet(snippet, filePath, startLine);
             } catch (error) {
-                // Continue with other snippets if one fails
+                // Skip this snippet on error — never fabricate findings.
+                if (this.verbose) {
+                    console.log(`    ⚠️  AI analysis skipped for ${filePath}:${startLine} — ${error.message}`);
+                }
                 continue;
             }
+
+            for (const vuln of vulnerabilities) {
+                findings.push({
+                    file_path: filePath,
+                    line_number: vuln.line_number || startLine,
+                    severity: vuln.severity || 'Medium',
+                    finding_type: 'Context-Based Issue',
+                    description: vuln.description || 'Privacy vulnerability detected',
+                    code_snippet: this._getCodeSnippet(content, vuln.line_number || startLine),
+                    suggestion: vuln.suggestion || 'Review and address the identified issue.',
+                    source: 'llm'
+                });
+            }
+
+            // Gentle pacing to respect provider rate limits.
+            if (this.rateLimitMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, this.rateLimitMs));
+            }
         }
 
         // Remove duplicates based on line number and description
@@ -283,4 +288,4 @@ ${codeSnippet}`;
     }
 }
 
-module.exports = LLMAnalyzer;
+module.exports = LLMAnalyzer;

package/dist/ReportGenerator.js

@@ -47,6 +47,25 @@ class ReportGenerator {
         }
     }
 
+    // Public: return the privacy grade (A+ .. F) for a set of findings.
+    getGrade(findings) {
+        return this._calculateGrade(findings);
+    }
+
+    // Public: build a shields.io privacy-grade badge for embedding in a README.
+    getBadge(findings) {
+        const grade = this._calculateGrade(findings);
+        const colorMap = {
+            'A+': 'brightgreen', 'A': 'brightgreen', 'A-': 'green',
+            'B+': 'yellowgreen', 'B': 'yellowgreen', 'B-': 'yellow',
+            'C+': 'yellow', 'C': 'orange', 'C-': 'orange',
+            'D': 'red', 'F': 'red'
+        };
+        const color = colorMap[grade] || 'lightgrey';
+        const url = `https://img.shields.io/badge/Privacy%20Grade-${encodeURIComponent(grade)}-${color}`;
+        return { grade, url, markdown: `![Privacy Grade: ${grade}](${url})` };
+    }
+
     _groupFindingsBySeverity(findings) {
         const groups = {};
         this.severityOrder.forEach(severity => {
@@ -132,7 +151,7 @@ class ReportGenerator {
             '│                                                                             │',
             '│ 🎯 Detection Methods:                                                       │',
             `│   • Pattern-based: ${patternCount} issues                                      │`,
-            `│   • AI-powered: ${llmCount} issues (Grok 4 Fast)                               │`,
+            `│   • AI-powered: ${llmCount} issues                                            │`,
             '│                                                                             │',
             '│ 📈 Severity Breakdown:                                                      │',
             `│   🚨 Critical: ${severityCounts['Critical'].toString().padEnd(10)} 🔥 High: ${severityCounts['High'].toString().padEnd(14)} │`,
@@ -209,16 +228,12 @@ class ReportGenerator {
 
         // Footer
         reportLines.push(
-            '╔═══════════════════════════════════════════════════════════════════════════════╗',
-            '║                              🚀 GET STARTED                                  ║',
-            '║                                                                               ║',
-            '║  📚 Documentation: https://kafkacode.dev/docs                                 ║',
-            '║  🐙 GitHub: https://github.com/kafkacode/privacy-scanner                     ║',
-            '║  💬 Support: https://discord.gg/kafkacode                                    ║',
-            '║  🐦 Follow: @KafkaCodeDev                                                     ║',
-            '║                                                                               ║',
-            '║              🛡️ Keep your code secure, keep your users safe! 🛡️               ║',
-            '╚═══════════════════════════════════════════════════════════════════════════════╝',
+            '',
+            '─'.repeat(80),
+            '🚀 KafkaCode · AI-powered privacy & compliance scanner',
+            '📚 Docs & issues: https://github.com/nikhil-kapu/kafkacode',
+            '🛡️  Keep your code secure, keep your users safe!',
+            '─'.repeat(80),
             ''
         );
 

package/dist/cli.js

@@ -12,13 +12,15 @@ const program = new Command();
 program
     .name('kafkacode')
     .description('KafkaCode - Privacy and Compliance Scanner')
-    .version('1.2.0');
+    .version('1.3.0');
 
 program
     .command('scan')
     .description('Scan a directory for privacy issues')
     .argument('<directory>', 'Path to the source code directory to scan')
     .option('-v, --verbose', 'Print verbose progress updates during the scan')
+    .option('-b, --badge', 'Print a copy-paste privacy-grade badge for your README')
+    .option('--no-ai', 'Disable AI-powered analysis (run pattern scan only)')
     .action(async (directory, options) => {
         await runScan(directory, options);
     });
@@ -40,6 +42,9 @@ async function runScan(directory, options = {}) {
         // Initialize components
         const fileScanner = new FileScanner(directory);
         const analysisEngine = new AnalysisEngine(verbose);
+        if (options.ai === false) {
+            analysisEngine.disableAi();
+        }
         const reportGenerator = new ReportGenerator();
 
         // Scan for files
@@ -67,6 +72,18 @@ async function runScan(directory, options = {}) {
         const report = reportGenerator.generateReport(directory, findings, files.length);
         console.log(report);
 
+        // Hint that AI analysis is available when it wasn't used.
+        if (options.ai !== false && !analysisEngine.aiEnabled()) {
+            console.log('💡 Tip: set KAFKACODE_API_KEY to enable AI-powered contextual analysis. See the README.\n');
+        }
+
+        // Optionally print a copy-paste privacy-grade badge for the user's README
+        if (options.badge) {
+            const badge = reportGenerator.getBadge(findings);
+            console.log('🏷️  Privacy Grade Badge — paste into your README:\n');
+            console.log(`    ${badge.markdown}\n`);
+        }
+
         // Return appropriate exit code
         process.exit(findings.length > 0 ? 1 : 0);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kafkacode",
-  "version": "1.2.0",
-  "description": "AI-powered privacy and compliance scanner by KafkaLabs - identify PII leaks, secrets, and compliance violations",
+  "version": "1.3.0",
+  "description": "AI-powered privacy and compliance scanner - find PII leaks, hardcoded secrets, and compliance violations in your source code",
   "main": "dist/index.js",
   "bin": {
     "kafkacode": "dist/cli.js"
@@ -27,8 +27,7 @@
     "shift-left",
     "cli-tool",
     "security-scanner",
-    "vulnerability-scanner",
-    "kafkalabs"
+    "vulnerability-scanner"
   ],
   "author": "KafkaLabs <contact@kafkalabs.com>",
   "license": "MIT",
@@ -48,10 +47,10 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/nikhil-kapu/KafkacodeFnpm.git"
+    "url": "git+https://github.com/nikhil-kapu/kafkacode.git"
   },
-  "homepage": "https://kafkalabs.com/kafka-code",
+  "homepage": "https://github.com/nikhil-kapu/kafkacode#readme",
   "bugs": {
-    "url": "https://github.com/nikhil-kapu/KafkacodeFnpm/issues"
+    "url": "https://github.com/nikhil-kapu/kafkacode/issues"
   }
-}
+}