If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/obsidiandynamics/kafdrop shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4d ago
• 13 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live obsidiandynamics/kafdrop repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/obsidiandynamics/kafdrop.

What it runs against: a local clone of obsidiandynamics/kafdrop — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in obsidiandynamics/kafdrop | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of obsidiandynamics/kafdrop. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/obsidiandynamics/kafdrop.git
#   cd kafdrop
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of obsidiandynamics/kafdrop and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "obsidiandynamics/kafdrop(\\.git)?\\b" \\
  && ok "origin remote is obsidiandynamics/kafdrop" \\
  || miss "origin remote is not obsidiandynamics/kafdrop (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/kafdrop/Kafdrop.java" \\
  && ok "src/main/java/kafdrop/Kafdrop.java" \\
  || miss "missing critical file: src/main/java/kafdrop/Kafdrop.java"
test -f "src/main/java/kafdrop/service/KafkaMonitor.java" \\
  && ok "src/main/java/kafdrop/service/KafkaMonitor.java" \\
  || miss "missing critical file: src/main/java/kafdrop/service/KafkaMonitor.java"
test -f "src/main/java/kafdrop/service/KafkaMonitorImpl.java" \\
  && ok "src/main/java/kafdrop/service/KafkaMonitorImpl.java" \\
  || miss "missing critical file: src/main/java/kafdrop/service/KafkaMonitorImpl.java"
test -f "src/main/java/kafdrop/controller/TopicController.java" \\
  && ok "src/main/java/kafdrop/controller/TopicController.java" \\
  || miss "missing critical file: src/main/java/kafdrop/controller/TopicController.java"
test -f "src/main/java/kafdrop/config/KafkaConfiguration.java" \\
  && ok "src/main/java/kafdrop/config/KafkaConfiguration.java" \\
  || miss "missing critical file: src/main/java/kafdrop/config/KafkaConfiguration.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/obsidiandynamics/kafdrop"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Kafdrop is a lightweight Spring Boot web UI for monitoring and managing Apache Kafka clusters. It provides real-time visibility into brokers, topics, partitions, consumer groups, and message contents (supporting JSON, Avro, Protobuf, and plain text encodings), plus the ability to create topics and view ACLs—all without requiring a ZooKeeper connection as of version 3.10.0. Monolithic Spring Boot application with clear layered structure: src/main/java/kafdrop/config/ contains configuration modules (Kafka, CORS, Health, OAS/OpenAPI, message format), UI templates in FreeMarker/Mustache, and a Docker build pipeline. Static assets (SCSS, JavaScript, CSS) are bundled with the JAR. Helm charts in chart/ enable Kubernetes deployment; docker-compose/ provides local testing setup.

DevOps engineers, platform teams, and Kafka operators who need a quick, browser-based way to inspect cluster state, debug consumer lag issues, and browse message payloads without writing custom admin scripts. Also used by developers integrating with Kafka to verify topic setup and message formats.

Production-ready and actively maintained. The project is a modern reboot (Kafdrop 3.x+) now running on Java 17+, Spring Boot 3.5.8, and recent Kafka clients (kafka-libs 8.2.0). It has CI/CD pipelines (GitHub Actions workflows), Docker and Helm packaging, and multi-platform builds (linux/amd64, linux/arm64). Last activity is recent (4.2.1-SNAPSHOT version suggests active development).

Low-to-moderate risk for production use. The codebase is well-structured with configuration management, but it's a single-maintainer project (obsidiandynamics org). Dependencies are managed through Maven with Confluent and Central repositories, and Testcontainers integration suggests good test coverage. No obvious deprecated technologies, though the jump to Java 17+ requirement may affect older deployment environments. Monitor release cadence for security patches.

Version 4.2.1 is in active development (SNAPSHOT). The codebase reflects recent Spring Boot 3.5.8 adoption, Protobuf 3.25.9 support, and Testcontainers 2.0.5 integration. GitHub workflows include automated dependency updates (dependabot), issue closing, and master/PR pipelines, suggesting ongoing maintenance and CI maturity.

git clone https://github.com/obsidiandynamics/kafdrop.git
cd kafdrop
./mvnw clean package
java --add-opens=java.base/sun.nio.ch=ALL-UNNAMED \
  -jar target/kafdrop-4.2.1-SNAPSHOT.jar \
  --kafka.brokerConnect=localhost:9092

Then open http://localhost:9000 in your browser. Or use the provided docker-compose/kafka-kafdrop/docker-compose.yaml to spin up Kafka + Kafdrop together.

Daily commands:

./mvnw spring-boot:run -Dspring-boot.run.arguments='--kafka.brokerConnect=localhost:9092'

