Appearance

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:

Linux (x86_64):

bash
# Download latest release
curl -LO https://github.com/aiopsone/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):

bash
curl -LO https://github.com/aiopsone/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):

bash
curl -LO https://github.com/aiopsone/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) ​

bash
# Pull latest image
docker pull aiopsone/kafkaguard:latest

# Verify installation
docker run --rm aiopsone/kafkaguard:latest version

For detailed installation instructions, see the Installation Guide.

Step 2: Verify Installation (30 seconds) ​

bash
./kafkaguard version

Expected Output:

KafkaGuard v1.0.0
Commit: a1b2c3d
Built: 2025-11-14T12: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.

bash
# 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 v1.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:

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

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

Or view JSON report:

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

Expected JSON Summary:

json
{
  "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:

Common Next Steps ​

Scan a Production Cluster ​

For production clusters with authentication:

bash
# 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 ​

bash
# Run scan with Docker
docker run --rm \
  -v $(pwd)/policies:/policies:ro \
  -v $(pwd)/reports:/reports \
  aiopsone/kafkaguard: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 User Guide.

Need Help?

Ready to Get Started?

Book a demo to see KafkaGuard in action and learn how it can help secure your Kafka clusters.

📅 Book a Demo