Release Guide

Release Notes

Unreleased (RELEASE-1a)

Added

.golangci.yml with gosec security linter enabled
Coverage gate in CI pipeline
Environment variable expansion in properties files (${VAR} syntax via os.ExpandEnv)
File permission warnings (warnInsecurePermissions) for properties files with mode > 0600
Fuzz testing: 4 fuzz targets covering auth, properties, SSRF URL validation, JDBC URL parsing
Signal handling: SIGINT/SIGTERM gracefully cancel the scan context
scanConfig struct encapsulates all scan parameters
runScan() function replaces goto endScan pattern; all phases guarded by ctx.Done()
checkRESTProxy() extracted as a standalone testable function
478 test cases total (up from ~128), 47.8% total coverage

Changed

goto endScan removed; replaced by runScan() function with structured early-return via context cancellation
isLinkLocalIP expanded to full SSRF deny list: 14 CIDR ranges (loopback, link-local, CGN, TEST-NETs, multicast, reserved, broadcast) + 4 warn ranges (RFC1918, ULA)
REST Proxy check now properly guarded by ctx.Done() inside runScan() (previously ran after endScan label)

Security

AI client CheckRedirect handler validates redirect targets against SSRF rules
Bounded HTTP reads everywhere via io.LimitReader (1MB for Schema Registry, REST Proxy, AI, Connect API)
REST Proxy extracted to checkRESTProxy() so it can be tested with httptest

Previously Unreleased (now in 0.2.0)

Features

Connector Config Probe (SPEC-002): Probe MongoDB, DB2, and PostgreSQL targets by reading connector configs from Kafka Connect REST API or local JSON files. Layered diagnostics (DNS -> TCP -> TLS -> Application Protocol) with actionable hints.
- New flags: --connect-url, --connector-name, --connector-config, --connect-basic-auth, --connect-bearer-token, --connect-ca-cert
- Environment variable fallback: KSHARK_CONNECT_AUTH, KSHARK_CONNECT_TOKEN
- MongoDB probe via official driver (SRV, SCRAM-SHA-256, TLS, ping, collection check)
- PostgreSQL probe via pgx (wire protocol v3, all auth mechanisms)
- DB2 probe via custom DRDA wire protocol (EXCSAT/ACCSEC/SECCHK/ACCRDB)
- JDBC URL parsing for DB2 and PostgreSQL connector configs
- Connector-only mode: run without -props when only probing connector targets
JAAS config credential extraction: kshark now automatically extracts username and password from sasl.jaas.config when sasl.username / sasl.password are not explicitly set. This makes kshark compatible with standard Java Kafka client properties files that only use sasl.jaas.config for authentication (e.g., files generated by Confluent Cloud).
Improved AI Analysis Prompt (SPEC-001): Layered reasoning hints, enhanced JSON schema with likelyCategory, confidence, severity, and evidence fields. Defensive re-redaction before AI export.

Security

SSRF Protection: Two-tier SSRF validation for Schema Registry, REST Proxy, and Connect API. Blocks loopback/link-local/cloud metadata (DENY). Warns on RFC1918 private IPs (WARN) since PrivateLink targets are common. Redirect-based SSRF bypass prevention via CheckRedirect handler.
Credential Redaction: sasl.jaas.config now redacted in all output (was previously leaking JAAS credentials). Added bearer, token, credential keyword matching. Credential scrubbing in database probe error messages.
Connect API Security: URL scheme validation (http/https only), response body limit (1MB), link-local IP blocking, redirect protection.

This document describes how to build, test, and publish releases of kshark.

Prerequisites

Tool	Version	Purpose
Go	1.23+	Compile the binary
GoReleaser	latest	Cross-platform builds and GitHub Releases
Docker	20+	Container image builds (optional)
GNU Make	3.81+	Local build shortcuts (optional)

Local Development

Build

# Quick build (uses make)
make build

# Or directly with go
CGO_ENABLED=0 go build -o kshark ./cmd/kshark

# Build with version metadata injected
CGO_ENABLED=0 go build \
  -ldflags "-s -w -X main.version=dev -X main.commit=$(git rev-parse --short HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o kshark ./cmd/kshark

Test and Vet

make vet       # static analysis
make test      # tests with race detector
make all       # vet + build

Local Snapshot Release

Build all platform binaries locally without publishing:

make snapshot
# or
goreleaser release --snapshot --clean

This produces archives for every OS/arch combination under dist/.

Docker

make docker
# or
docker build -t kshark:latest .

Makefile Targets

Target	Description
`make build`	Build the kshark binary with version/commit/date ldflags
`make test`	Run tests with `-race -timeout 120s`
`make vet`	Run `go vet ./...`
`make all`	Vet then build
`make clean`	Remove the binary and `dist/` directory
`make snapshot`	GoReleaser snapshot build (no publish)
`make docker`	Build Docker image tagged with version and `latest`
`make help`	List all targets

