Quick Start

Get started with KafkaGuard in under 5 minutes! This guide walks you through installation, running your first scan, and viewing results.

Run Your First Scan in 5 Minutes

Follow these simple steps to scan your Kafka cluster and see results in under 5 minutes.

Step 1: Install KafkaGuard (2 minutes)

Choose the installation method that works best for your environment:

Option 1: Download Pre-Built Binary (Recommended)

Linux (x86_64):

# Download latest release
curl -LO https://github.com/KafkaGuard/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz

# Extract
tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Move to system path (optional)
sudo mv kafkaguard /usr/local/bin/

# Verify installation
kafkaguard version

macOS (Intel):

curl -LO https://github.com/KafkaGuard/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_x86_64.tar.gz
tar -xzf kafkaguard_Darwin_x86_64.tar.gz
sudo mv kafkaguard /usr/local/bin/
kafkaguard version

macOS (Apple Silicon):

curl -LO https://github.com/KafkaGuard/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_arm64.tar.gz
tar -xzf kafkaguard_Darwin_arm64.tar.gz
sudo mv kafkaguard /usr/local/bin/
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard 2>/dev/null || true
kafkaguard version

Option 2: Docker (Cross-Platform)

# Pull latest image
docker pull KafkaGuard/kafkaguardmain:latest

# Verify installation
docker run --rm KafkaGuard/kafkaguardmain:latest version

For detailed installation instructions, see the Installation Guide.

Step 2: Verify Installation (30 seconds)

./kafkaguard version

Expected Output:

KafkaGuard v2.0.0
Commit: 1158328
Built: 2026-04-10T12:00:00Z
Go: go1.22.0 darwin/arm64

Step 3: Run Your First Scan (1-2 minutes)

This example uses a development cluster with no authentication. If your cluster requires authentication, see the Configuration Guide for security setup.

# Scan using baseline-dev policy (development clusters)
./kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html,json \
  --out ./reports

What This Does:

--bootstrap localhost:9092 - Connects to your Kafka broker
--policy policies/baseline-dev.yaml - Uses development policy (20 reliability/operational controls)
--format html,json - Generates both HTML and JSON reports
--out ./reports - Saves reports to ./reports directory

Expected Output:

🚀 KafkaGuard v2.0.0 - Starting scan...
✅ Connected to Kafka cluster (3 brokers detected)
🔍 Collecting broker configurations...
🔍 Collecting topic metadata...
🔍 Collecting ZooKeeper information...
📊 Evaluating 20 controls from baseline-dev policy...

Results:
  ✅ Passed: 16 controls
  ❌ Failed: 3 controls
  ⚠️  N/A: 1 control

Overall Score: 84%

📁 Reports generated:
  - ./reports/scan-20251114120530-abc123.html
  - ./reports/scan-20251114120530-abc123.json

✨ Scan completed in 9.8 seconds

Estimated Time: ~10 seconds (3-node cluster)

Step 4: View Your Report (30 seconds)

Open HTML Report:

# macOS
open ./reports/scan-*.html

# Linux
xdg-open ./reports/scan-*.html

Or view JSON report:

cat ./reports/scan-*.json | jq '.summary'

Expected JSON Summary:

{
  "score": 84,
  "total_controls": 20,
  "passed": 16,
  "failed": 3,
  "not_applicable": 1,
  "scan_duration_seconds": 9.8
}

Step 5: Understand Your Results

The scan report shows:

Overall Score - Percentage of controls that passed (0-100%)
Passed Controls - Controls that met requirements
Failed Controls - Controls that need attention
N/A Controls - Controls not applicable to your cluster

Each failed control includes:

Control ID (e.g., KG-028)
Title and description
Evidence - What was found
Remediation - How to fix it

What's Next?

Now that you've run your first scan, explore more:

Installation Guide - Detailed installation instructions for all platforms
Configuration Guide - Configure KafkaGuard for production clusters with authentication
Scanning Guide - Learn advanced scanning techniques and usage patterns
Policy Tiers - Understand the three policy tiers and choose the right one
Reports Guide - Learn about different report formats and how to use them

Common Next Steps

Scan a Production Cluster

For production clusters with authentication:

# Set credentials via environment variables
export KAFKAGUARD_SASL_USERNAME="admin"
export KAFKAGUARD_SASL_PASSWORD="secret"

# Run scan with SASL_SSL
./kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --tls-ca-cert /path/to/ca-cert.pem \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf \
  --out ./reports

See the Configuration Guide for detailed security setup.

Use Docker

# Run scan with Docker
docker run --rm \
  -v $(pwd)/policies:/policies:ro \
  -v $(pwd)/reports:/reports \
  KafkaGuard/kafkaguardmain:latest scan \
    --bootstrap kafka.example.com:9092 \
    --policy /policies/baseline-dev.yaml \
    --format html,json \
    --out /reports

Troubleshooting

Connection Failed

Problem: Error: failed to connect to Kafka broker

Solution:

Verify Kafka broker is running: telnet localhost 9092
Check bootstrap server address is correct
Ensure network connectivity to broker

Authentication Failed

Problem: Error: SASL authentication failed

Solution:

Verify credentials are correct
Check security protocol matches cluster configuration
See Configuration Guide for authentication setup

Policy File Not Found

Problem: Error: policy file not found

Solution:

Download policy files from the repository
Verify policy file path is correct
Use absolute path if relative path doesn't work

For more troubleshooting help, see the Troubleshooting Guide.

Need Help?

Installation Guide - Detailed installation instructions
Configuration Guide - Configure KafkaGuard
Contact Support - Report bugs or request features

Ready to get started? Download KafkaGuard and scan your first cluster in under 5 minutes. Download CLI | Quick Start Guide