From 73354f09c3a62f49606ae225a7780c5b246ec95e Mon Sep 17 00:00:00 2001 From: "Caro R. Pereira" Date: Thu, 2 Apr 2026 15:20:32 -0300 Subject: [PATCH] feat(security): add kafka secure-mode smoke test and acceptance checklist --- docs/operations/README.md | 2 + .../kafka-sasl-ssl-acceptance-checklist.md | 34 +++++++++ docs/operations/kafka-sasl-ssl-quickstart.md | 6 ++ scripts/kafka-secure-smoke.sh | 72 +++++++++++++++++++ 4 files changed, 114 insertions(+) create mode 100644 docs/operations/kafka-sasl-ssl-acceptance-checklist.md create mode 100755 scripts/kafka-secure-smoke.sh diff --git a/docs/operations/README.md b/docs/operations/README.md index c51470d..0293adf 100644 --- a/docs/operations/README.md +++ b/docs/operations/README.md @@ -24,6 +24,7 @@ It is intended for developers, operators, and support engineers who need repeata - `monitor-operations-runbook.md` - day-to-day operational procedures, smoke checks, and incident-oriented troubleshooting - `kafka-sasl-ssl-quickstart.md` - secure Kafka enablement (TLS/SASL) with bootstrap scripts - `kafka-sasl-ssl-troubleshooting.md` - failure patterns and diagnostics for Kafka secure mode +- `kafka-sasl-ssl-acceptance-checklist.md` - release checklist to close secure Kafka rollout ### Scope @@ -56,6 +57,7 @@ Esta pensada para desarrolladores, operadores y personal de soporte que necesite - `monitor-operations-runbook.md` - procedimientos operativos diarios, smoke checks y troubleshooting orientado a incidentes - `kafka-sasl-ssl-quickstart.md` - habilitacion de Kafka seguro (TLS/SASL) con scripts de bootstrap - `kafka-sasl-ssl-troubleshooting.md` - guia de diagnostico para fallas de Kafka en modo seguro +- `kafka-sasl-ssl-acceptance-checklist.md` - checklist de aceptacion para cierre operativo de Kafka seguro ### Alcance diff --git a/docs/operations/kafka-sasl-ssl-acceptance-checklist.md b/docs/operations/kafka-sasl-ssl-acceptance-checklist.md new file mode 100644 index 0000000..74e303e --- /dev/null +++ b/docs/operations/kafka-sasl-ssl-acceptance-checklist.md @@ -0,0 +1,34 @@ +# Kafka SASL/SSL Acceptance Checklist + +Use this checklist to declare Hallazgo #12 operationally closed. + +## Preconditions +- [ ] `.env` contains secure Kafka credentials +- [ ] TLS artifacts exist under `docker/kafka/secrets/` +- [ ] Preflight passes: `./scripts/kafka-secure-preflight.sh` + +## Activation +- [ ] Secure mode applied: `./scripts/kafka-enable-secure-mode.sh` +- [ ] Overlay is active: `docker compose -f docker-compose.yml -f docker-compose.secure.yml ps` + +## Smoke validation +- [ ] `./scripts/kafka-secure-smoke.sh` exits with code 0 +- [ ] `kafka`, `kafka-connect`, `backend` are running +- [ ] Backend env has `KAFKA_SECURITY_PROTOCOL=SASL_SSL` +- [ ] Connect env has `CONNECT_SECURITY_PROTOCOL=SASL_SSL` +- [ ] Recent logs have no TLS/SASL handshake/auth failures + +## Functional validation +- [ ] Debezium connector stays healthy +- [ ] CDC events still arrive to backend pipeline +- [ ] No regression on SSE event delivery + +## Rollback validated +- [ ] Plaintext fallback works: `docker compose -f docker-compose.yml up -d` +- [ ] Services recover after rollback + +## Evidence to attach in PR/issue +- [ ] `docker compose ps` output (secure mode) +- [ ] `./scripts/kafka-secure-preflight.sh` output +- [ ] `./scripts/kafka-secure-smoke.sh` output +- [ ] relevant logs for kafka/connect/backend diff --git a/docs/operations/kafka-sasl-ssl-quickstart.md b/docs/operations/kafka-sasl-ssl-quickstart.md index dddbef8..f732eeb 100644 --- a/docs/operations/kafka-sasl-ssl-quickstart.md +++ b/docs/operations/kafka-sasl-ssl-quickstart.md @@ -58,6 +58,12 @@ If preflight fails, fix missing env vars/files and rerun. - Backend starts with `KAFKA_SECURITY_PROTOCOL=SASL_SSL` - Debezium connect worker starts with SASL settings +Run automated smoke check: + +```bash +./scripts/kafka-secure-smoke.sh +``` + ## 5) Rollback to plaintext ```bash diff --git a/scripts/kafka-secure-smoke.sh b/scripts/kafka-secure-smoke.sh new file mode 100755 index 0000000..eb093ff --- /dev/null +++ b/scripts/kafka-secure-smoke.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT_DIR" + +services=(kafka kafka-connect backend) +failed=0 + +echo "[1/4] Checking container status" +for svc in "${services[@]}"; do + if ! docker compose ps "$svc" >/dev/null 2>&1; then + echo " [FAIL] service not found: $svc" + failed=1 + continue + fi + + status="$(docker compose ps --format json "$svc" | tr -d '\n' | sed 's/}\s*{/}\n{/g' | grep -m1 '"Service":"'"$svc"'"' || true)" + if [[ -z "$status" ]]; then + echo " [FAIL] unable to read status: $svc" + failed=1 + continue + fi + + if echo "$status" | grep -q '"State":"running"'; then + echo " [OK] $svc running" + else + echo " [FAIL] $svc not running" + failed=1 + fi +done + +echo "[2/4] Verifying secure env in backend" +backend_env="$(docker compose exec -T backend /bin/sh -lc 'env' 2>/dev/null || true)" +if echo "$backend_env" | grep -q '^KAFKA_SECURITY_PROTOCOL=SASL_SSL$'; then + echo " [OK] backend KAFKA_SECURITY_PROTOCOL=SASL_SSL" +else + echo " [FAIL] backend missing KAFKA_SECURITY_PROTOCOL=SASL_SSL" + failed=1 +fi + +echo "[3/4] Verifying secure env in kafka-connect" +connect_env="$(docker compose exec -T kafka-connect /bin/sh -lc 'env' 2>/dev/null || true)" +if echo "$connect_env" | grep -q '^CONNECT_SECURITY_PROTOCOL=SASL_SSL$'; then + echo " [OK] connect CONNECT_SECURITY_PROTOCOL=SASL_SSL" +else + echo " [FAIL] connect missing CONNECT_SECURITY_PROTOCOL=SASL_SSL" + failed=1 +fi + +echo "[4/4] Scanning logs for obvious auth/ssl failures" +kafka_logs="$(docker compose logs --tail=200 kafka 2>/dev/null || true)" +connect_logs="$(docker compose logs --tail=200 kafka-connect 2>/dev/null || true)" +backend_logs="$(docker compose logs --tail=200 backend 2>/dev/null || true)" +combined_logs="$kafka_logs +$connect_logs +$backend_logs" + +if echo "$combined_logs" | grep -Eiq 'SSLHandshakeException|SaslAuthenticationException|PKIX path building failed|No route to host|Connection refused'; then + echo " [WARN] suspicious errors detected in recent logs" + echo " inspect with: docker compose logs --tail=200 kafka kafka-connect backend" + failed=1 +else + echo " [OK] no obvious TLS/SASL errors in recent logs" +fi + +if [[ "$failed" -ne 0 ]]; then + echo "Secure smoke test FAILED" + exit 1 +fi + +echo "Secure smoke test PASSED"