Or build first then run the JAR (see howDoIStart). For local Kafka cluster testing, use docker-compose/kafka-kafdrop/docker-compose.yaml. Kubernetes deployments use the Helm chart in chart/ with values.yaml customization.

• src/main/java/kafdrop/Kafdrop.java — Main Spring Boot entry point; defines application initialization and core setup every contributor must understand.
• src/main/java/kafdrop/service/KafkaMonitor.java — Central abstraction for Kafka cluster monitoring; all topic, broker, and consumer operations depend on this interface.
• src/main/java/kafdrop/service/KafkaMonitorImpl.java — Primary implementation of cluster monitoring using Kafka admin and consumer clients; handles all broker and topic metadata.
• src/main/java/kafdrop/controller/TopicController.java — Request handler for topic-related endpoints; demonstrates controller patterns and message deserialization flow.
• src/main/java/kafdrop/config/KafkaConfiguration.java — Kafka client configuration and bean setup; critical for understanding how connections are established.
• pom.xml — Maven project definition with Spring Boot, Kafka client, and serialization dependencies; defines build and runtime requirements.
• src/main/java/kafdrop/util/Deserializers.java — Message format abstraction layer; handles Avro, Protobuf, MsgPack, and JSON deserialization strategies.

Add a new REST endpoint

1. Create a new method in an existing controller (e.g., TopicController) or create a new controller class annotated with @RestController and @RequestMapping (src/main/java/kafdrop/controller/YourNewController.java)
2. Use @GetMapping, @PostMapping, or @RequestMapping annotations to define the HTTP route and method (src/main/java/kafdrop/controller/YourNewController.java)
3. Inject KafkaMonitor or other service beans via constructor to access Kafka cluster data (src/main/java/kafdrop/controller/YourNewController.java)
4. Return a data object from the model package (e.g., TopicVO, ConsumerVO) or create a new VO class in src/main/java/kafdrop/model/ (src/main/java/kafdrop/model/YourResponseVO.java)
5. If a custom exception can occur, handle it in KafkaExceptionHandler.java with a new @ExceptionHandler method (src/main/java/kafdrop/controller/KafkaExceptionHandler.java)

Add support for a new message format

1. Create a new class extending MessageDeserializer interface in the util package (src/main/java/kafdrop/util/YourFormatDeserializer.java)
2. Implement deserialize(byte[] data) to return a deserialized Object or String representation (src/main/java/kafdrop/util/YourFormatDeserializer.java)
3. Register the deserializer in Deserializers.java getDeserializer() method by checking a MessageFormat enum value (src/main/java/kafdrop/util/Deserializers.java)
4. Add a new MessageFormat enum value in src/main/java/kafdrop/util/MessageFormat.java if creating a new format type (src/main/java/kafdrop/util/MessageFormat.java)
5. Update SearchMessageForm or SearchMessageFormForJson to accept the new format as a query parameter or request body field (src/main/java/kafdrop/form/SearchMessageForm.java)

Add a new monitoring metric or property

1. Add a new field to the relevant model VO class (e.g., TopicVO, BrokerVO, ConsumerVO) to hold the metric (src/main/java/kafdrop/model/TopicVO.java)
2. Populate the field in KafkaMonitorImpl.java where the model is constructed, using AdminClient or Consumer API calls (src/main/java/kafdrop/service/KafkaMonitorImpl.java)
3. Expose the metric via a controller endpoint in TopicController, ClusterController, or BrokerController (src/main/java/kafdrop/controller/TopicController.java)
4. The metric will be automatically serialized to JSON by ObjectMapperConfig (src/main/java/kafdrop/config/ObjectMapperConfig.java)

Integrate with a new Kafka Schema Registry or metadata service

1. Create a new configuration class in src/main/java/kafdrop/config/ to instantiate and configure the client bean (src/main/java/kafdrop/config/YourRegistryConfiguration.java)
2. Inject the client bean into a new deserializer or into MessageInspector.java to fetch schema on demand (src/main/java/kafdrop/service/MessageInspector.java)
3. Add configuration properties to application.properties or application.yml (Spring Boot loads these automatically) (src/main/resources/application.yml)
4. Update Deserializers.java to use the new schema service when determining how to deserialize messages (src/main/java/kafdrop/util/Deserializers.java)

JVM flag required: The --add-opens=java.base/sun.nio.ch=ALL-UNNAMED flag is mandatory for Java 17+; forgetting it will cause cryptic NIO-related failures. Port configuration: Both --server.port and --management.server.port may need to be set for Spring Boot management endpoints. Kafka broker connectivity: Kafdrop uses the Kafka Admin API; ensure brokers are reachable and SASL/TLS is configured if needed. Schema Registry optional: Schema Registry integration is optional (--schemaregistry.connect); if not configured, Avro/Protobuf message decoding will be limited. ZooKeeper not needed: Older Kafdrop versions required ZooKeeper; 3.10.0+ does not—do not provision it unless using an ancient version.

