Scanning Guide

Learn how to scan Kafka clusters with KafkaGuard, understand scan commands and flags, and explore common usage patterns.

Table of Contents

• Scan Command Overview
• Basic Scanning
• Scan Command Flags
• Common Usage Patterns
• Exit Codes
• Next Steps

---

Scan Command Overview

The scan command is the primary command for scanning Kafka clusters and generating compliance reports.

Basic Syntax

kafkaguard scan [flags]

Required Flags

Flag	Short	Type	Description
--bootstrap	-b	string	Kafka bootstrap servers (comma-separated: broker1:9092,broker2:9092)

---

Kafka Version Support

KafkaGuard automatically detects and supports:

• Kafka 2.x – 3.8.x (ZooKeeper mode) — Full control suite including ZooKeeper health checks (KG-040–KG-049)
• Kafka 3.9.x / 4.x (KRaft mode) — Native KRaft support; ZooKeeper controls auto-skip and 4 KRaft-specific controls run instead (KG-052, KG-053, KG-054, KG-056)
• Confluent Platform — Detects CP version and validates expected Kafka version (KG-055)

No extra flags are needed. Pass --bootstrap as normal — KafkaGuard detects the cluster mode automatically:

# KRaft cluster (Kafka 4.x) — same command as always
kafkaguard scan --bootstrap kafka:9092 --policy policies/enterprise-default.yaml

# ZooKeeper cluster (Kafka 2.x/3.x) — same command
kafkaguard scan --bootstrap kafka:9092 --policy policies/enterprise-default.yaml

The detected cluster_mode (kraft or zookeeper) is included in all report formats.

---

Basic Scanning

Development Cluster Scan

# Minimal scan with PLAINTEXT protocol
kafkaguard scan --bootstrap localhost:9092

# Scan with custom policy
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html,json \
  --out ./reports

Production Cluster Scan (SASL_SSL)

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

# Better: Use environment variables for credentials
export KAFKAGUARD_SASL_USERNAME=admin
export KAFKAGUARD_SASL_PASSWORD=secret

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 /var/reports

---

Scan Command Flags

General Flags

Flag	Short	Type	Default	Description
--policy	-p	string	policies/baseline-dev.yaml	Path to policy YAML file
--out	-o	string	./reports	Output directory for reports
--format	-f	string	json	Report formats (comma-separated: json,html,pdf,csv)
--fail-on		string	high	Fail threshold: high, medium, low, none
--timeout		int	300	Scan timeout in seconds

Security Flags

Flag	Type	Default	Description
--security-protocol	string	auto-detect	Security protocol: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL
--sasl-mechanism	string	-	SASL mechanism: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512
--sasl-username	string	-	SASL username (prefer KAFKAGUARD_SASL_USERNAME env var)
--sasl-password	string	-	SASL password (prefer KAFKAGUARD_SASL_PASSWORD env var)
--tls-ca-cert	string	-	Path to CA certificate file (for server verification)
--tls-cert	string	-	Path to client certificate file (for mutual TLS)
--tls-key	string	-	Path to client private key file (for mutual TLS)
--tls-insecure-skip-verify	bool	false	Skip TLS certificate verification (testing only, NOT for production)

Performance Flags

Flag	Type	Default	Description
--parallel	bool	true	Enable parallel data collection
--max-collectors	int	6	Maximum concurrent collectors

---

Common Usage Patterns

Multi-Format Report Generation

# Generate all 4 report formats
kafkaguard scan \
  --bootstrap kafka:9092 \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf,csv \
  --out ./reports

# Reports generated:
# - reports/scan-20251115120530-abc123.json
# - reports/scan-20251115120530-abc123.html
# - reports/scan-20251115120530-abc123.pdf
# - reports/scan-20251115120530-abc123.csv

CI/CD Integration with Fail Threshold

# Fail pipeline if HIGH severity findings detected
kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --policy policies/enterprise-default.yaml \
  --format json \
  --fail-on high \
  \
  --out ./reports

# Check exit code
EXIT_CODE=$?
if [ $EXIT_CODE -eq 1 ]; then
  echo "HIGH severity findings detected!"
  exit 1
fi

Mutual TLS (mTLS) Authentication

