Documentation

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

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

Basic Syntax

kafkaguard scan [flags]

Required Flags

FlagShortTypeDescription
--bootstrap-bstringKafka 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

FlagShortTypeDefaultDescription
--policy-pstringpolicies/baseline-dev.yamlPath to policy YAML file
--out-ostring./reportsOutput directory for reports
--format-fstringjsonReport formats (comma-separated: json,html,pdf,csv)
--fail-onstringhighFail threshold: high, medium, low, none
--timeoutint300Scan timeout in seconds

Security Flags

FlagTypeDefaultDescription
--security-protocolstringauto-detectSecurity protocol: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL
--sasl-mechanismstring-SASL mechanism: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512
--sasl-usernamestring-SASL username (prefer KAFKAGUARD_SASL_USERNAME env var)
--sasl-passwordstring-SASL password (prefer KAFKAGUARD_SASL_PASSWORD env var)
--tls-ca-certstring-Path to CA certificate file (for server verification)
--tls-client-certstring-Path to client certificate file (for mutual TLS)
--tls-client-keystring-Path to client private key file (for mutual TLS)
--tls-insecure-skip-verifyboolfalseSkip TLS certificate verification (testing only, NOT for production)

Performance Flags

FlagTypeDefaultDescription
--parallelbooltrueEnable parallel data collection
--max-collectorsint6Maximum 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 CodeMeaningDescriptionUse Case
0SuccessScan completed successfully, no findings above --fail-on thresholdContinue pipeline, deploy changes
1FindingsScan completed, findings exceed --fail-on thresholdBlock deployment, review findings
2ErrorScan 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

Need Help?

<BookDemoCallout />