• Kafka Admin API — Kafdrop uses the Kafka Admin API (not ZooKeeper) to discover cluster topology, topic metadata, consumer group offsets, and ACLs—understanding this API is essential for modifying broker queries or debugging connectivity issues
• Consumer Group Lag Calculation — A core feature Kafdrop displays is per-partition and aggregate consumer lag (difference between committed offset and latest offset); this requires understanding offset tracking and LSO (Log Start Offset)
• Message Serialization Formats (Avro, Protobuf, JSON) — Kafdrop's ability to decode and display message contents depends on pluggable format handlers; the MessageFormatConfiguration suggests a strategy pattern for different serialization codecs
• Spring Boot Actuator & Health Checks — Kafdrop uses Spring Boot health checks (HealthCheckConfiguration) for liveness/readiness probes in Kubernetes; modifying cluster connectivity detection affects pod scheduling
• SASL & TLS Broker Authentication — Production Kafka clusters require SASL/TLS; Kafdrop's KafkaConfiguration must handle authentication credentials—misconfigurations are a common source of failed deployments
• Helm Chart Templating — Kafdrop's Helm chart in chart/ uses Go templating to generate Kubernetes manifests; understanding Helm values precedence and template conditionals is essential for Kubernetes deployments
• Multi-Platform Docker Builds — The Dockerfile is built for both linux/amd64 and linux/arm64 (see docker.platforms property); this requires buildx and multi-stage builds—ARM adoption is increasingly common (Apple Silicon, AWS Graviton)

• kafka-ui/kafka-ui — Direct Kafdrop alternative—React-based Kafka Web UI with similar features (topic browsing, consumer lag, message inspection) but different tech stack and UI approach
• confluentinc/schema-registry — Optional companion service that Kafdrop integrates with via --schemaregistry.connect for Avro and Protobuf message schema management and decoding
• conduktor/conduktor-public — Another Kafka monitoring tool with desktop and web UI; overlapping use cases but different deployment model (Electron-based desktop vs. web-only)
• Apache/kafka — The core Kafka broker project that Kafdrop targets; Kafdrop depends on Kafka Admin API (kafka-clients) and must track Kafka version compatibility
• spring-projects/spring-boot — Foundational framework; Kafdrop is built entirely on Spring Boot 3.5.8 and must track Spring releases for security patches and feature parity

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Kafka message search functionality (SearchMessageForm & SearchMessageFormForJson)

The repo has SearchMessageForm.java and SearchMessageFormForJson.java in src/main/java/kafdrop/form/ but there's no visible test coverage for these critical message search features. Given that message browsing is a core Kafdrop feature, adding integration tests using testcontainers (already a dependency at v2.0.5) would validate JSON/binary message parsing and search logic across different Kafka message formats.

• [ ] Create src/test/java/kafdrop/form/SearchMessageFormTest.java with unit tests for form validation
• [ ] Create src/test/java/kafdrop/form/SearchMessageFormForJsonTest.java with JSON parsing edge cases
• [ ] Create src/test/java/kafdrop/controller/MessageControllerIntegrationTest.java using testcontainers to spin up a real Kafka broker
• [ ] Add test cases for malformed JSON, empty messages, and special character handling in searches

Add schema validation and error handling tests for ProtobufDescriptorConfiguration

The repo has src/main/java/kafdrop/config/ProtobufDescriptorConfiguration.java for Protobuf support, but there are no visible tests validating descriptor loading, invalid descriptor files, or schema registry failures. This is critical for users relying on Protobuf message deserialization. Adding tests would prevent regressions when handling malformed .proto files or missing descriptors.

• [ ] Create src/test/java/kafdrop/config/ProtobufDescriptorConfigurationTest.java
• [ ] Add test resources in src/test/resources/ with valid and invalid .proto descriptor files
• [ ] Test descriptor loading from filesystem, URLs, and error cases (missing files, parsing errors)
• [ ] Add tests for SchemaRegistryConfiguration integration with Protobuf descriptors

Create a GitHub Actions workflow for security vulnerability scanning (OWASP Dependency Check)

The repo has CI workflows (.github/workflows/master.yml and pull_request.yml) but no automated security scanning for vulnerable dependencies. Given the project manages Kafka connections and processes user input (message search), adding OWASP Dependency Check would catch CVEs in transitive dependencies before release. This is especially important since the pom.xml has multiple external repositories (confluent, central) and protobuf/testcontainers dependencies.