CI Pipeline

The GitHub Actions workflow (.github/workflows/build-and-release.yml) runs two jobs:

Build & Test (every push and PR to `main`)

Checkout code
Set up Go 1.23
go mod download
go vet ./...
go build -o kshark ./cmd/kshark
go test ./... -v -race -timeout 120s

Release (only on `v*` tags, after Build & Test passes)

Checkout with full git history (fetch-depth: 0)
Set up Go 1.23
Run GoReleaser with GITHUB_TOKEN

GoReleaser handles:

Cross-compilation for Linux, macOS, Windows (amd64 + arm64)
Static binaries (CGO_ENABLED=0)
Archive creation (.tar.gz for Unix, .zip for Windows)
SHA256 checksum file (checksums.txt)
GitHub Release page with auto-generated changelog
Bundling of LICENSE, README.md, client.properties.example, ai_config.json.example, and web/templates/

Publishing a Release

Step 1 — Ensure `main` is clean

git checkout main
git pull origin main
make all        # vet + build
make test       # run tests

Step 2 — Tag the release

Use semantic versioning. Tags prefixed with -rc, -beta, or -alpha are automatically marked as pre-releases.

# Stable release
git tag v0.31.0

# Pre-release
git tag v0.31.0-rc1

Step 3 — Push the tag

git push origin v0.31.0

This triggers the CI workflow. The Build & Test job runs first; if it passes, the Release job runs GoReleaser, which creates the GitHub Release with all binaries and checksums.

Step 4 — Verify

Go to Releases on GitHub and confirm the new release appears.

Download a binary for your platform and verify:

tar -xzf kshark_0.31.0_linux_amd64.tar.gz
./kshark --version
# Expected: kshark version 0.31.0 (commit abc1234, built 2025-...)
sha256sum -c checksums.txt

Release Artifacts

Each release produces the following files on the GitHub Releases page:

File	Description
`kshark_<ver>_linux_amd64.tar.gz`	Linux x86-64 binary
`kshark_<ver>_linux_arm64.tar.gz`	Linux ARM64 binary
`kshark_<ver>_darwin_amd64.tar.gz`	macOS Intel binary
`kshark_<ver>_darwin_arm64.tar.gz`	macOS Apple Silicon binary
`kshark_<ver>_windows_amd64.zip`	Windows x86-64 binary
`kshark_<ver>_windows_arm64.zip`	Windows ARM64 binary
`checksums.txt`	SHA256 checksums for all archives

Every archive also includes:

LICENSE
README.md
client.properties.example
ai_config.json.example
web/templates/report_template.html

Version Injection

The build injects three variables at link time via -ldflags:

Variable	Source	Example
`main.version`	Git tag (GoReleaser) or `git describe` (Makefile)	`0.31.0`
`main.commit`	Git short SHA	`ae0ec21`
`main.date`	Build timestamp (UTC)	`2025-06-15T10:30:00Z`

These values are printed by kshark --version and included in reports.

Changelog

GoReleaser auto-generates the changelog from commit messages between the previous tag and the new tag. Commits are grouped:

Group	Commit prefix
Features	`feat:` or `feat(scope):`
Bug Fixes	`fix:` or `fix(scope):`
Other	Everything else

Commits starting with docs:, test:, or chore: are excluded from the changelog.

Hotfix Process

For urgent fixes against a released version:

git checkout v0.31.0           # start from the release tag
git checkout -b hotfix/issue   # create a hotfix branch
# ... make and test changes ...
git commit -m "fix: description of the fix"
git checkout main
git merge hotfix/issue
git tag v0.31.1
git push origin main v0.31.1

Docker Release

Docker images are built locally and are not currently published to a registry by the CI pipeline. To publish:

make docker
docker tag kshark:latest your-registry/kshark:0.31.0
docker tag kshark:latest your-registry/kshark:latest
docker push your-registry/kshark:0.31.0
docker push your-registry/kshark:latest

Release Guide

Release Notes

Unreleased (RELEASE-1a)

Added

Changed

Security

Previously Unreleased (now in 0.2.0)

Features

Security

Prerequisites

Local Development

Build

Test and Vet

Local Snapshot Release

Docker

Makefile Targets

CI Pipeline

Build & Test (every push and PR to main)

Release (only on v* tags, after Build & Test passes)

Publishing a Release

Step 1 — Ensure main is clean

Step 2 — Tag the release

Step 3 — Push the tag

Step 4 — Verify

Release Artifacts

Version Injection

Changelog

Hotfix Process

Docker Release

Build & Test (every push and PR to `main`)

Release (only on `v*` tags, after Build & Test passes)

Step 1 — Ensure `main` is clean