Documentation

KafkaGuard User Guide

Welcome to the comprehensive KafkaGuard User Guide! This guide provides in-depth documentation for installing, configuring, and using KafkaGuard to scan and audit your Apache Kafka clusters.

Target Audience

This user guide is designed for:

  • DevOps Engineers - Install and operate KafkaGuard in development and production environments
  • Security Engineers - Configure authentication, enforce security policies, and review security findings
  • Compliance Auditors - Generate compliance reports and validate against regulatory frameworks
  • Platform Teams - Maintain consistent standards across multiple Kafka clusters

Getting Started

New to KafkaGuard? Start here:

  1. Installation Guide - Install KafkaGuard on your platform (5 minutes)
  2. CLI Reference - Learn the basic commands
  3. Quick Start - Run your first scan

User Guide Sections

📦 Installation Guide

Complete installation instructions for all platforms and scenarios:

  • Binary Installation - Linux (Ubuntu, RHEL, Debian), macOS (Intel, Apple Silicon)
  • Docker Installation - Pull from Docker Hub, run scans in containers
  • Build from Source - Clone repository, build with Go 1.22+
  • Air-Gapped Installation - Create bundles, install in offline environments
  • Installation Verification - Confirm KafkaGuard is working correctly
  • Troubleshooting - Resolve common installation issues

Use this guide when: You need to install KafkaGuard on a new system or environment.

🖥️ CLI Reference

Complete command reference for all KafkaGuard CLI commands:

  • scan - Main scanning command with all flags and options
  • validate-policy - Validate policy files before use
  • list-controls - Display available security and compliance controls
  • version - Show version and build information
  • Global Flags - Flags available for all commands
  • Exit Codes - Understand exit codes for CI/CD integration
  • Common Examples - Real-world usage patterns

Use this guide when: You need detailed information about command syntax, flags, or options.

⚙️ Configuration

Comprehensive configuration management guide:

  • Configuration File Format - .kafkaguard.yaml structure and schema
  • All Configuration Options - Complete reference with types and defaults
  • Configuration Precedence - CLI flags > env vars > config file > defaults
  • Environment Variables - All supported KAFKAGUARD_* environment variables
  • Configuration File Locations - Where KafkaGuard searches for config files
  • Sensitive Data Handling - Secure credential management practices
  • Configuration Examples - Dev, production, CI/CD, and air-gapped scenarios

Use this guide when: You need to configure KafkaGuard for your environment or understand configuration options.

🔐 Security & Authentication

Enterprise security and authentication setup:

  • Security Protocols - PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL
  • SASL Authentication - PLAIN, SCRAM-SHA-256, SCRAM-SHA-512
  • SSL/TLS Encryption - Certificate validation, TLS configuration
  • Mutual TLS (mTLS) - Client certificate authentication for regulated industries
  • Security Best Practices - Production security recommendations
  • Auto-Detection - How KafkaGuard detects security protocols
  • Troubleshooting - Resolve authentication and TLS errors

Use this guide when: You need to configure security for production Kafka clusters or troubleshoot authentication issues.

🛡️ Policy Tiers

Choose the right policy tier for your environment:

  • Policy Tier Overview - baseline-dev, enterprise-default, finance-iso
  • Tier Decision Framework - Environment assessment and selection criteria
  • Tier Comparison Matrix - Control counts, focus areas, and use cases
  • Tier Selection Checklist - Step-by-step tier selection guide
  • Quick Tier Selection Commands - Ready-to-use commands for each tier
  • Tier Transition Strategies - Moving between tiers safely

🛠️ Policy Creation

Customize policies for your organization:

  • Policy Schema Reference - Complete YAML structure and field descriptions
  • Control Structure Deep Dive - Control ID conventions, severity levels, CEL expressions
  • Custom Policy Creation Workflow - Step-by-step guide to create custom policies
  • CEL Expression Guide - Advanced Common Expression Language usage
  • Validation and Testing - Policy validation and testing strategies
  • Policy Lifecycle Management - Versioning, promotion, and rollback
  • Troubleshooting Policy Issues - Debug policy creation problems
  • Advanced Policy Patterns - Complex policy scenarios and examples

📋 Usage Patterns

Common workflows and usage scenarios:

  • Dev Cluster Scanning - PLAINTEXT clusters, baseline-dev policy
  • Production Cluster Scanning - SASL_SSL clusters, enterprise-default policy
  • Compliance Audit Workflow - Custom policies, PDF reports for auditors
  • CI/CD Integration - Automated scanning in GitHub Actions, GitLab CI, Jenkins
  • Air-Gapped Scanning - Bundle creation, offline scanning workflows
  • Multi-Cluster Scanning - Scan multiple clusters with automation scripts
  • Scheduled Scanning - Cron jobs, systemd timers, Windows Task Scheduler
  • Report Management - Generate, archive, and share reports

Use this guide when: You want to implement specific workflows or integrate KafkaGuard into your existing processes.

🔧 Troubleshooting

Resolve common issues and errors:

  • Connection Errors - Connection refused, timeouts, DNS failures
  • Authentication Errors - SASL failures, TLS certificate issues
  • Policy Validation Errors - Invalid control IDs, CEL syntax errors
  • Performance Issues - Slow scans, timeouts, memory usage
  • Report Generation Errors - Permission denied, disk space issues
  • Debugging Techniques - Using debug logs, testing connectivity
  • Support Resources - GitHub Issues, community support

Use this guide when: You encounter errors or unexpected behavior and need to diagnose and fix issues.

🚀 Advanced Usage

Advanced topics for power users:

  • Custom Policy Creation - Overview and link to Policy Creation Guide (Story 9.3)
  • Report Customization - Output formats, directory management
  • Performance Tuning - Timeout configuration, memory optimization
  • Monitoring Integration - Splunk, ELK stack, custom systems
  • Ticketing Integration - Jira, ServiceNow automation
  • Scripting & Automation - Bash, Python, PowerShell examples
  • Air-Gapped Best Practices - Bundle management, updates
  • Production Security - Least privilege, audit logging, network segmentation

Use this guide when: You need to customize KafkaGuard, integrate with other systems, or implement advanced security practices.

Core Documentation

Technical Documentation

Policy Documentation

🛡️ Compliance Mappings

Framework-specific control mappings:

For Developers

KafkaGuard Developer Resources:

Community and Support

Get Help

Contribute

Document Information

Last Updated: 2025-11-15 KafkaGuard Version: 1.0.0 Documentation Version: 1.0

This user guide is maintained alongside the KafkaGuard codebase. If you find errors or have suggestions for improvement, please open an issue or submit a pull request.

Quick Navigation

I want to...Go to...
Install KafkaGuardInstallation Guide
Learn CLI commandsCLI Reference
Configure KafkaGuardConfiguration Guide
Set up SASL/SSL authenticationSecurity & Authentication
Run my first scanQuick Start
Scan a production clusterUsage Patterns - Production
Integrate with CI/CDUsage Patterns - CI/CD
Fix an errorTroubleshooting
Create a custom policyAdvanced Usage - Custom Policies
Generate PDF reportsCLI Reference - Scan Command
Understand exit codesCLI Reference - Exit Codes

Ready to get started? → Install KafkaGuard → Run your first scan → Review the reports