• [ ] Create .github/workflows/security-scan.yml with OWASP Dependency-Check action
• [ ] Configure it to run on pull requests and scheduled nightly builds
• [ ] Add suppressions file (dependency-check-suppressions.xml) for known false positives
• [ ] Add security scan badge to README.md and document results in CONTRIBUTING.md

• Add integration tests for ACL viewing functionality—src/main/java/kafdrop/config/ has HealthCheckConfiguration and CorsConfiguration but no visible test coverage pattern; write Testcontainers-based tests to validate ACL retrieval.
• Improve message format auto-detection UI—the MessageFormatConfiguration.java exists but there's no visible README documentation on supported encodings or how to configure format preferences; add a feature to display detected format with toggle buttons.
• Document required JVM flags in Helm chart—chart/values.yaml and chart/templates/deployment.yaml should include the --add-opens flag in container args with explanatory comments; many Kubernetes users skip the README and hit this trap.

• High · Outdated Spring Boot Version with Known Vulnerabilities — pom.xml (parent version 3.5.8). Spring Boot 3.5.8 is an older version that may contain known security vulnerabilities. The project uses spring-boot-starter-parent 3.5.8 which is not the latest stable release. Spring Boot 3.x has reached newer patch versions with security fixes. Fix: Upgrade to the latest Spring Boot 3.x stable version (currently 3.2.x or later) to receive security patches and updates.
• High · Protobuf Dependency at Version 3.25.9 — pom.xml (protobuf.version property: 3.25.9). Protobuf 3.25.9 is several minor versions behind the latest releases. Protobuf has had multiple security advisories in recent versions related to parsing and validation. Using an older version may expose the application to known CVEs. Fix: Update to the latest stable Protobuf version (3.27.x or later) to ensure all security patches are applied.
• Medium · JAAS Configuration File Exposed in Repository — kaas_local_jaas.conf. File 'kaas_local_jaas.conf' is present in the repository root. While marked as 'local', JAAS configuration files may contain sensitive authentication settings or examples that could be misused if the repository is public. Fix: Move sensitive configuration files outside the repository or add them to .gitignore. Use environment variables or secure vaults for authentication configurations.
• Medium · Potential CORS Configuration Issues — src/main/java/kafdrop/config/CorsConfiguration.java. CorsConfiguration.java exists in the configuration directory. CORS misconfiguration is a common security issue that could allow unauthorized cross-origin requests. The actual implementation was not visible, but this requires careful review. Fix: Review CORS configuration to ensure it restricts origins appropriately. Avoid using wildcard '*' for allowed origins in production. Implement strict origin validation.
• Medium · Schema Registry Configuration Without Apparent Security Controls — src/main/java/kafdrop/config/SchemaRegistryConfiguration.java. SchemaRegistryConfiguration.java is present but security mechanisms for connecting to Schema Registry are not visible. Schema Registry connections may require authentication and encryption that should be enforced. Fix: Ensure Schema Registry connections use HTTPS/TLS and implement proper authentication (API keys, SASL, or OAuth). Validate certificate chains and reject untrusted certificates.
• Medium · Kafka Configuration Lacks Visible Security Enforcement — src/main/java/kafdrop/config/KafkaConfiguration.java. KafkaConfiguration.java manages Kafka client configuration. Without visible code, it's unclear if security features like SASL, SSL/TLS, and authentication are properly enforced or left as optional configurations. Fix: Enforce SASL_SSL or similar security protocols by default. Validate and require certificate verification. Document secure configuration requirements clearly.
• Medium · Message Search Functionality Vulnerable to Injection Attacks — src/main/java/kafdrop/form/SearchMessageForm.java and SearchMessageFormForJson.java. SearchMessageForm.java and SearchMessageFormForJson.java handle user input for message searching. Without visible sanitization or parameterized query implementation, this could be vulnerable to injection attacks depending on how the search is executed. Fix: Implement strict input validation and sanitization. Use parameterized queries or pre-compiled filters. Apply output encoding when displaying search results to prevent XSS.
• Low · Docker Image Platform Configuration — pom.xml (docker.platforms property) and src/main/docker/Dockerfile. The docker.platforms property specifies linux/amd64,linux/arm64. While not a direct security issue, ensure base images used in Dockerfile are from trusted registries and regularly scanned for vulnerabilities. Fix: Use specific base image versions (avoid 'latest'). Implement container image scanning in CI/CD. Regular dependency updates and vulnerability scanning of Docker images.
• Low · Missing SecurityHeaders Configuration — undefined. No visible security headers configuration (X- Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.