# Scan with client certificate authentication
kafkaguard scan \
  --bootstrap kafka:9093 \
  --security-protocol SSL \
  --tls-ca-cert /path/to/ca-cert.pem \
  --tls-cert /path/to/client-cert.pem \
  --tls-key /path/to/client-key.pem \
  --policy policies/enterprise-default.yaml \
  --out ./reports

Custom Timeout for Large Clusters

# Increase timeout for large clusters (1000+ topics)
kafkaguard scan \
  --bootstrap kafka:9092 \
  --policy policies/enterprise-default.yaml \
  --timeout 600 \
  --out ./reports

Development Cluster Scanning

# Quick scan with minimal configuration
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html \
  --out ./reports

Production Compliance Scan

# Full production scan with SASL_SSL
export KAFKAGUARD_SASL_USERNAME=admin
export KAFKAGUARD_SASL_PASSWORD=secret

kafkaguard scan \
  --bootstrap kafka1.prod.example.com:9095,kafka2.prod.example.com:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --tls-ca-cert /etc/kafkaguard/certs/ca.pem \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf \
  --fail-on high \
  --timeout 600 \
  --out /var/reports/kafkaguard

---

Exit Codes

KafkaGuard uses standard exit codes for scripting and CI/CD integration.

Exit Code Reference

Exit Code	Meaning	Description	Use Case
0	Success	Scan completed successfully, no findings above --fail-on threshold	Continue pipeline, deploy changes
1	Findings	Scan completed, findings exceed --fail-on threshold	Block deployment, review findings
2	Error	Scan failed due to errors (connection failure, invalid config, policy error)	Fix configuration, check connectivity

Exit Code Examples

CI/CD Pipeline Integration

#!/bin/bash
set -e

echo "Running KafkaGuard scan..."
kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --policy policies/enterprise-default.yaml \
  --format json \
  --fail-on high \
  --out ./reports

EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "✅ Scan passed - no critical findings"
  exit 0
elif [ $EXIT_CODE -eq 1 ]; then
  echo "⚠️  Scan found policy violations exceeding threshold"

  # Parse and display findings
  cat reports/scan-*.json | jq '.findings[] | select(.status == "FAILED" and .severity == "HIGH")'

  # Block deployment
  exit 1
else
  echo "❌ Scan failed with errors"
  exit 2
fi

---

Alerting After Scans

KafkaGuard can fire a webhook alert after every scan when the compliance score drops below a configurable threshold. Supports Slack, Microsoft Teams, and generic HTTP endpoints.

Quick Start

# Alert on Slack when score drops below 80%
kafkaguard scan \
  --bootstrap kafka:9092 \
  --policy policies/enterprise-default.yaml \
  --alert-slack-webhook https://hooks.slack.com/services/T.../B.../xxx \
  --alert-threshold 80

Alert Triggers

Scenario	Behaviour
--alert-threshold 0 (default)	Alert fires after every scan when a webhook is set
--alert-threshold 80	Alert fires only when score drops below 80%
Score ≥ threshold	Scan completes normally, no alert sent
Alert delivery fails	Logged as a warning — scan exit code is unaffected

Persisting Alert Config

Add alert settings to .kafkaguard.yaml so you don't repeat them on every run:

alert:
  slack_webhook: "https://hooks.slack.com/services/..."
  threshold: 80
  dashboard_url: "https://kafkaguard.mycompany.com"

Then scan without repeating the flags:

kafkaguard scan --bootstrap kafka:9092 --policy policies/enterprise-default.yaml

Slack Message Format

The Slack alert includes cluster name, score, threshold, pass/fail/NA counts, and the top 5 failing controls sorted by severity. A "View Dashboard" button is added when --dashboard-url is set.

Viewing Trends After Scanning

Once you have multiple scans uploaded to the on-prem platform, view historical trends at:

• /dashboard/trends?cluster=<id> — Compliance score timeline with period selector (7d / 30d / 90d / 1y) and regression highlighting
• /dashboard/compare — Fleet grid comparing all clusters with current score, delta, and sparkline

---

Next Steps

• Configuration Guide - Learn about configuration files and environment variables
• Reports Guide - Understand report formats and how to use them
• Policy Tiers - Learn about different policy tiers
• Advanced Usage - Explore automation and integration patterns

---

Need Help?

• Configuration Guide - Configure KafkaGuard for your environment
• Reports Guide - Learn about report formats
• GitHub Issues - 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