KafkaGuard
Get started
FeaturesDocsEnterprisePricingBlogToolsGet started

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
  • Kafka 4.x / KRaft support — Automatic detection of KRaft mode clusters; ZK-specific controls auto-skip, KRaft controls auto-activate (KG-052–KG-054)

🛠️ 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

Policy Documentation

Compliance Mappings

Compliance mappings are embedded in each policy file. KafkaGuard controls include PCI-DSS 4.0, SOC 2 Type II, and ISO 27001:2013 requirement IDs — visible in every scan report under the Compliance Mapping tab.

API Reference

  • API Reference - REST API endpoints, authentication, and examples

Support

Get Help

Document Information

Last Updated: 2026-04-25 KafkaGuard Version: 2.3.0 Documentation Version: 2.3

This user guide is maintained alongside the KafkaGuard codebase. If you find errors or have suggestions for improvement, contact Enterprise Support.

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