Skip to main content

​
Introduction

While KafkaCode is primarily a CLI tool, it’s built with modular components that can be used programmatically in your Node.js applications.

​
Architecture

KafkaCode consists of five main components:

FileScanner

Discovers and filters source code files

PatternScanner

Regex-based pattern detection

LLMAnalyzer

AI-powered contextual analysis

AnalysisEngine

Orchestrates the scanning process

ReportGenerator

Generates formatted reports

​
Basic Usage

const { AnalysisEngine, FileScanner, ReportGenerator } = require('kafkacode');

async function scanProject(directory) {
  // Initialize components
  const fileScanner = new FileScanner(directory);
  const analysisEngine = new AnalysisEngine();
  const reportGenerator = new ReportGenerator();

  // Scan for files
  const files = fileScanner.scanFiles();

  // Analyze files
  const findings = await analysisEngine.analyzeFiles(files);

  // Generate report
  const report = reportGenerator.generateReport(directory, findings, files.length);

  console.log(report);
  return findings;
}

// Usage
scanProject('./src')
  .then(findings => {
    console.log(`Found ${findings.length} issues`);
    process.exit(findings.length > 0 ? 1 : 0);
  })
  .catch(error => {
    console.error('Scan failed:', error);
    process.exit(1);
  });

​
Installation

npm install kafkacode

​
Import Syntax

  • CommonJS
  • ES Modules
const FileScanner = require('kafkacode/dist/FileScanner');
const AnalysisEngine = require('kafkacode/dist/AnalysisEngine');
const ReportGenerator = require('kafkacode/dist/ReportGenerator');
const PatternScanner = require('kafkacode/dist/PatternScanner');
const LLMAnalyzer = require('kafkacode/dist/LLMAnalyzer');

​
Data Structures

​
Finding Object

Each finding has this structure: 
interface Finding {
  filePath: string;       // Path to the file
  lineNumber: number;     // Line number where issue was found
  severity: 'critical' | 'high' | 'medium' | 'low';
  type: string;          // Type of issue (e.g., 'AWS Access Key')
  description: string;   // Human-readable description
  codeSnippet: string;   // The problematic code
  recommendation: string; // How to fix it
}
Example: 
{
  filePath: 'src/config.js',
  lineNumber: 12,
  severity: 'critical',
  type: 'AWS Access Key',
  description: 'AWS Access Key detected',
  codeSnippet: 'aws_access_key_id = "AKIAIOSFODNN7EXAMPLE"',
  recommendation: 'Move to environment variables'
}

​
Quick Examples

​
Example 1: Simple Scan

const { AnalysisEngine, FileScanner } = require('kafkacode');

async function quickScan() {
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  console.log(`Scanned ${files.length} files`);
  console.log(`Found ${findings.length} issues`);

  return findings;
}

quickScan();

​
Example 2: Custom Filtering

const { AnalysisEngine, FileScanner } = require('kafkacode');

async function scanWithFilter() {
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  // Filter for critical issues only
  const critical = findings.filter(f => f.severity === 'critical');

  console.log(`Critical issues: ${critical.length}`);
  critical.forEach(finding => {
    console.log(`${finding.filePath}:${finding.lineNumber} - ${finding.type}`);
  });

  return critical;
}

scanWithFilter();

​
Example 3: Verbose Mode

const { AnalysisEngine, FileScanner } = require('kafkacode');

async function verboseScan() {
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine(true); // Enable verbose

  console.log('Starting scan...');

  const files = scanner.scanFiles();
  console.log(`Found ${files.length} files`);

  const findings = await engine.analyzeFiles(files);

  return findings;
}

verboseScan();

​
Example 4: Single File Analysis

const { AnalysisEngine } = require('kafkacode');

async function analyzeFile(filePath) {
  const engine = new AnalysisEngine();
  const findings = await engine.analyzeFile(filePath);

  console.log(`Issues in ${filePath}: ${findings.length}`);

  return findings;
}

analyzeFile('./src/config.js');

​
Example 5: Custom Report

const { AnalysisEngine, FileScanner } = require('kafkacode');

async function customReport() {
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  // Group by severity
  const grouped = findings.reduce((acc, finding) => {
    acc[finding.severity] = acc[finding.severity] || [];
    acc[finding.severity].push(finding);
    return acc;
  }, {});

  // Custom output
  console.log('=== Custom Privacy Report ===');
  for (const [severity, items] of Object.entries(grouped)) {
    console.log(`\n${severity.toUpperCase()}: ${items.length}`);
    items.forEach(item => {
      console.log(`  - ${item.filePath}:${item.lineNumber}`);
    });
  }

  return grouped;
}

customReport();

​
Use Cases

Integrate KafkaCode into your build tools or scripts:
const { AnalysisEngine, FileScanner } = require('kafkacode');

async function buildWithScan() {
  // Scan before build
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  if (findings.length > 0) {
    console.error('Privacy issues detected. Build aborted.');
    process.exit(1);
  }

  // Proceed with build
  console.log('Privacy scan passed. Building...');
  // ... build logic
}
Build custom tools on top of KafkaCode:
const { PatternScanner } = require('kafkacode');

class CustomScanner extends PatternScanner {
  constructor() {
    super();
    // Add custom patterns
    this.patterns.customSecret = /MY_CUSTOM_PATTERN/g;
  }
}

const scanner = new CustomScanner();
Create a scanning API service:
const express = require('express');
const { AnalysisEngine, FileScanner } = require('kafkacode');

const app = express();

app.post('/scan', async (req, res) => {
  const { directory } = req.body;

  const scanner = new FileScanner(directory);
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  res.json({
    filesScanned: files.length,
    issuesFound: findings.length,
    findings
  });
});

app.listen(3000);
Track privacy metrics over time:
const { AnalysisEngine, FileScanner } = require('kafkacode');

async function collectMetrics() {
  const scanner = new FileScanner('./src');
  const engine = new AnalysisEngine();

  const files = scanner.scanFiles();
  const findings = await engine.analyzeFiles(files);

  // Calculate metrics
  const metrics = {
    timestamp: new Date(),
    filesScanned: files.length,
    totalIssues: findings.length,
    critical: findings.filter(f => f.severity === 'critical').length,
    high: findings.filter(f => f.severity === 'high').length,
    medium: findings.filter(f => f.severity === 'medium').length,
    low: findings.filter(f => f.severity === 'low').length
  };

  // Store in database or send to metrics service
  await saveMetrics(metrics);

  return metrics;
}

​
Component Overview

ComponentPurposeKey Methods
FileScannerFile discoveryscanFiles()
PatternScannerRegex detectionscanContent()
LLMAnalyzerAI analysisanalyzeFile()
AnalysisEngineOrchestrationanalyzeFile(), analyzeFiles()
ReportGeneratorReport formattinggenerateReport()

​
Next Steps

FileScanner API

Learn about file discovery

AnalysisEngine API

Explore the analysis engine

PatternScanner API

Understand pattern detection

Examples

See practical examples