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)

---

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-client-cert	string	-	Path to client certificate file (for mutual TLS)
--tls-client-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 \
  --no-color \
  --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-client-cert /path/to/client-cert.pem \
  --tls-client-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

---

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?

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

📅 Book a Demo